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. 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` + `upload_path`
Returns	`file_paths`

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` array
Returns	`output_file_paths`

This example generates 3 variants in one call:

output_file_path	Resolution	Format	Background	Notes
`my-project/full.png`	12MP	PNG	Transparent	High quality, full resolution
`my-project/thumb.webp`	0.25MP	WebP	Transparent	Auto-cropped to object bounds
`my-project/white-bg.jpg`	12MP	JPEG	`#ffffff`	White background, compressed

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 with multiple output variants (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/full.png",
                "format": "png",
                "max_resolution": 12000000,
                "quality": "high"
                # transparent background (default)
            },
            {
                "output_file_path": "my-project/thumb.webp",
                "format": "webp",
                "max_resolution": 250000,
                "quality": "medium",
                "autocrop": True
                # crops tightly to object bounds
            },
            {
                "output_file_path": "my-project/white-bg.jpg",
                "format": "jpeg",
                "max_resolution": 12000000,
                "background_color": "#ffffff",
                "output_compression": 85
            }
        ]
    },
    timeout=300
)

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

full_path, thumb_path, white_bg_path = output["output_file_paths"]
print("Full PNG:  ", full_path)
print("Thumbnail: ", thumb_path)
print("White BG:  ", white_bg_path)

Response

{
    "output_file_paths": [
        "my-project/full.png",
        "my-project/thumb.webp",
        "my-project/white-bg.jpg"
    ]
}

Field	Type	Description
`output_file_paths`	`string[]`	Ordered list of output file paths in your space, one per variant in the same order as `output_variants`.

Output Variant Fields

Field	Type	Default	Description
`output_file_path`	`string`	—	required Destination path in your space (e.g. `my-project/result.png`).
`format`	`string`	`"png"`	Output format: `png`, `jpeg`, `jpg`, `webp`, `avif`. Use JPEG/WebP for solid color backgrounds.
`max_resolution`	`integer`	`12000000`	Maximum pixel count (width × height). Range: 4096–25,000,000.
`quality`	`string`	`"high"`	Processing quality: `high`, `medium`, `low`. Affects edge detail and mask precision.
`background_color`	`string`	`null`	Fill color (e.g. `"#ffffff"`). Omit or set to `null` for transparent.
`output_compression`	`integer`	`85`	Compression level for JPEG/WebP/AVIF outputs (1–100). No effect on PNG.
`autocrop`	`boolean`	`false`	Crop the output to the bounding box of the foreground subject. Useful for thumbnails.

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

Use JPEG or WebP for solid backgrounds. PNG supports transparency but produces larger files when a solid color background is set.
Reuse the image. The file persists in your space after upload. Call /v3/tools/ai/remove-bg/process/ again with the same input_file_path and new variants without re-uploading. See Image Reuse.
Paths are ordered. Entries in output_file_paths correspond to variants in the same order as output_variants.

API v3 Beta

Remove BG Examples

AI Cut Examples

Interactive Docs