API v3 Beta
Remove BG Examples
AI Cut Examples
Interactive Docs

Remove Background: Image Reuse

Generate new output variants from a previously uploaded image without re-uploading it.

How it works:

  1. Upload your image once, specifying the key you want. Save the key.
  2. Call /v3/tools/ai/remove-bg/process/ with your initial output_variants.
  3. Later, call /v3/tools/ai/remove-bg/process/ again with the same input_key and new variants — no re-upload needed.
import requests

API_KEY = "YOUR_API_KEY"
API_BASE = "https://api.backgroundcut.co"
HEADERS = {"Authorization": f"Token {API_KEY}"}

# The key you choose at upload time — save this for reuse
INPUT_KEY = "my-project/photo.jpg"

# =============================================
# FIRST TIME — upload + initial processing
# =============================================

# 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()
print("Uploaded under key:", INPUT_KEY)  # save this

# Step 2 — Process with initial variant (application/json)
result1 = 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/preview.png", "quality": "low"}
        ]
    },
    timeout=300
)

result1.raise_for_status()
print("Preview:", result1.json()["output_keys"][0])

# =============================================
# LATER — new variants, NO re-upload needed
# =============================================
result2 = requests.post(
    f"{API_BASE}/v3/tools/ai/remove-bg/process/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "input_key": INPUT_KEY,    # same key, no re-upload
        "output_variants": [
            {
                "output_key": "my-project/high-res.png",
                "format": "png",
                "max_resolution": 4000000,
                "quality": "high",
                "autocrop": True
            },
            {
                "output_key": "my-project/red-bg.jpg",
                "format": "jpeg",
                "background_color": "#FF5733",
                "output_compression": 90
            }
        ]
    },
    timeout=300
)

result2.raise_for_status()
output_keys = result2.json()["output_keys"]
high_res_key, red_bg_key = output_keys
print("High res:", high_res_key)
print("Red BG:  ", red_bg_key)
Process Response

The response is identical whether this is the first or a subsequent processing call:

{
    "output_keys": [
        "my-project/high-res.png",
        "my-project/red-bg.jpg"
    ]
}
FieldTypeDescription
output_keysstring[]Ordered list of output keys in your space, one per variant. 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": "File not found at the given key."
}
StatusMeaning
400Bad request — missing or invalid fields, malformed JSON
401Missing or invalid Authorization header
402Insufficient credits — each processing call deducts credits
404File not found — input_key has expired, been deleted, or was uploaded to a different regional server
429Rate limit exceeded — slow down requests
Use Cases
  • E-commerce: Upload once, then generate marketplace-specific variants (Amazon, Shopify, eBay) with different sizes and backgrounds on demand.
  • A/B testing: Try different background colors or quality settings on the same image without paying to re-upload each time.
  • Progressive generation: Generate a fast low-quality preview first, then request a high-resolution variant once the user confirms.
  • Responsive images: Generate additional output sizes later as new requirements arise.
Tips
  • Each process call costs credits — only the upload is free to reuse. Every /v3/tools/ai/remove-bg/process/ call deducts credits based on the variants requested.
  • Input files persist up to 2 hours — uploaded files stay in your space until they expire. You can re-process the same image within that window without re-uploading.
  • Manage storage — use POST /v3/file-ops/delete/ with a pattern to remove files you no longer need, or set expires_in_hours at upload time for automatic cleanup.