API flags overview

How flags are sent

Request options can be sent in either of these ways:

• Multipart form fields, usually together with image_file
• JSON body fields, together with image, image_base64, or image_url

Keys are case-insensitive, and booleans accept values like true, false, 1, 0, yes, and no.

format

The format flag controls the output file type.

• Allowed: png, jpg, webp
• Default: png
• JPG is always opaque — if the result contains transparency, it will be flattened against bg_color, or white if no background color is provided.
• In some JSON workflows where channels ≠ alpha, the API may return a base64 JPG inside JSON for compactness.

channels

The channels flag controls whether the API returns a full image or just a mask.

• Allowed: rgba, alpha
• Default: rgba
• rgba returns the full cutout image
• alpha returns a single-channel PNG mask

If your JSON request uses the legacy field "image": "<base64>", the server forces channels="alpha".

size

The size flag caps the final output by megapixels. It never upscales the image. Internally, the model always performs inference using a 1024×1024 thumbnail representation.

• Allowed: preview, medium, hd, full, auto
• Default: full
• preview: about 0.25 MP
• medium: about 1.5 MP
• hd: about 4.0 MP
• full: up to 50 MP
• auto: alias of full

A long-side safeguard of roughly 6000 pixels may apply before the megapixel cap.

crop

The crop flag tight-crops the output to the non-transparent region of the result.

• Allowed: boolean
• Default: false
• In rgba mode, bounds are computed from the non-transparent region
• In alpha mode, bounds are computed from the non-zero mask
• The threshold is roughly alpha > 10

This is useful when you want a tighter result without transparent padding around the subject.

bg_color

The bg_color flag flattens the result against a solid background. This is especially useful with opaque formats like JPG, or when you want to replace transparency with a color.

• Allowed: CSS names, #rrggbb, or shorthand hex like fff
• Default: null
• If you request jpg and omit bg_color, white is used automatically

despill

The despill flag reduces unwanted color spill along edges. Internally it uses Lab-space cleanup while preserving luminance.

• Allowed: boolean
• Default: false
• Only applies when the working image is RGBA
• Has no effect on already-flattened outputs like JPG
• May be skipped on very large images (roughly > 50 MP)

Supported input fields

The API accepts several input field names depending on whether you are using JSON or multipart requests.

Data URLs are accepted, and any data:image/...;base64, prefix is stripped automatically.

Basic example

Here is the simplest possible multipart request:

curl -f https://api.backgrounderase.com/v2 \
  -H "x-api-key: YOUR_API_KEY" \
  -F 'image_file=@/absolute/path/to/image.jpg' \
  -o output.png

Example: PNG with alpha, crop, HD, and despill

curl -f https://api.backgrounderase.com/v2 \
  -H "x-api-key: YOUR_API_KEY" \
  -F 'image_file=@/path/to/image.jpg' \
  -F 'format=png' -F 'channels=rgba' \
  -F 'size=hd' -F 'crop=true' -F 'despill=true' \
  -o output.png

This example returns a PNG cutout, preserves alpha, tight-crops the result, limits the output to HD sizing, and enables despill.

Example: WebP with blue background

curl -f https://api.backgrounderase.com/v2 \
  -H "x-api-key: YOUR_API_KEY" \
  -F 'image_file=@/path/to/image.jpg' \
  -F 'format=webp' -F 'channels=rgba' \
  -F 'size=medium' -F 'bg_color=blue' -F 'despill=true' \
  -o output.webp

This example returns a WebP file, uses medium sizing, and flattens the output against a blue background. Because the image is flattened with a background color, despill may effectively be a no-op in the final opaque output.

Latency and performance tips

With optimized inputs, typical responses often land around 600–700 ms for standard multipart uploads. In low-latency JSON workflows, payloads are much smaller, which can improve perceived speed.

• For JSON mode, downsize client-side to 1024×1024 before sending when possible.
• For multipart uploads, use JPEG around 85% quality to balance file size and detail.
• Reuse keep-alive HTTP connections when possible.
• Avoid unnecessary proxies or unstable network paths.

Frequently asked questions