Remove Background: Custom Background

Replace the removed background with a solid color. Generate transparent and colored variants in one call.

Step 1 Upload Image
MethodPOST
Endpoint/v3/file-ops/upload/
Content-Typemultipart/form-data
Bodyfile + key
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
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"

# 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()

# Step 2 — Process with custom background colors (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": "my-project/blue-bg.jpg",
                "background_color": "#1A01FF",
                "format": "jpeg",
                "output_compression": 90
            },
            {
                "output_key": "my-project/white-bg.jpg",
                "background_color": "#ffffff",
                "format": "jpeg",
                "output_compression": 90
            },
            {
                "output_key": "my-project/transparent.png",
                "format": "png"
                # background_color omitted = transparent
            }
        ]
    },
    timeout=300
)

result.raise_for_status()
output_keys = result.json()["output_keys"]
blue_key, white_key, transparent_key = output_keys
print("Blue:       ", blue_key)
print("White:      ", white_key)
print("Transparent:", transparent_key)

# Step 3 — Mint public URLs
for key in output_keys:
    pub = requests.post(
        f"{API_BASE}/v3/file-ops/get-public-url/",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"key": key},
        timeout=10
    )
    pub.raise_for_status()
    print(key, "->", pub.json()["url"])
Process Response
{
    "output_keys": [
        "my-project/blue-bg.jpg",
        "my-project/white-bg.jpg",
        "my-project/transparent.png"
    ]
}
FieldTypeDescription
output_keysstring[]Ordered list of output keys in your space, one per variant in the same order as output_variants. Call POST /v3/file-ops/get-public-url/ with each key to get a downloadable URL.
Error Response

All errors return JSON with a detail field:

{
    "detail": "Invalid background_color. Expected hex string like #ffffff."
}
StatusMeaning
400Bad request — invalid hex color, missing fields, 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
  • Use JPEG or WebP for solid color backgrounds — significantly smaller than PNG when no transparency is needed. PNG is best reserved for transparent outputs.
  • Generate transparent and colored variants together — include both in a single output_variants array. One upload, one processing call, multiple outputs.
  • Reuse the image — call /v3/tools/ai/remove-bg/process/ again later with the same input_key to try new background colors. See Image Reuse.