Remove Background: Basic
Simplest possible example. Upload an image, then process it to remove the background.
Note: The two steps use different content types. Upload uses
multipart/form-data. Process uses application/json.Step 1 Upload Image
| Method | POST |
| Endpoint | /v3/file-ops/upload/ |
| Content-Type | multipart/form-data |
| Auth | Token YOUR_API_KEY |
| Body | files (file), upload_path (string) |
| Returns | file_paths (array) |
Step 2 Process Image
| Method | POST |
| Endpoint | /v3/tools/ai/remove-bg/process/ |
| Content-Type | application/json |
| Auth | Token YOUR_API_KEY |
| Body | JSON with input_file_path + output_variants |
| Returns | output_file_paths (array) |
Each variant requires
output_file_path. All other variant fields are optional. Defaults: 12MP resolution, PNG format, high quality, transparent background, no autocrop.import requests
API_KEY = "YOUR_API_KEY"
API_BASE = "https://api.backgroundcut.co"
HEADERS = {"Authorization": f"Token {API_KEY}"}
# 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={"files": f},
data={"upload_path": "my-project"},
timeout=60
)
upload_response.raise_for_status()
input_file_path = upload_response.json()["file_paths"][0]
# 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_file_path": input_file_path,
"output_variants": [
{
"output_file_path": "my-project/result.png"
# All other fields are optional with sensible defaults:
# format: "png"
# max_resolution: 12000000 (12MP)
# quality: "high"
# background_color: null (transparent)
# output_compression: 85
# autocrop: false
}
]
},
timeout=300
)
result.raise_for_status()
output = result.json()
print(output["output_file_paths"][0])Step 1 Response — Upload Image
{
"file_paths": ["my-project/photo.jpg"]
}| Field | Type | Description |
|---|---|---|
file_paths | string[] | Paths of the uploaded files in your space. Pass file_paths[0] as input_file_path to tool endpoints. |
Step 2 Response — Process Image
{
"output_file_paths": ["my-project/result.png"]
}| Field | Type | Description |
|---|---|---|
output_file_paths | string[] | Ordered list of output file paths in your space, one per variant. Download via GET /v3/files/{path} with your API key. |
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_file_path does not exist |
429 | Rate limit exceeded — slow down requests |
Tips
- Reuse uploads — uploaded files persist in your space. Call
/v3/tools/ai/remove-bg/process/again with the sameinput_file_pathand different variants without re-uploading. See Image Reuse. - Download results — fetch
output_file_paths[0]viaGET /v3/files/{path}with your API key in the header. - Supported input formats — JPEG, PNG, WebP, AVIF.