Remove Background: Custom Background
Replace the removed background with a solid color. Generate transparent and colored variants in one call.
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 keyed by variant_name |
background_color: Any hex color string —
#ffffff (white), #000000 (black), #1A01FF (blue), #FF5733 (orange), etc. Omit or set to null for transparent output. When setting a solid background, prefer format: "jpg" 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"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 with custom background colors (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": "blue_bg",
"background_color": "#1A01FF",
"format": "jpg",
"output_compression": 90
},
{
"variant_name": "white_bg",
"background_color": "#ffffff",
"format": "jpg",
"output_compression": 90
},
{
"variant_name": "transparent",
"format": "png"
# background_color omitted = transparent
}
]
},
timeout=300
)
result.raise_for_status()
output = result.json()
print("Blue: ", output["output_urls"]["blue_bg"])
print("White: ", output["output_urls"]["white_bg"])
print("Transparent:", output["output_urls"]["transparent"])Response
{
"unique_filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"input_url": "https://cdn.backgroundcut.co/.../input.jpg",
"output_urls": {
"blue_bg": "https://cdn.backgroundcut.co/.../blue_bg.jpg",
"white_bg": "https://cdn.backgroundcut.co/.../white_bg.jpg",
"transparent": "https://cdn.backgroundcut.co/.../transparent.png"
}
}| Field | Type | Description |
|---|---|---|
unique_filename | string | Same identifier from the upload step. Reuse to generate additional variants without re-uploading. |
input_url | string | URL to the original uploaded image. |
output_urls | object | Map of variant_name → output image URL. One entry per requested variant. |
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 image, 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
- Use JPG or WebP for solid color backgrounds — they are 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. - Output URLs are temporary — download or cache results promptly. URLs will expire.
- Reuse the image — call
/v3/remove-bg/process-image/again later with the sameunique_filenameto try new background colors. See Image Reuse.