BackgroundCut API v2
The power of BackgroundCut, automated
Two Ways to Authenticate
Your permanent secret key. Use it directly from your server to process images. Simple, one-step process.
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
Your API Token is a permanent secret key that identifies your account. You can find it in your dashboard. Never expose this token in client-side code — it should only be used on your server.
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.pngCode 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
| URL | https://api.backgroundcut.co/v2/cut/ |
| Method | POST |
| Authorization Header | Token YOUR_API_TOKEN |
Request Parameters
| image_file | The image file to process. Supports PNG, JPG, WEBP. Maximum size: 12MB |
| max_resolution | Maximum 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
An Access Token is a single-use, short-lived token that you generate using your API Token. Unlike your API Token, Access Tokens are safe to use in client-side code because they expire after use and don't expose your account credentials.
- Valid for 5 minutes: Access Tokens expire 5 minutes after generation if not used.
- Single-use only: Once an Access Token is used to process an image, it immediately expires and cannot be used again.
- Credit deducted on generation: When you request an Access Token, the credit for background removal is deducted immediately. This grants permission to use the API endpoint for one image processing request.
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:
Use your API Token to request an Access Token from BackgroundCut. Send this Access Token to your 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
- User wants to remove background, uploads image to Your Server
- Your Server sends image to BackgroundCut API with your API Token
- BackgroundCut processes and returns image to Your Server
- 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
- User wants to remove background, sends a simple request (no image) to Your Server
- Your Server requests an Access Token from BackgroundCut using your API Token
- Your Server returns the Access Token to the User
- User sends the Access Token + image directly to BackgroundCut API
- 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)
| URL | https://backgroundcut.co/api-v2-token/ |
| Method | POST |
| Authorization Header | Token YOUR_API_TOKEN |
Request Parameters
| max_resolution | Maximum 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)
| URL | https://api.backgroundcut.co/v2/cut/ |
| Method | POST |
| Authorization | Not required (Access Token is used instead) |
Request Parameters
| access_token | The Access Token from Step 1 (required) |
| image_file | The 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.pngCommon Reference
Response Codes
| 200 | Success - processed image returned |
| 400 | Invalid parameters or unable to process image |
| 401 | Missing or invalid API Token / Access Token |
| 402 | No credits remaining |
| 405 | Invalid request method (use POST) |
| 413 | File size exceeds 12MB limit |
| 429 | Rate 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.