BackgroundCut API v2

The power of BackgroundCut, automated

Two Ways to Authenticate
API Token

Your permanent secret key. Use it directly from your server to process images. Simple, one-step process.

Access Token

A single-use token for client-side use. Get it from your server, then let users send images directly to our API.

Method 1: Using API Token

Direct authentication for server-side applications

Quick Start

curl -X POST https://api.backgroundcut.co/v2/cut/ \
     -H "Authorization: Token YOUR_API_TOKEN" \
     -F "image_file=@input_image.jpg" \
     -F "quality=High" \
     -F "return_type=PNG" \
     --output output.png

Code Examples

import requests

# Your API Token (keep this secret, server-side only)
API_TOKEN = "YOUR_API_TOKEN"

# API endpoint
url = "https://api.backgroundcut.co/v2/cut/"

# Set up authentication header
headers = {
    "Authorization": f"Token {API_TOKEN}"
}

# Open and send the image
with open("input_image.jpg", "rb") as image_file:
    files = {"image_file": image_file}
    data = {
        "max_resolution": 4000000,
        "quality": "High",
        "return_type": "PNG"
    }
    response = requests.post(url, headers=headers, files=files, data=data)

# Save the result
if response.status_code == 200:
    with open("output.png", "wb") as output_file:
        output_file.write(response.content)
    print("Success! Background removed.")
else:
    print(f"Error {response.status_code}: {response.text}")

API Reference

Endpoint
URLhttps://api.backgroundcut.co/v2/cut/
MethodPOST
Authorization HeaderToken YOUR_API_TOKEN
Request Parameters
image_fileThe image file to process. Supports PNG, JPG, WEBP. Maximum size: 12MB
max_resolutionMaximum output resolution in pixels. Up to 12,000,000 (12MP). Default: 12000000
quality'High', 'Medium' (default), or 'Low'
return_type'PNG' (default) or 'WEBP'. For WEBP, specify quality: WEBP_50, WEBP_75, WEBP_90
channels'rgba' (default) for full image, or 'alpha' for mask only

Method 2: Using Access Tokens

For third-party integrations and client-side applications

Why Use Access Tokens?

Access Tokens are designed for developers building applications where end users need to send images directly to BackgroundCut. This is a two-step process:

Step 1: Your Server

Use your API Token to request an Access Token from BackgroundCut. Send this Access Token to your user's browser/app.

Step 2: User's Browser/App

The user sends their image + Access Token directly to BackgroundCut API. No API Token needed!

Comparison: API Token vs Access Token

With API Token only: All images must go through your server

  1. User wants to remove background, uploads image to Your Server
  2. Your Server sends image to BackgroundCut API with your API Token
  3. BackgroundCut processes and returns image to Your Server
  4. Your Server returns processed image to User

Problem: Image uploads/downloads 4 times. Your server handles all the heavy traffic.

With Access Token: Images go directly to BackgroundCut

  1. User wants to remove background, sends a simple request (no image) to Your Server
  2. Your Server requests an Access Token from BackgroundCut using your API Token
  3. Your Server returns the Access Token to the User
  4. User sends the Access Token + image directly to BackgroundCut API
  5. BackgroundCut returns processed image directly to User

Benefit: Image only transfers 2 times. Your server only handles tiny token requests.

Benefits:
  • Faster: Images go directly to BackgroundCut without routing through your server
  • Cheaper: Your server doesn't handle large image files, reducing bandwidth costs
  • Scalable: Your backend only handles small token requests
  • Secure: Your API Token stays secret on your server

Code Examples

import requests

# ============================================
# STEP 1: Your Backend Server
# Get an Access Token using your API Token
# ============================================

API_TOKEN = "YOUR_API_TOKEN"  # Keep secret on your server

# Request an Access Token from BackgroundCut
token_response = requests.post(
    "https://backgroundcut.co/api-v2-token/",
    headers={"Authorization": f"Token {API_TOKEN}"},
    data={
        "max_resolution": 4000000,
        "quality": "High",
        "return_type": "PNG"
    }
)

access_token = token_response.json()['access_token']
# Send this access_token to your frontend/client

# ============================================
# STEP 2: Frontend/Client Code
# Use the Access Token to send image directly
# ============================================

# The client received access_token from your backend
with open("input_image.jpg", "rb") as image_file:
    response = requests.post(
        "https://api.backgroundcut.co/v2/cut/",
        files={"image_file": image_file},
        data={"access_token": access_token}  # No API Token needed!
    )

if response.status_code == 200:
    with open("output.png", "wb") as f:
        f.write(response.content)
    print("Success! Background removed.")

API Reference

Step 1: Get Access Token (Server-Side)
URLhttps://backgroundcut.co/api-v2-token/
MethodPOST
Authorization HeaderToken YOUR_API_TOKEN
Request Parameters
max_resolutionMaximum output resolution. Up to 12,000,000 (12MP). Default: 12000000
quality'High', 'Medium' (default), or 'Low'
return_type'PNG' (default), 'WEBP', or 'WEBP_XX'
channels'rgba' (default) or 'alpha'
Response
{"success": true, "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."}
Step 2: Process Image (Client-Side)
URLhttps://api.backgroundcut.co/v2/cut/
MethodPOST
AuthorizationNot required (Access Token is used instead)
Request Parameters
access_tokenThe Access Token from Step 1 (required)
image_fileThe image file to process. Supports PNG, JPG, WEBP. Maximum size: 12MB
Example
curl -X POST https://api.backgroundcut.co/v2/cut/ \
     -F "access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6..." \
     -F "image_file=@input_image.jpg" \
     --output output.png

Common Reference

Response Codes

200Success - processed image returned
400Invalid parameters or unable to process image
401Missing or invalid API Token / Access Token
402No credits remaining
405Invalid request method (use POST)
413File size exceeds 12MB limit
429Rate limit exceeded

Rate Limits

  • Default: 40 requests per minute
  • Dynamic Scaling: Rate limit increases based on usage, up to 500 requests per minute

Output Formats

  • PNG: Lossless quality with transparency. Larger file size.
  • WEBP: Recommended for web. Smaller files with transparency. Use WEBP_75 for good balance.