Alpha Matte (Binary)#

When to Use This Endpoint#

Use the binary alpha matte endpoint when:

• Server-to-server workflows: Direct file I/O without JSON overhead
• CLI tools and scripts: Save the mask directly to disk
• Backend processing pipelines: Efficient binary transfers for compositing workflows
• Non-destructive editing: Keep the mask separate for advanced compositing, multiple background variants, or quality-preserving edits

Endpoint#

POST /v1.0/alpha-channel

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

Description: Returns the alpha channel (mask) of the processed image.

Consumes: multipart/form-data

Produces: image/png (grayscale)

Authentication#

Send your API key in the request header:

X-API-Key: YOUR_API_KEY

Request#

Headers#

• X-API-Key (required) - Your API key

Body (multipart/form-data)#

• file (required) - The image file to process

Supported input formats#

JPEG, PNG, WebP, TIFF, BMP, GIF. Max file size: 10 MB.

Response#

Success (200 OK)#

• Content-Type: image/png
• Body: Binary PNG containing the grayscale alpha matte

The response is a grayscale image where:

• White (255) = fully opaque foreground
• Black (0) = fully transparent background
• Gray values = partial transparency (soft edges, hair, etc.)

Error Responses#

All errors return JSON:

{
  "detail": "Error message here"
}

Examples#

curl -X POST "https://api.withoutbg.com/v1.0/alpha-channel" \
  -H "X-API-Key: $WITHOUTBG_API_KEY" \
  -F "file=@/path/to/input.jpg" \
  --output alpha-mask.png

1import os
2import requests
3
4url = "https://api.withoutbg.com/v1.0/alpha-channel"
5headers = {"X-API-Key": os.environ["WITHOUTBG_API_KEY"]}
6
7with open("input.jpg", "rb") as f:
8    files = {"file": f}
9    r = requests.post(url, headers=headers, files=files, timeout=60)
10    r.raise_for_status()
11    
12    with open("alpha-mask.png", "wb") as out:
13        out.write(r.content)

1import fs from "node:fs";
2import FormData from "form-data";
3
4const form = new FormData();
5form.append("file", fs.createReadStream("input.jpg"));
6
7const res = await fetch("https://api.withoutbg.com/v1.0/alpha-channel", {
8  method: "POST",
9  headers: { 
10    "X-API-Key": process.env.WITHOUTBG_API_KEY,
11    ...form.getHeaders()
12  },
13  body: form
14});
15
16if (!res.ok) {
17  const error = await res.text();
18  throw new Error(`HTTP ${res.status}: ${error}`);
19}
20
21const buffer = Buffer.from(await res.arrayBuffer());
22fs.writeFileSync("alpha-mask.png", buffer);

1set -euo pipefail
2API=https://api.withoutbg.com/v1.0/alpha-channel
3
4http_code=$(curl -sS -w "%{http_code}" -o alpha-mask.png \
5  -H "X-API-Key: $WITHOUTBG_API_KEY" \
6  -F "file=@input.jpg" "$API")
7
8if [ "$http_code" != "200" ]; then
9  echo "Request failed with status: $http_code" >&2
10  cat alpha-mask.png >&2  # Error response is JSON
11  exit 1
12fi

Status Codes#

Rate & Size Limits#

• Rate limit: 7 requests/minute per API key
• Max input size: 10 MB

Best Practices#

• Timeouts: Set HTTP timeouts of at least 60 seconds to cover upload and processing time
• Retries: Implement exponential backoff for transient 429 and 5xx errors
• Pre-resize: Downscale large images before upload to reduce latency and cost
• Monitor credits: Poll /available-credit to track usage and set up alerts
• Rate limiting: Stay within 7 requests/minute. Queue requests on your side if needed
• Security: Store API keys in environment variables or secrets managers, never in code repositories
• Error handling: Parse JSON error responses and handle 402/403 by prompting users to top up credits

Troubleshooting#

• 401 errors: Verify your API key is correct and included in the X-API-Key header
• 402/403 credit errors: Check /available-credit and top up if needed
• 413 errors: Input image exceeds 10 MB. Compress or resize before uploading
• 415 errors: Ensure the file is one of the supported formats (JPEG, PNG, WebP, TIFF, BMP, GIF)
• 422 errors: Verify the file field is present and contains a valid image
• 429 rate limit: Implement exponential backoff. Wait progressively longer between retries
• Mask appears all black/white: Some viewers don't render grayscale PNGs well. Open in an image editor to verify the gradient
• Unexpected results: The alpha matte shows where the subject is (white) vs background (black). Use with Background Removal output for compositing

Related Endpoints#

• Alpha Matte (Base64): POST /v1.0/alpha-channel-base64 — Returns the alpha matte as Base64 JSON for browser/embedded workflows
• Background Removal (Binary): POST /v1.0/image-without-background — Returns the cut-out image (RGB + alpha) instead of just the mask
• Background Removal (Base64): POST /v1.0/image-without-background-base64 — Base64 variant of background removal
• Credits: GET /available-credit — Check remaining API credits

Quick Checklist#

• POST to /v1.0/alpha-channel
• X-API-Key header present with valid key
• multipart/form-data with file field
• File is under 10 MB and in supported format
• HTTP timeout set to at least 60 seconds
• Save response body as *.png
• Handle 402/403 credit errors by checking /available-credit
• Implement exponential backoff for 429 rate limit errors
• Never expose API keys in client-side code