Remove Background: Custom Background
Replace the removed background with a solid color. Generate transparent and colored variants in one call.
Note: Upload uses
multipart/form-data. Process and get-public-url use application/json.Step 1 Upload Image
| Method | POST |
| Endpoint | /v3/file-ops/upload/ |
| Content-Type | multipart/form-data |
| Body | file + key |
| Returns | {"success": true} |
Step 2 Process Image
| Method | POST |
| Endpoint | /v3/tools/ai/remove-bg/process/ |
| Content-Type | application/json |
| Body | JSON with input_key + output_variants |
| Returns | output_keys |
background_color: Any hex color string —
#ffffff (white), #000000 (black), #1A01FF (blue), #FF5733 (orange), or 8-digit form for alpha (#ffffff80). Omit or set to null for transparent output. When using a solid background prefer format: "jpeg" or format: "webp" — they produce smaller files since no alpha channel is needed.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"
]
} | Field | Type | Description |
|---|---|---|
output_keys | string[] | 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."
} | Status | Meaning |
|---|---|
400 | Bad request — invalid hex color, missing fields, or malformed JSON |
401 | Missing or invalid Authorization header |
402 | Insufficient credits |
404 | File not found — input_key does not exist (expired, deleted, or wrong region) |
429 | Rate 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_variantsarray. One upload, one processing call, multiple outputs. - Reuse the image — call
/v3/tools/ai/remove-bg/process/again later with the sameinput_keyto try new background colors. See Image Reuse.