API v3 Beta
Remove BG Examples
AI Cut Examples
Interactive Docs

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
1

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

→
2

Client uploads image using the access token as an AccessToken header

→
3

Client processes image using the same access token

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}"}

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

input_file_path = upload["file_paths"][0]

# 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_file_path": input_file_path,
        "output_variants": [
            {
                "output_file_path": "my-project/result.png"
                # Defaults: 12MP, png, high quality, transparent bg
            }
        ]
    },
    timeout=300
).json()

print(result["output_file_paths"][0])

Option 2: Access Tokens

Your server mints a short-lived access token, then your client uses it to upload and process 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/tools/ai/remove-bg/process/",
            "/v3/files/*"
        ],
        "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
FieldTypeDefaultDescription
pathsstring[]["*"]Glob patterns for allowed endpoints. Use "*" for all, or list specific paths (e.g. "/v3/file-ops/upload/", "/v3/tools/ai/ai-cut/segment/", "/v3/files/*").
expires_ininteger60Token lifetime in seconds (1–600). Mint tokens immediately before use — do not store them.
Client: Upload and Process

The client gets the access token from your server, then uploads and processes 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}` };

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

const upload = await fetch(`${API_BASE}/v3/file-ops/upload/`, {
    method: 'POST',
    headers: AUTH,
    body: uploadForm
}).then(r => r.json());
// upload.file_paths[0] → identifies the uploaded image

// 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_file_path: upload.file_paths[0],
        output_variants: [{ output_file_path: 'my-project/result.png' }]
    })
}).then(r => r.json());

// result.output_file_paths[0] → path to the processed image
// Download it via GET /v3/files/{path} with the same access token

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.