apyhub

Extract Head Region from Image API

What it does

Head Region Extractor takes a portrait image and returns the head and shoulders area with transparency. Send a single binary file in the request body, and optionally tune padding in the query to control how much of the surrounding area is kept around the subject.

Use it when you need a clean cutout for avatars, profile cards, staff directories, ID-style imagery, or any workflow that needs a subject isolated from the background. The service is designed for portrait photos and the output is a binary image, ready to store, forward, or post-process in your own pipeline.

The only input is the uploaded image file, capped at 20 MB, plus the optional padding value. The response is an image with transparency, so you can place the extracted head and shoulders onto different backgrounds without manual masking.

If your product handles user photos at scale, Head Region Extractor is a straightforward way to standardize portraits before resizing, compositing, or approval workflows.

POST
Extract a head/shoulders region with transparency
https://api.eu.apyhub.com/dosvak/extract-head-region

QUICKSTART

GUIDE

Quickstart

Upload a portrait image to extract the head region, with the default padding.

curl -X POST "https://api.eu.apyhub.com/dosvak/extract-head-region?padding=0.42" \
  -H "apy-token: $APY_TOKEN" \
  -F "file=@/path/to/portrait.jpg"

What you'll get back

Returns a binary file (string with format: binary) containing the extracted head region.

TRY ITLIVE · 100 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.
body*
Portrait image

About this endpoint

What it does

Extracts a head/shoulders region from a portrait image and returns the result as a binary file with transparency. The request uploads one image file and can optionally adjust the padding used around the extracted region.

Query Parameter(s)

AttributeTypeMandatoryDescription
paddingNumberNoControls the padding around the extracted head/shoulders region. Minimum 0.1, maximum 0.9, default 0.42.

Request Body

ParameterTypeMandatoryDescription
fileStringYesPortrait image file. Binary upload. Maximum size: 20 MB.

Response

Returns a binary file containing the extracted head/shoulders region with transparency.

Query parameters

Name
Type
Description
paddingOPTIONAL
number
—
DEFAULT 0.42

Body

Name
Type
Description
bodyREQUIRED
object
—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.