Authentication

Send your API key in every request header

API Key
Your API key is a permanent secret key that identifies your account. You can find it in your dashboard. Send it raw in the Authorization header with no scheme prefix. Never expose this key in client-side code, it should only be used on your server.

Authorization: YOUR_API_KEY

Remove Background

POST https://api.backgroundcut.co/v2/cut/

Provide the image in exactly one of three ways: a file upload (image_file), a base64 string (image_file_b64), or a public URL (image_file_url). The processed image is returned directly in the response body.

Quick Start

curl -X POST https://api.backgroundcut.co/v2/cut/ \
     -H "Authorization: YOUR_API_KEY" \
     -F "image_file=@input_image.jpg" \
     -F "quality=High" \
     -F "return_type=PNG" \
     --output output.png

Code Examples

import requests

# Your API key (keep this secret, server-side only)
API_KEY = "YOUR_API_KEY"

url = "https://api.backgroundcut.co/v2/cut/"

headers = {
    "Authorization": API_KEY
}

# Option 1: Upload a file
with open("input_image.jpg", "rb") as image_file:
    files = {"image_file": image_file}
    data = {
        "max_resolution": 4000000,
        "quality": "High",
        "return_type": "PNG"
    }
    response = requests.post(url, headers=headers, files=files, data=data)

# Option 2: Pass a public URL
# response = requests.post(url, headers=headers, data={
#     "image_file_url": "https://example.com/photo.jpg",
#     "return_type": "PNG"
# })

# Save the result
if response.status_code == 200:
    with open("output.png", "wb") as output_file:
        output_file.write(response.content)
    print("Success! Background removed.")
else:
    print(f"Error {response.status_code}: {response.text}")

Request Parameters

Image Input (provide exactly one)

image_file	Source image as a binary file upload. Supports PNG, JPG, WEBP.
image_file_b64	Source image as a base64-encoded string.
image_file_url	Public URL to fetch the source image from.

Processing Options

max_resolution	Maximum output resolution in pixels. Up to 12,000,000 (12 MP). Larger values are clamped. Default: 12000000
quality	`High`, `Medium` (default), or `Low`. Higher quality takes longer.
return_type	`PNG` (default) for lossless with transparency. `WEBP` for compressed with transparency. Append a quality level 1-100 to control WebP compression, e.g. `WEBP_100` (near-lossless) or `WEBP_50` (smaller).
channels	`rgba` (default) returns the cutout on a transparent background. `alpha` returns only the grayscale alpha matte.

Response Codes

200	Background removed. Processed image returned as raw bytes in the chosen format.
400	Invalid parameters, unsupported image type, or unreadable image. No credit deducted.
401	API key missing or invalid.
402	No API credits remaining.
503	Server is busy (processing queue full). Retry shortly.
504	Processing timed out. Retry shortly.

Output Formats

PNG: Lossless quality with transparency. Larger file size.
WEBP: Recommended for web. Smaller files with transparency. Use WEBP_75 for a good balance of quality and size.