Background Removal (Binary)#

When to Use This Endpoint#

Use the binary background removal endpoint when:

• Server-to-server workflows: Direct file I/O without JSON overhead, perfect for backend processing
• CLI tools and scripts: Save the transparent PNG directly to disk
• Batch processing: Process multiple images efficiently without base64 encoding/decoding overhead
• File-based pipelines: Integration with systems that expect standard image files
• Simple cutouts: You need the final transparent PNG, not separate RGB and alpha for compositing

Binary vs Base64: Choose binary for server environments, file-based workflows, and direct image output. Use the Base64 variant for browser apps, JSON APIs, or when you need to embed images in structured data.

Cutout vs Matte: This endpoint returns the final cut-out image with transparent background. If you need the alpha mask separately for advanced compositing, use the Alpha Matte endpoints instead.

Endpoint#

POST /v1.0/image-without-background

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

Authentication#

Provide your API key in the request header:

X-API-Key: <your_api_key>

Request#

Headers#

• X-API-Key: <your_api_key> (required)
• The request must be multipart/form-data.

Form fields#

• file (required): The image file to process.

Supported formats: JPEG, PNG, WebP, TIFF, BMP, GIF

Max file size: 10 MB

Response#

• 200 OK — Binary image in the body
  • Content-Type: image/png
  • Transparent background (alpha channel)

The response body is the processed PNG. Save it to disk (e.g., no-bg.png).

Usage Examples#

curl -X POST \
  -H "X-API-Key: $WITHOUTBG_API_KEY" \
  -F "file=@/path/to/input.jpg" \
  --output no-bg.png \
  https://api.withoutbg.com/v1.0/image-without-background

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/image-without-background', {
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('no-bg.png', buffer);

1const formData = new FormData();
2formData.append('file', fileInput.files[0]);
3
4const res = await fetch('https://api.withoutbg.com/v1.0/image-without-background', {
5  method: 'POST',
6  headers: { 'X-API-Key': 'YOUR_API_KEY' }, // Use backend proxy instead
7  body: formData
8});
9
10if (!res.ok) throw new Error(`HTTP ${res.status}`);
11const blob = await res.blob();
12
13// Save in browser
14const url = URL.createObjectURL(blob);
15const a = document.createElement('a');
16a.href = url;
17a.download = 'no-bg.png';
18a.click();
19URL.revokeObjectURL(url);

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

1set -euo pipefail
2API=https://api.withoutbg.com/v1.0/image-without-background
3
4http_code=$(curl -sS -w "%{http_code}" -o no-bg.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  # Optional: dump JSON error (403/4xx) to stderr
11  curl -sS -H "X-API-Key: $WITHOUTBG_API_KEY" -F "file=@input.jpg" "$API" -o >(cat >&2)
12  exit 1
13fi

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

Errors#

All error responses follow this format:

{
  "detail": "Error message here"
}

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
• Keep it binary: Use multipart/form-data and send the raw file part for best performance
• Idempotence: Hash input files for deduplication if you need to handle retries

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
• 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: The endpoint removes the background automatically. For fine control over compositing, use Alpha Matte endpoints

Quick Checklist#

• POST to /v1.0/image-without-background
• X-API-Key header present with valid key
• multipart/form-data with file field (not image)
• 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

Related Endpoints#

• Background Removal (Base64): POST /v1.0/image-without-background-base64 — Returns Base64 JSON for browser/embedded workflows
• Alpha Matte (Binary): POST /v1.0/alpha-channel — Returns just the alpha mask for advanced compositing
• Alpha Matte (Base64): POST /v1.0/alpha-channel-base64 — Base64 variant of alpha matte with compositing benefits explained
• Credits: GET /available-credit — Check remaining API credits