▣ MEDIA KIT

Remove Image Background with Advanced Controls API

What it does

The Background Removal API removes the background from an image and returns the cut-out subject. Send the image in image, as a public URL or base64 data, and get back a transparent PNG, a WebP, a JPEG or JSON metadata.

Set format to json (default), png, webp or jpeg. JSON returns a PNG data URI with the metadata. Set background to transparent (default) or a solid #RRGGBB color. JPEG needs a solid color because it has no transparency. Set crop to true to trim the result to the subject, and add padding (0 to 1000 pixels) to keep space around it. Choose quality as best (default) or fast, and use max_size to limit the output size.

The response includes the format, media_type, width, height, bytes, quality and foreground_ratio, the share of the image covered by the subject. It also returns the subject bbox in the original image, or null when no subject is found.

Teams use the Background Removal API to remove the background from product photos and make profile pictures on a plain color. Online stores use it to prepare listing images and crop catalog shots to the subject.

For a grayscale mask of the subject instead of the cutout, use the Generate Image Foreground Mask API. To read text in the image, use the Image & PDF OCR to Markdown API.

POST

Remove the background

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

QUICKSTART

GUIDE

Quickstart

Remove the background from an image URL and return the result as JSON metadata.

curl -X POST "https://api.eu.apyhub.com/callable-labs/background-removal/v1/background/remove" \
  -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 format, media_type, width, height, bytes, data_uri, bbox, foreground_ratio, and quality.

format (string): encoding of data_uri
media_type (string): the output media type
width / height (integer): output dimensions in pixels
bytes (integer): output size in bytes
data_uri (string): a data:<media_type>;base64,… payload
bbox (object or null): subject bounding box in the original image
foreground_ratio (number): share of the original image covered by the subject
quality (string): best or fast

{
  "format": "json",
  "media_type": "image/png",
  "width": 1200,
  "height": 900,
  "bytes": 123456,
  "data_uri": "data:image/png;base64,...",
  "bbox": { "x": 120, "y": 80, "width": 900, "height": 700 },
  "foreground_ratio": 0.42,
  "quality": "best"
}

TRY ITLIVE · 800 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

Removes the background from an input image and returns result metadata plus the processed image payload. The request accepts either a public image URL or base64-encoded image data, along with optional output and cropping settings.

Request Body

Parameter	Type	Description
image	Object	Image source. Provide one of `image.url` or `image.base64`.
image.url	String	Public http(s) URL of the image (≤ 20 MB). Private and internal addresses are refused.
image.base64	String	The image as base64 (a `data:` URI is fine), ≤ 20 MB decoded.
crop	Boolean	Crop the result to the subject's bounding box. Default: `false`.
format	ENUM	Output encoding. Allowed values: `json`, `png`, `webp`, `jpeg`. Default: `json`. `json` returns metadata plus a PNG data URI. `png` and `webp` return the image bytes. `jpeg` needs an opaque `background`.
padding	Integer	Pixels kept around the subject when `crop` is true. Default: `0`. Minimum: `0`. Maximum: `1000`.
quality	ENUM	Processing quality. Allowed values: `best`, `fast`. Default: `best`. `best` prioritizes detail. `fast` is suitable for previews.
max_size	Integer	Longest side of the output in pixels. Default: null (original size). Minimum: `64`. Maximum: `4096`.
background	String	Background color to place the subject on. Default: `transparent`. Allowed values: `transparent` or a hex color in `#RRGGBB` format.

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; the other fields describe the generated output and its encoding.

Parameter	Type	Description
bbox	Object	Subject bounding box in the original image, or `null` when nothing was found.
bbox.x	Integer	X coordinate of the bounding box.
bbox.y	Integer	Y coordinate of the bounding box.
bbox.width	Integer	Width of the bounding box.
bbox.height	Integer	Height of the bounding box.
bytes	Integer	Size of the output in bytes.
width	Integer	Output width in pixels.
format	String	Encoding of `data_uri`.
height	Integer	Output height in pixels.
quality	ENUM	Processing quality used in the result. Allowed values: `best`, `fast`.
data_uri	String	`data:<media_type>;base64,…`
media_type	String	MIME type of the returned data.
foreground_ratio	Number	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.

CALLGenerate Image Foreground Mask APICallable Labs CALLRemove Background from Images APIApyHub CALLChange Background of Images APIApyHub CALLRemove Image Metadata APIApyHub

From the blog

Reads that touch this API.

Top Image Editing APIs for 2026Sep 18, 2026 How to Convert Images to WebP in 2026: Formats, Browser Support, and a Conversion APISep 18, 2026 Video Watermarking: Guide Using Node.js & ApyHub APISep 18, 2026 Video Processing APIs for 2025: Optimize & Edit Video ContentAug 10, 2026