BackgroundCut API v3
Built for browsers and mobile apps. Direct uploads, multiple variants, AI segmentation.
Short-lived tokens for secure client-side uploads. Your API key stays on your server.
Generate full-size PNG, WebP thumbnail, and custom backgrounds in a single request.
Point-based segmentation. Pay once, refine unlimited times.
Interactive API Documentation
Try API requests directly from your browser using the interactive docs:
How API v3 Works
API v3 uses a two-server architecture. Your server talks to the Token API to get short-lived access tokens. Your user's browser sends images directly to the Processing API.
Requests a token from your server
Calls BackgroundCut Token API with your Bearer key
Your server forwards token to user's browser
Browser sends image + token to Processing API
Result: Your API key stays secure. Images go directly from user to processing server via GeoDNS.
See the full Integration Guide for a working implementation of this pattern.
Token API
https://backgroundcut.co/api/v3/ Called from your server with your API key. Returns short-lived access tokens. Credits are deducted here.
Processing API
https://api.backgroundcut.co/v3/ Called from user's device with the access token. Receives images, returns results. GeoDNS routed.
Background Removal
Remove backgrounds with multiple output variants in a single request.
Step 1: Get Access Token Your Server
| URL | POST https://backgroundcut.co/api/v3/remove-bg/token/ |
| Authorization | Bearer YOUR_API_KEY |
| Content-Type | application/json |
Request Body
| output_variants | Array of variant configurations (see Output Variants below) |
| unique_filename | (Optional) Reuse a previously uploaded image. See Image Reuse |
Response
{
"access_token": "eyJ..."
}Step 2: Process Image User's Device
| URL | POST https://api.backgroundcut.co/v3/remove-bg/ |
| Content-Type | multipart/form-data |
Form Fields
| token | The access token from Step 1 |
| image | Image file (PNG, JPG, WebP). Max 12MB. Optional if unique_filename was provided in the token request. |
Response
{
"status": "success",
"unique_filename": "abc123-def456-...",
"input_url": "https://...",
"output_urls": {
"full": "https://...result.png",
"thumbnail": "https://...result.webp"
}
}Output Variants
Configure multiple output versions in a single API call. Each variant can have different settings:
{
"output_variants": [
{
"variant_name": "full",
"max_resolution": 12000000,
"format": "png",
"background_color": "transparent",
"quality": "high",
"output_compression": 90,
"autocrop": false
},
{
"variant_name": "thumbnail",
"max_resolution": 250000,
"format": "webp",
"background_color": "#ffffff",
"quality": "medium",
"output_compression": 80,
"autocrop": true
}
]
}Variant Options
| variant_name * | Required. Your identifier for this variant (e.g., "full", "thumb", "preview"). This is the only required field. |
| max_resolution | Default: 12,000,000 (12MP). Range: 250,000 to 25,000,000. |
| format | Default: png. Options: png (lossless), jpg (no transparency), webp |
| background_color | Default: transparent. Hex color like #ffffff, #1A01FF |
| quality | Default: high. Options: high, medium, low |
| output_compression | Default: 90. Range: 1–100 (for jpg/webp output) |
| autocrop | Default: false. Crop to object bounds (+0.5 credits per variant) |
AI Cut
Precisely select objects using point-based segmentation.
Initialize session (2 credits)
Green = include, Red = exclude
Add more points to perfect selection
Get AI Cut Token Your Server
| URL | POST https://backgroundcut.co/api/v3/ai-cut/token/ |
| Authorization | Bearer YOUR_API_KEY |
| Cost | 2 credits (one-time per session) |
Response
{
"access_token": "eyJ..."
}Initialize Session User's Device
| URL | POST https://api.backgroundcut.co/v3/ai-cut/initialize/ |
| Content-Type | multipart/form-data |
Form Fields
| token | Access token from previous step |
| image | Image file to segment |
Response
{
"unique_filename": "abc123-...",
"s3_path": "...",
"bucket": "..."
}Segment with Points FREE
| URL | POST https://api.backgroundcut.co/v3/ai-cut/segment/ |
| Content-Type | application/json |
Request Body
{
"unique_filename": "abc123-...",
"greenDots": [{"x": 250, "y": 300}, {"x": 260, "y": 310}],
"redDots": [{"x": 50, "y": 50}],
"request_number": 1
}Response
{
"status": "completed",
"unique_filename": "...",
"output_url": "https://...",
"request_number": 1
}Coming Soon
POST /v3/generate-ai-background/
POST /v3/inpaint/
Response Codes
| 200 | Success |
| 400 | Invalid parameters or request body |
| 401 | Missing or invalid API key / access token |
| 402 | Insufficient credits |
| 404 | Image not found (when reusing unique_filename) |
| 422 | Validation error (malformed request) |
| 429 | Rate limit exceeded |
| 503 | Server busy, try again later |
| 504 | Processing timeout |