Remove Background: Basic

Simplest possible example. Upload an image, process it to remove the background, then mint a public URL to download the result.

Step 1 Upload Image
MethodPOST
Endpoint/v3/file-ops/upload/
Content-Typemultipart/form-data
Bodyfile (file), key (string)
Returns{"success": true}
Step 2 Process Image
MethodPOST
Endpoint/v3/tools/ai/remove-bg/process/
Content-Typeapplication/json
BodyJSON with input_key + output_variants
Returnsoutput_keys (array)
Step 3 Get Public URL
MethodPOST
Endpoint/v3/file-ops/get-public-url/
Content-Typeapplication/json
BodyJSON with key
Returnsurl (public, no auth)
import requests

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

INPUT_KEY = "my-project/photo.jpg"
OUTPUT_KEY = "my-project/result.png"

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

upload_response.raise_for_status()
# The file is stored under INPUT_KEY — no need to read it from the response

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

result.raise_for_status()
output_key = result.json()["output_keys"][0]
print("Output key:", output_key)

# Step 3 — Mint a public URL to download the result
pub = requests.post(
    f"{API_BASE}/v3/file-ops/get-public-url/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"key": output_key},
    timeout=10
)
pub.raise_for_status()
public_url = pub.json()["url"]
print("Download URL:", public_url)  # no auth needed to fetch this URL
Step 2 Response — Process Image
{
    "output_keys": ["my-project/result.png"]
}
FieldTypeDescription
output_keysstring[]Ordered list of output keys in your space, one per variant. Pass each key to POST /v3/file-ops/get-public-url/ to get a downloadable URL.
Step 3 Response — Get Public URL
{
    "url": "https://cdn.backgroundcut.co/pub/abc123.../result.png"
}
FieldTypeDescription
urlstringPublic URL serving the file directly from the edge. No Authorization header needed. Expires within 2 hours.
Error Response

All errors return JSON with a detail field:

{
    "detail": "Invalid image format. Supported: JPEG, PNG, WebP, AVIF"
}
StatusMeaning
400Bad request — missing fields, invalid format, or malformed JSON
401Missing or invalid Authorization header
402Insufficient credits
404File not found — input_key does not exist (expired, deleted, or wrong region)
429Rate limit exceeded — slow down requests
Tips
  • You choose the key — specify the full key at upload time (e.g. my-project/photo.jpg). No need to parse the upload response to find out where the file was stored.
  • Reuse uploads — the uploaded file persists in your space (up to 2 hours). Call /v3/tools/ai/remove-bg/process/ again with the same input_key and different variants without re-uploading. See Image Reuse.
  • Supported input formats — JPEG, PNG, WebP, AVIF, HEIC/HEIF.