Background Removal API (Base64)#

When to Use This Endpoint#

Use the base64 background removal endpoint when:

• Browser-based applications: Embed transparent PNGs directly in JSON responses for client-side rendering
• JSON API workflows: Need structured data format rather than raw binary images
• Serverless functions: Process and return images without file system access
• Mobile apps: Handle images in base64 format for API integration
• Embedded workflows: Include transparent images in JSON documents or data structures

Base64 vs Binary: Choose base64 for browser environments, JSON APIs, and structured data workflows. Use the Binary variant for server-to-server transfers, file I/O, and backend processing pipelines.

Cutout vs Matte: This endpoint returns the final cut-out image with transparent background baked in. If you need the alpha mask separately for advanced compositing workflows (multiple backgrounds, shadows, glows), use the Alpha Matte endpoints instead.

Endpoint#

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

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

Authentication#

Include your API key in the request header:

X-API-Key: YOUR_API_KEY

Request#

Content-Type: application/json

Body#

{
  "image_base64": "<base64_encoded_image_data>"
}

Fields#

• image_base64 (string, required) — The input image encoded as Base64. Supported input formats: JPEG, PNG, WebP, TIFF, BMP, GIF. Maximum file size: 10 MB (before encoding).

Response#

Content-Type: application/json

Body#

{
  "img_without_background_base64": "<base64_encoded_transparent_image>"
}

Fields#

• img_without_background_base64 (string) — The result image encoded as Base64 PNG with a transparent background.

Examples#

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

1import fs from "node:fs";
2
3const apiKey = process.env.WITHOUTBG_API_KEY;
4const imageBase64 = fs.readFileSync("input.jpg").toString("base64");
5
6const res = await fetch("https://api.withoutbg.com/v1.0/image-without-background-base64", {
7  method: "POST",
8  headers: {
9    "Content-Type": "application/json",
10    "X-API-Key": apiKey
11  },
12  body: JSON.stringify({ image_base64: imageBase64 })
13});
14
15if (!res.ok) {
16  const error = await res.text();
17  throw new Error(`HTTP ${res.status}: ${error}`);
18}
19
20const data = await res.json();
21const outputPng = Buffer.from(data.img_without_background_base64, "base64");
22fs.writeFileSync("output.png", outputPng);

1import base64
2import os
3import requests
4
5API_KEY = os.environ["WITHOUTBG_API_KEY"]
6
7with open("input.jpg", "rb") as f:
8    b64 = base64.b64encode(f.read()).decode("utf-8")
9
10resp = requests.post(
11    "https://api.withoutbg.com/v1.0/image-without-background-base64",
12    headers={"X-API-Key": API_KEY},
13    json={"image_base64": b64},
14    timeout=60,
15)
16resp.raise_for_status()
17
18out_b64 = resp.json()["img_without_background_base64"]
19with open("output.png", "wb") as out:
20    out.write(base64.b64decode(out_b64))

1# macOS/Linux example using base64 CLI
2BASE64_DATA=$(base64 -w 0 input.jpg) # use `-w 0` (GNU) or omit on macOS
3curl -X POST "https://api.withoutbg.com/v1.0/image-without-background-base64" \
4  -H "X-API-Key: $WITHOUTBG_API_KEY" \
5  -H "Content-Type: application/json" \
6  -d "{\"image_base64\": \"$BASE64_DATA\"}"

Python SDK#

Python developers can use the official withoutbg Python SDK instead of making raw HTTP requests:

1from withoutbg import remove_background
2
3# Cloud API (uses this endpoint)
4img = remove_background("input.jpg", api_key="sk_your_api_key")
5img.save("output.png")

The SDK handles authentication, retries, error handling, and provides a cleaner API. It also supports local processing (free) with the Focus v1.0.0 model.

Learn more: Python SDK Documentation

Status Codes#

Success (200 OK)#

Returns JSON with the transparent PNG as Base64.

Error Responses#

All errors return JSON:

{
  "detail": "Error message here"
}

Rate limit: 7 requests per minute per API key

Max input size: 10 MB (before base64 encoding)

Best Practices#

• Trim Base64 prefixes: Send only the raw Base64 payload, not data URI schemes
• Pre-resize: Downscale large images before encoding to reduce payload size and latency
• Retry on 429: Implement exponential backoff when rate limited
• Monitor credits: Check /available-credit to track usage and set up alerts
• Timeouts: Set HTTP timeouts of at least 60 seconds for large images
• Error handling: Parse JSON error responses and handle 402/403 by prompting users to top up credits
• Security: Store API keys in environment variables or secrets managers, never in code repositories
• Caching: Cache processed images on your side to save credits and reduce latency

Troubleshooting#

• 400/422 errors: Ensure Content-Type: application/json and image_base64 is a valid Base64 string of a supported image format
• 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 after decoding. Compress or resize before encoding
• 415 errors: Ensure the decoded image is in a supported format (JPEG, PNG, WebP, TIFF, BMP, GIF)
• 429 rate limit: Implement exponential backoff. Wait progressively longer between retries
• Transparent output issues: If your viewer shows a black/white background, the PNG is still transparent. Verify with an editor that supports alpha
• Unexpected results: For advanced compositing with multiple backgrounds, consider using Alpha Matte endpoints

Related Endpoints#

• Background Removal (Binary): POST /v1.0/image-without-background — Returns transparent PNG as binary for server workflows
• Alpha Matte (Base64): POST /v1.0/alpha-channel-base64 — Returns just the alpha mask for advanced compositing
• Alpha Matte (Binary): POST /v1.0/alpha-channel — Binary variant of alpha matte
• Credits: GET /available-credit — Check remaining API credits

Quick Checklist#

• POST to /v1.0/image-without-background-base64
• X-API-Key header present with valid key
• Content-Type: application/json header set
• JSON body with image_base64 field (raw Base64, no data URI prefix)
• Base64 string decoded size under 10 MB
• HTTP timeout set to at least 60 seconds
• 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
• Decode img_without_background_base64 from response to get transparent PNG