apyhub
Back
▣ FILE MANIPULATION · IMAGE PROCESSING

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)

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

Request Body

ParameterTypeDescription
fileBinaryPortrait image file. Binary upload. Maximum size: 20 MB.

Response

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

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.

Similar APIs

Closest matches in the catalog based on this service.

CALLExtract Hair Region from Image APIDosvak LLCCALLRestore and enhance detected face regions APIDosvak LLCCALLDetect Faces from Image File APIDosvak LLCCALLRemove Background from Images APIApyHub

From the blog

Reads that touch this API.

curl HEAD Request: Check Headers Without DownloadingSep 29, 2026Top Data Extraction APIs for Developers in 2025Jul 9, 2026Face Detection using AI: Use Cases, Benefits, and ImplementationJul 9, 2026Top Image Editing APIs for 2026Sep 18, 2026