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 API key. Simplest approach — great for backend scripts, batch processing, and server-side integrations.

Access Tokens (Client-Side)

Your server mints a short-lived, path-scoped access token; your client uses it directly. Images go from client to API — your API key is never exposed.

Access Token Flow

Your server mints an access token via /v3/auth/access-token/ using its API key

→

Client uploads image and processes it using the access token as an AccessToken header

→

Client calls get-public-url to get a direct download link for the result

Why access tokens work well

API key stays on your server

Clients only get short-lived, scoped tokens. 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.

Path-scoped

Each token is restricted to the endpoints you list. Calls to other paths are rejected.

Option 1: Direct API

Call the API directly with your API key (Authorization: Token YOUR_API_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"Token {API_KEY}"}

INPUT_KEY = "my-project/photo.jpg"
OUTPUT_KEY = "my-project/result.png"

# Step 1 — Upload image
with open("photo.jpg", "rb") as f:
    requests.post(
        f"{API_BASE}/v3/file-ops/upload/",
        headers=HEADERS,
        files={"file": f},
        data={"key": INPUT_KEY},
        timeout=60
    ).raise_for_status()

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

output_key = result["output_keys"][0]

# Step 3 — Mint a public URL to download the result
pub = requests.post(
    f"{API_BASE}/v3/file-ops/get-public-url/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"key": output_key},
    timeout=10
).json()

print(pub["url"])  # public URL, no auth needed

Option 2: Access Tokens

Your server mints a short-lived access token, then your client uses it to upload, process, and get the result directly.

Server: Mint an Access Token

Call POST /v3/auth/access-token/ from your server when a user wants to process an image. Return the access_token value to your client.

import requests

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

# === YOUR SERVER: Mint a scoped access token ===
# The token is restricted to specific paths and expires after `expires_in` seconds.

token_response = requests.post(
    f"{API_BASE}/v3/auth/access-token/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "paths": [
            "/v3/file-ops/upload/",
            "/v3/file-ops/get-public-url/",
            "/v3/tools/ai/remove-bg/process/"
        ],
        "expires_in": 600  # 10 minutes
    },
    timeout=10
).json()

access_token = token_response["access_token"]
# Returns: {"access_token": "eyJ..."}

# Send `access_token` to your client.
# The client uses it as "Authorization: AccessToken <token>"
# — your real API key is never exposed.

`POST /v3/auth/access-token/` request body

Field	Type	Default	Description
`paths`	`string[]`	`["*"]`	Glob patterns for allowed endpoints. Use `"*"` for all, or list specific paths (e.g. `"/v3/file-ops/upload/"`, `"/v3/file-ops/get-public-url/"`, `"/v3/tools/ai/remove-bg/process/"`).
`expires_in`	`integer`	`60`	Token lifetime in seconds (1–600). Mint tokens immediately before use — do not store them.

Client: Upload, Process, and Get Result

The client gets the access token from your server, then uploads, processes, and mints a public URL directly with BackgroundCut using it in the Authorization: AccessToken <token> header.

// User selects a file. Your server provides a scoped access token.

// 1. Get the access token from your server
const { accessToken } = await fetch('/your-api/get-bgcut-token', {
    method: 'POST'
}).then(r => r.json());

const API_BASE = 'https://api.backgroundcut.co';
const AUTH = { 'Authorization': `AccessToken ${accessToken}` };

const INPUT_KEY = 'my-project/photo.jpg';
const OUTPUT_KEY = 'my-project/result.png';

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

await fetch(`${API_BASE}/v3/file-ops/upload/`, {
    method: 'POST',
    headers: AUTH,
    body: uploadForm
});

// 3. Process the image with the same token
const result = await fetch(`${API_BASE}/v3/tools/ai/remove-bg/process/`, {
    method: 'POST',
    headers: { ...AUTH, 'Content-Type': 'application/json' },
    body: JSON.stringify({
        input_key: INPUT_KEY,
        output_variants: [{ output_key: OUTPUT_KEY }]
    })
}).then(r => r.json());

const outputKey = result.output_keys[0];

// 4. Mint a public URL to display or download the result
const { url } = await fetch(`${API_BASE}/v3/file-ops/get-public-url/`, {
    method: 'POST',
    headers: { ...AUTH, 'Content-Type': 'application/json' },
    body: JSON.stringify({ key: outputKey })
}).then(r => r.json());

// Set url as <img src="..."> or trigger a download — no auth header needed

Access Token Behavior

Path-scoped. Tokens only work for the paths listed in paths. Calls to other endpoints return 401.
Short-lived. Tokens expire after expires_in seconds (max 600). Mint them right before use — do not cache or reuse them.
Sent as AccessToken. Use the token in the Authorization: AccessToken <token> header. Note this is different from the Authorization: Token YOUR_API_KEY format used for API keys.

API v3 Beta

Remove BG Examples

AI Cut Examples

Interactive Docs