Multiple Variants Example - BackgroundCut API v3

Remove Background: Multiple Variants

Generate multiple output versions from a single image in one processing request.

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` array
Returns	`output_urls` keyed by `variant_name`

This example generates 3 variants in one call:

variant_name	Resolution	Format	Background	Notes
`full`	12MP	PNG	Transparent	High quality, full resolution
`thumbnail`	0.25MP	WebP	Transparent	Auto-cropped to object bounds
`white_bg`	12MP	JPG	`#ffffff`	White background, compressed

Pricing: The first variant is charged at the standard rate based on resolution. Each additional variant costs 0.25 credits. Autocrop adds 0.5 credits per variant.

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 multiple output variants (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": "full",
                "max_resolution": 12000000,
                "format": "png",
                "quality": "high"
                # transparent background (default)
            },
            {
                "variant_name": "thumbnail",
                "max_resolution": 250000,
                "format": "webp",
                "quality": "medium",
                "autocrop": True
                # crops tightly to object bounds
            },
            {
                "variant_name": "white_bg",
                "max_resolution": 12000000,
                "format": "jpg",
                "background_color": "#ffffff",
                "output_compression": 85
            }
        ]
    },
    timeout=300
)

result.raise_for_status()
output = result.json()

print("Full PNG:  ", output["output_urls"]["full"])
print("Thumbnail: ", output["output_urls"]["thumbnail"])
print("White BG:  ", output["output_urls"]["white_bg"])

Response

{
    "unique_filename": "abc123-def456-...",
    "input_url": "https://cdn.backgroundcut.co/.../input.jpg",
    "output_urls": {
        "full": "https://cdn.backgroundcut.co/.../full.png",
        "thumbnail": "https://cdn.backgroundcut.co/.../thumbnail.webp",
        "white_bg": "https://cdn.backgroundcut.co/.../white_bg.jpg"
    }
}

Field	Type	Description
`unique_filename`	`string`	Same identifier from the upload step. Reuse to generate more variants without re-uploading.
`input_url`	`string`	URL to the original uploaded image.
`output_urls`	`object`	Map of `variant_name` → output image URL. Contains one entry per variant requested.

Output Variant Fields

Field	Type	Default	Description
`variant_name`	`string`	—	Required. Your identifier for this output. Used as the key in `output_urls`. Must be unique within the request.
`max_resolution`	`integer`	`12000000`	Maximum output pixel count (width × height). Output is scaled down proportionally if the original exceeds this. 12MP = 12,000,000.
`format`	`string`	`"png"`	Output format. Options: `png`, `jpg`, `webp`. Use `jpg` or `webp` when `background_color` is set (no alpha needed, smaller files).
`quality`	`string`	`"high"`	Processing quality. Options: `high`, `medium`, `low`. Affects edge detail and mask precision.
`background_color`	`string`	`null`	Fill color for removed background. Hex string (e.g. `"#ffffff"`). Omit or set to `null` for transparent.
`output_compression`	`integer`	`85`	Compression level for JPG and WebP outputs. Range: 1–100. Higher = larger file, better quality. Has no effect on PNG.
`autocrop`	`boolean`	`false`	Crop the output to the bounding box of the foreground subject. Adds 0.5 credits per variant. Useful for thumbnails.

Error Response

All errors return JSON with a detail field:

{
    "detail": "Invalid image format. Supported: PNG, JPG, JPEG, WebP"
}

Status	Meaning
`400`	Bad request — missing image, invalid format, duplicate `variant_name`, 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

Variant names must be unique within a request. Using the same variant_name twice in one call will return a 400 error.
Use JPG or WebP for solid backgrounds. PNG supports transparency but produces larger files when a solid color background is set.
Reuse the image. The unique_filename stays valid after processing. Call /v3/remove-bg/process-image/ again with new variants without re-uploading. See Image Reuse.
Output URLs are temporary — download or cache results. URLs will expire.

Documentation

Remove BG Examples

AI Cut Examples

Interactive Docs