Basic Remove BG Example - BackgroundCut API v3

Remove Background: Basic

Simplest possible example. Upload an image, then process it to remove the background.

Note: The two steps use different content types. Upload uses multipart/form-data (file upload). Process uses application/json (JSON body).

Step 1 Upload Image

Method	`POST`
Endpoint	`/v3/remove-bg/upload-image/`
Content-Type	`multipart/form-data`
Auth	`Bearer YOUR_API_KEY`
Body	Form field: `image` (file)
Returns	`unique_filename`

Step 2 Process Image

Method	`POST`
Endpoint	`/v3/remove-bg/process-image/`
Content-Type	`application/json`
Auth	`Bearer YOUR_API_KEY`
Body	JSON with `unique_filename` + `output_variants`
Returns	`output_urls`, `input_url`

All variant fields are optional except variant_name. Defaults: 12MP resolution, PNG format, high quality, transparent background, no autocrop.

import requests

API_KEY = "YOUR_API_KEY"
API_BASE = "https://api.backgroundcut.co"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Step 1 — Upload image (multipart/form-data)
with open("photo.jpg", "rb") as f:
    upload_response = requests.post(
        f"{API_BASE}/v3/remove-bg/upload-image/",
        headers=HEADERS,
        files={"image": f},
        timeout=60
    )

upload_response.raise_for_status()
unique_filename = upload_response.json()["unique_filename"]

# Step 2 — Process image (application/json)
result = requests.post(
    f"{API_BASE}/v3/remove-bg/process-image/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "unique_filename": unique_filename,
        "output_variants": [
            {
                "variant_name": "result"
                # All other fields are optional with sensible defaults:
                # max_resolution: 12000000 (12MP)
                # format: "png"
                # quality: "high"
                # background_color: transparent
                # output_compression: 85
                # autocrop: false
            }
        ]
    },
    timeout=300
)

result.raise_for_status()
output = result.json()
print(output["output_urls"]["result"])

# Download the result
import urllib.request
urllib.request.urlretrieve(output["output_urls"]["result"], "output.png")

Step 1 Response — Upload Image

{
    "unique_filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Field	Type	Description
`unique_filename`	`string`	Unique identifier for the uploaded image. Use this in the process request and to reuse the image later.

Step 2 Response — Process Image

{
    "unique_filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "input_url": "https://cdn.backgroundcut.co/.../input.jpg",
    "output_urls": {
        "result": "https://cdn.backgroundcut.co/.../result.png"
    }
}

Field	Type	Description
`unique_filename`	`string`	Same identifier from the upload step.
`input_url`	`string`	URL to the original uploaded image.
`output_urls`	`object`	Map of `variant_name` → output image URL. Keys match the `variant_name` values you specified in `output_variants`.

Error Response

All errors return JSON with a detail field:

{
    "detail": "Invalid image format. Supported: PNG, JPG, JPEG, WebP"
}

Status	Meaning
`400`	Bad request — missing image, invalid format, or malformed JSON
`401`	Missing or invalid `Authorization` header
`402`	Insufficient credits
`404`	Image not found — `unique_filename` does not exist or has expired
`429`	Rate limit exceeded — slow down requests

Tips

Save unique_filename — you can call /v3/remove-bg/process-image/ again with the same unique_filename and different output_variants to generate new outputs without re-uploading. See Image Reuse.
Output URLs are temporary — download or cache the result images. URLs will expire.
Supported input formats — PNG, JPG, JPEG, WebP.

Documentation

Remove BG Examples

AI Cut Examples

Interactive Docs