Integration Guide

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

The Pattern

Your server holds the API key and gets a short-lived token from BackgroundCut. Your client (browser, mobile app, desktop app) receives the token and sends the image directly to BackgroundCut's processing servers. Images never pass through your server.

1

User's device requests token from your server

2

Your server calls BackgroundCut Token API with Bearer key

3

Your server sends access token to user's device

4

Device sends image + token to Processing API

Why this works well
API key stays on your server

Users only get a single-use token. They never see your key.

No image proxy

Images go directly from user to processing server. Your server handles tiny JSON requests only.

GeoDNS routing

Users auto-connect to the nearest BackgroundCut server regardless of your server location.

Any client

Browser, React Native, Flutter, iOS, Android, Electron — anything that sends multipart POST.

Your Server: Get a Token

Call this from your server when a user wants to process an image. Return the access_token to your client. Integrate into whatever framework you use.

import requests

API_KEY = "YOUR_API_KEY"  # Keep this on your server — never expose to clients

# Your user wants to remove a background.
# Your server requests a token from BackgroundCut:

token_response = requests.post(
    "https://backgroundcut.co/api/v3/remove-bg/token/",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "output_variants": [
            {
                "variant_name": "result"
                # All other fields are optional with sensible defaults:
                # max_resolution: 12000000 (12MP)
                # format: "png"
                # quality: "high"
                # background_color: None (transparent)
                # output_compression: 90
                # autocrop: false
            }
        ]
    },
    timeout=60
)
token_response.raise_for_status()
access_token = token_response.json()["access_token"]

# Return this access_token to your client (browser, mobile app, etc.)
# The client will use it to send the image directly to BackgroundCut.

Your Client: Send Image

The client gets the token from your server, then sends the image directly to BackgroundCut.

// User selects a file, you get a token from YOUR server, then send directly to BackgroundCut.

// 1. Get token from your server
const tokenRes = await fetch('/your-api/get-token', { method: 'POST' });
const { access_token } = await tokenRes.json();

// 2. Send image directly to BackgroundCut
const formData = new FormData();
formData.append('token', access_token);
formData.append('image', fileInput.files[0]);  // from <input type="file">

const response = await fetch('https://api.backgroundcut.co/v3/remove-bg/', {
    method: 'POST',
    body: formData
});

const result = await response.json();
// result.output_urls.result → URL to the processed image
// result.unique_filename → save this to generate more variants later

Token Behavior

  • Single use. One token = one processing request.
  • Short-lived. Tokens expire shortly after creation. Request them right before upload.
  • Config is locked in. Output variants (resolution, format, quality) are encoded in the token and cannot be changed client-side.
  • Credits deducted at token creation. Only request tokens when the user is ready to upload.