▣ ARTIFICIAL INTELLIGENCE · IMAGE PROCESSING

Generate Image Foreground Mask API

What it does

Generate Image Foreground Mask API lets you isolate a subject from an image and return either a mask or a background-removed image. Send a public image URL or base64-encoded image data, and choose whether you want JSON metadata or image bytes back.

Use the subject mask endpoint when you need a grayscale cutout for compositing, edge cleanup, or downstream image analysis. The response includes the output format, media type, width, height, byte size, data URI, subject bounding box, foreground ratio, and the quality setting used. If nothing is found, bbox is null.

Use the background-removal endpoint when you need a ready-to-use subject image. You can crop to the subject's bounding box, add padding, limit the output size, and pick best or fast quality. Output can be json, png, webp, or jpeg; JPEG requires an opaque background color in #RRGGBB form. This is a good fit for product photos, profile pictures, asset pipelines, and any workflow that needs transparent backgrounds or a consistent subject crop.

Both endpoints accept images up to 20 MB and return a data URI alongside the image metadata, so you can pass results straight into your storage, preview, or rendering pipeline.

POST

Get the subject mask

https://api.eu.apyhub.com/callable-labs/background-removal/v1/background/mask

QUICKSTART

GUIDE

Quickstart

Send a public image URL to remove its background and return mask metadata in JSON.

curl -X POST "https://api.eu.apyhub.com/callable-labs/background-removal/v1/background/mask" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "url": "https://assets.apyhub.com/samples/cat.jpg"
    }
  }'

What you'll get back

Returns a JSON object with these top-level fields: format and media_type are strings, width and height are output dimensions in pixels, bytes is the payload size, data_uri is a data:<media_type>;base64,... string, bbox is either an object with x, y, width, and height or null, foreground_ratio is a number between 0 and 1, and quality is "best" or "fast".

{
  "format": "json",
  "media_type": "image/png",
  "width": 800,
  "height": 600,
  "bytes": 124532,
  "data_uri": "data:image/png;base64,iVBORw0KGgoAAA...",
  "bbox": { "x": 120, "y": 45, "width": 540, "height": 510 },
  "foreground_ratio": 0.42,
  "quality": "best"
}

TRY ITLIVE · 600 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Generates a subject mask for an input image. The request accepts an image source and optional output controls, and the response returns mask metadata plus either a data URI or PNG-oriented output depending on the requested format.

Request Body

Parameter	Type	Mandatory	Description
crop	Boolean	No	Crop the result to the subject's bounding box. Default: `false`.
image	Object	Yes	Image source object. Contains `url` and/or `base64`; see nested fields.
image.url	String	No	Public http(s) URL of the image. Must be ≤ 20 MB; private and internal addresses are refused.
image.base64	String	No	The image as base64, including a `data:` URI if desired. Must be ≤ 20 MB decoded.
format	ENUM	No	Output format. Allowed values: `json`, `png`. Default: `json`. `json` returns metadata plus a PNG data URI; `png` returns the 8-bit grayscale mask.
padding	Integer	No	Pixels kept around the subject when `crop` is true. Default: `0`; minimum: `0`, maximum: `1000`.
quality	ENUM	No	Output quality. Allowed values: `best`, `fast`. Default: `best`. `best` prioritizes detail; `fast` is suitable for previews.
max_size	Integer	No	Longest side of the output in pixels. Default: original size; minimum: `64`, maximum: `4096`.

Response

Returns a JSON object with format, media_type, width, height, bytes, data_uri, bbox, foreground_ratio, and quality fields. bbox is either an object with x, y, width, and height, or null when nothing was found.

Parameter	Type	Mandatory	Description
bbox	Object	Yes	Subject bounding box in the original image, or `null` when nothing was found.
bbox.x	Integer	Yes (if `bbox` is not null)	X coordinate of the bounding box.
bbox.y	Integer	Yes (if `bbox` is not null)	Y coordinate of the bounding box.
bbox.width	Integer	Yes (if `bbox` is not null)	Width of the bounding box.
bbox.height	Integer	Yes (if `bbox` is not null)	Height of the bounding box.
bytes	Integer	Yes	Size of the output in bytes.
width	Integer	Yes	Output width in pixels.
format	String	Yes	Encoding of `data_uri`.
height	Integer	Yes	Output height in pixels.
quality	ENUM	Yes	Quality used for the result. Allowed values: `best`, `fast`.
data_uri	String	Yes	`data:<media_type>;base64,…`
media_type	String	Yes	Media type of the returned data URI.
foreground_ratio	Number	Yes	Share of the original image covered by the subject, from `0` to `1`.

▣ 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.

CALLChange Background of Images APIApyHub CALLRemove Background from Images APIApyHub CALLCompress Images APIApyHub CALLGenerate Text to Image Job APIMasterA AI

From the blog

Reads that touch this API.

Exploring the Top Video Thumbnail ( Preview) APIsJul 9, 2026 Generating Video Thumbnails with ApyHub’s API (Go Guide)Aug 7, 2026 Generating Thumbnails from Videos : A step-by-step guide in NodeJSJul 9, 2026 Video Thumbnails for SEO: How They Lift CTR, and How to Generate Them with an APISep 22, 2026