Background Removal (Binary)#

Endpoint#

POST /v1.0/image-without-background

Base URL: https://api.withoutbg.com · Spec: openapi.json

Example (cURL)#

curl -X POST \
  -H "X-API-Key: $WITHOUTBG_API_KEY" \
  -F "file=@/path/to/input.jpg" \
  --output result.png \
  "https://api.withoutbg.com/v1.0/image-without-background"

Authentication#

Provide your API key in the request header:

X-API-Key: <your_api_key>

Request#

Content-Type: multipart/form-data

Fields#

• file (string, required)
• include_image_type (boolean, optional) · default true — When true (default), include photo vs graphic probabilities in X-Image-Type-* headers. Set false to skip.
• keep_mask (string, optional) — Optional Keep mask: marked pixels become fully opaque. One stroke on a person or object that was cut away brings back all of it. It is an image with the same width and height as the input (after EXIF orientation) or as the returned matte (processed_dimensions). White (light, opaque) pixels mark the area; black or transparent pixels mark nothing, so paint white strokes on a black or transparent canvas. Send it with matte (the matte we returned for this image) to fix that matte: a rough stroke is enough, then edges are refined again. Without matte the image is matted first. Where keep_mask and remove_mask overlap, Remove wins. Maximum size: 5.0 MB.
• remove_mask (string, optional) — Optional Remove mask: marked pixels become fully transparent. One stroke on an extra person or object removes all of it. It is an image with the same width and height as the input (after EXIF orientation) or as the returned matte (processed_dimensions). White (light, opaque) pixels mark the area; black or transparent pixels mark nothing, so paint white strokes on a black or transparent canvas. Send it with matte (the matte we returned for this image) to fix that matte: a rough stroke is enough, then edges are refined again. Without matte the image is matted first. Where keep_mask and remove_mask overlap, Remove wins. Maximum size: 5.0 MB.
• matte (string, optional) — Optional, needs keep_mask or remove_mask: the alpha matte we returned for this image, as a grayscale PNG at the input or processed_dimensions size. It is edited with the masks instead of being recomputed, so earlier fixes are kept. Maximum size: 10.0 MB.

Response#

Success Content-Type: image/png

Response headers#

• X-Input-Dimensions — Decoded input size as `width,height` (pixels).
• X-Processed-Dimensions — Size after server prep downscale (longest side / megapixel caps) as `width,height`. Not the model inference resolution (~1024 long side).
• X-Was-Downscaled — Whether the input was downscaled during server prep (`true`/`false`).
• X-Image-Type-Photo — Optional photo-class probability from image-type classifier.
• X-Image-Type-Graphic — Optional graphic-class probability from image-type classifier.

Errors#

Related endpoints#

• Background Removal (Base64) — POST /v1.0/image-without-background-base64