Remove Background: Basic
Simplest possible example. Upload an image, process it to remove the background, then mint a public URL to download the result.
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 (file), key (string) |
| 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 (array) |
Step 3 Get Public URL
| Method | POST |
| Endpoint | /v3/file-ops/get-public-url/ |
| Content-Type | application/json |
| Body | JSON with key |
| Returns | url (public, no auth) |
Each variant requires
output_key. All other variant fields are optional. Defaults: 12MP resolution, PNG format, medium quality, transparent background, no autocrop.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 URLStep 2 Response — Process Image
{
"output_keys": ["my-project/result.png"]
} | Field | Type | Description |
|---|---|---|
output_keys | string[] | 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"
} | Field | Type | Description |
|---|---|---|
url | string | Public 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"
} | Status | Meaning |
|---|---|
400 | Bad request — missing fields, invalid format, 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
- 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 sameinput_keyand different variants without re-uploading. See Image Reuse. - Supported input formats — JPEG, PNG, WebP, AVIF, HEIC/HEIF.