Integration Guide

How to integrate BackgroundCut into your web app, mobile app, or any client-server setup.

Two Integration Approaches

Direct API (Server-to-Server)

Call the API directly with your Bearer key. Simplest approach — great for backend scripts, batch processing, and server-side integrations.

Presigned URLs (Client-Side)

Your server gets presigned URLs, your client uses them. Images go directly from client to API — your API key is never exposed.

Presigned URL Flow

Your server gets presigned URLs from API using Bearer key

→

Client uploads image using presigned upload URL

→

Client processes image using presigned process URL

Why presigned URLs work well

API key stays on your server

Clients only get short-lived presigned URLs. They never see your key.

No image proxy

Images go directly from client to API. Your server handles tiny JSON requests only.

Any client

Browser, React Native, Flutter, iOS, Android, Electron — anything that sends HTTP requests.

Config locked in

Output variants are encoded in the presigned URL. Clients can't tamper with settings.

Option 1: Direct API

Call the API directly with your Bearer key. Best for server-side integrations.

import requests

API_KEY = "YOUR_API_KEY"  # Keep this on your server
API_BASE = "https://api.backgroundcut.co"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Step 1 — Upload image
with open("photo.jpg", "rb") as f:
    upload = requests.post(
        f"{API_BASE}/v3/remove-bg/upload-image/",
        headers=HEADERS,
        files={"image": f},
        timeout=60
    ).json()

unique_filename = upload["unique_filename"]

# Step 2 — Process with output variants
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": "result"
                # Defaults: 12MP, png, high quality, transparent bg
            }
        ]
    },
    timeout=300
).json()

print(result["output_urls"]["result"])

Option 2: Presigned URLs

Your server gets presigned URLs, then your client uses them to upload and process directly.

Server: Get Presigned URLs

Call these from your server when a user wants to process an image. Return the signed_request values to your client.

import requests

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

# === YOUR SERVER: Get presigned URLs ===

# 1. Get upload presigned URL
upload_presign = requests.post(
    f"{API_BASE}/v3/remove-bg/upload-image/presign/",
    headers=HEADERS,
    timeout=10
).json()
# Returns: {"signed_request": "eyJ..."}

# 2. Get process presigned URL (with output variant config)
process_presign = requests.post(
    f"{API_BASE}/v3/remove-bg/process-image/presign/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "unique_filename": "PLACEHOLDER",  # filled after upload
        "output_variants": [{"variant_name": "result"}]
    },
    timeout=10
).json()
# Returns: {"signed_request": "eyJ..."}

# Send both signed_requests to your client
# The client uses them without needing your API key

Client: Upload and Process

The client gets presigned URLs from your server, then uploads and processes directly with BackgroundCut.

// User selects a file. Your server provides presigned URLs.

// 1. Get presigned URLs from your server
const { uploadSignedRequest, processSignedRequest } = await fetch('/your-api/get-presigned-urls', {
    method: 'POST'
}).then(r => r.json());

// 2. Upload image directly to BackgroundCut (no API key needed)
const uploadForm = new FormData();
uploadForm.append('image', fileInput.files[0]);  // from <input type="file">

const uploadResult = await fetch(
    `https://api.backgroundcut.co/v3/remove-bg/upload-image/presigned/?signed_request=${encodeURIComponent(uploadSignedRequest)}`,
    { method: 'POST', body: uploadForm }
).then(r => r.json());
// uploadResult.unique_filename → identifies the uploaded image

// 3. Process image using presigned URL (no API key needed)
const result = await fetch('https://api.backgroundcut.co/v3/remove-bg/process-image/presigned/', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ signed_request: processSignedRequest })
}).then(r => r.json());

// result.output_urls.result → URL to the processed image

Presigned URL Behavior

Single use. Each presigned URL can only be used once.
Short-lived. Presigned URLs expire shortly after creation. Request them right before use.
Config is locked in. Output variants (resolution, format, quality) are encoded in the process presigned URL and cannot be changed client-side.
No authentication needed. Clients use presigned URLs without any API key or auth headers.

Documentation

Remove BG Examples

AI Cut Examples

Interactive Docs