Alpha Matte (Binary)#

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

Return a grayscale alpha matte as a PNG.

Cost: 1 credit on HTTP 200.

Prefer this over the cutout endpoint when you need a full-resolution master: keep the original locally, optionally send a ~1024 px proxy, then apply the matte yourself. Edge detail is capped at model inference resolution (~1024 long side).

Binary sibling of /v1.0/alpha-channel-base64. Response metadata is returned in X-Input-Dimensions, X-Processed-Dimensions, X-Was-Downscaled, and optional X-Image-Type-* headers.

Endpoint#

POST /v1.0/alpha-channel

Base URL: https://api.withoutbg.com

Authentication#

Provide your API key in the request header:

API key header

X-API-Key: <your_api_key>

Request#

Content-Type: multipart/form-data

Fields#

file (binary, required)
include_image_type (boolean, optional) — When true (default), include photo vs graphic probabilities in X-Image-Type-* headers. Set false to skip.

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#

Status	Description	Detail
`401`	Invalid API Key	Invalid API Key
`402`	Insufficient credit. Please top up API credits.	Insufficient credit. Please top up API credits.
`403`	Credits Expired. Please top up API credits. If you have existing credits, they will be reactivated.	Credits Expired. Please top up API credits. If you have existing credits, they will be reactivated.
`413`	File size too large. Maximum file size is 20.0 MB.	File size too large. Maximum file size is 20.0 MB
`415`	Unsupported Media Type. Supported formats are: JPEG, PNG, WebP, AVIF, HEIC, TIFF, BMP, GIF.	Unsupported Media Type. Supported formats are: JPEG, PNG, WebP, AVIF, HEIC, TIFF, BMP, GIF.
`422`	Validation Error	Validation Error
`429`	Rate limit exceeded (product policy: 30 requests/minute per API key). May be returned by the API gateway. Retry with exponential backoff.	{"error":"Too Many Requests","status":429,"message":"Rate limit exceeded. Please try again later"}
`500`	Internal Server Error	Internal Server Error. Please contact support: contact@withoutbg.com

Example (cURL)#

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/alpha-channel"

Alpha Matte (Base64) — POST /v1.0/alpha-channel-base64

Contract sections are generated at build time from OpenAPI. Markdown mirror: /docs/pro-model/alpha-matte-binary.md