Alpha Matte (Base64)#

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

Return a grayscale alpha matte as Base64 PNG in JSON.

Cost: 1 credit on HTTP 200.

Recommended when you keep a full-res original locally, send a ~1024 px proxy, then upscale/apply the matte yourself. Binary sibling: /v1.0/alpha-channel.

Endpoint#

POST /v1.0/alpha-channel-base64

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: 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) — When true (default), include photo vs graphic probabilities in the response (`image_type` / `X-Image-Type-*`). Set false to skip.

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 (~1024 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.
alpha_base64 (string, required) — Grayscale alpha matte as Base64 PNG. Prepend `data:image/png;base64,` to display in a browser.

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.
`422`	Validation error. Includes invalid Base64, non-image payloads, unsupported formats, and decoded size over 20.0 MB.	[object Object]
`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" \
  -H "Content-Type: application/json" \
  -d '{"image_base64":"<raw_base64>"}' \
  "https://api.withoutbg.com/v1.0/alpha-channel-base64"

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

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