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. The image is matted, then the strokes edit that matte: a rough stroke is enough, then edges are refined again. To fix a result further, send all strokes so far again. 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. The image is matted, then the strokes edit that matte: a rough stroke is enough, then edges are refined again. To fix a result further, send all strokes so far again. Where keep_mask and remove_mask overlap, Remove wins. Maximum size: 5.0 MB.
• shadow_if_possible (boolean, optional) · default false — When true, add a soft cast shadow under the subject if it stands on the ground. A ground-contact check runs first: floating, flying or jumping subjects, and ones where ground contact is uncertain, get no shadow, and neither does a photo whose camera or ground can't be recovered. The shadow is baked into the RGBA cutout behind the subject, with its light fitted to the shadow already in the photo (a default light when there is none). Vehicles always get their cast shadow, with or without this flag. Ignored when a Keep / Remove mask is sent. Default false. Same cost: 1 credit.

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.
• X-Shadow — Sent when `shadow_if_possible` is true: `true` if a cast shadow was added under the subject, `false` if not (subject off the ground, or no ground could be recovered).

Errors#

Related endpoints#

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