Background Removal (Base64)#

Endpoint#

POST /v1.0/image-without-background-base64

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

Example (cURL)#

curl -X POST \
  -H "X-API-Key: $WITHOUTBG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_base64":"<raw_base64>","keep_mask_base64":null,"remove_mask_base64":null}' \
  "https://api.withoutbg.com/v1.0/image-without-background-base64"

Authentication#

Provide your API key in the request header:

X-API-Key: <your_api_key>

Request#

Content-Type: application/json

Fields#

• image_base64 (string, required) — Input image as a raw Base64 string (no data: URI prefix). Supported formats: JPEG, PNG, WebP, AVIF, HEIC, TIFF, BMP, GIF. Maximum decoded size: 20.0 MB. Invalid Base64, non-image data, unsupported formats, or oversize payloads fail with HTTP 422.
• include_image_type (boolean, optional) · default true — When true (default), include photo vs graphic probabilities in the response (image_type / X-Image-Type-*). Set false to skip.
• keep_mask_base64 (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. Raw Base64 string (no data: URI prefix).
• remove_mask_base64 (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. Raw Base64 string (no data: URI prefix).
• 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: application/json

Body fields#

• input_dimensions (array<integer>, required) — Decoded input size as [width, height] (pixels).
• processed_dimensions (array<integer>, required) — Size after server prep downscale (longest-side / megapixel caps) as [width, height]. Distinct from model inference resolution (up to 2048 px long side).
• was_downscaled (boolean, required) — True when the input was downscaled during server prep.
• image_type (object, optional) — Photo vs graphic class probabilities. Present when include_image_type is true (default); omitted when false. Never returned by car endpoints.
• img_without_background_base64 (string, required) — Result image as Base64 PNG (RGBA) with transparent background. Prepend data:image/png;base64, to display in a browser.
• shadow_base64 (string, optional) — Soft cast-shadow mask as Base64 grayscale PNG (0 = no shadow, 255 = full shadow), same size as the cutout. Present only when shadow_if_possible was true and a shadow was cast; the cutout already has it baked in.

Errors#

Related endpoints#

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