API Documentation
Integrate ClearBG.ai into your application with our simple REST API. Process up to 500 images per minute.
Getting Started
Get up and running in 3 steps:
- Get your API Key — Sign in and visit your Dashboard to generate a key.
- Make your first request — Use the code samples below.
- Review the reference — Adjust parameters as needed.
Authentication
All API requests require an API key passed via the X-Api-Key header:
curl -H 'X-Api-Key: YOUR_API_KEY' \
https://api.clearbg.ai/v1.0/removebgRemove Background
POST/v1.0/removebg
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| image_file | file | Source image file (binary upload) |
| image_url | string | Source image URL (alternative to file) |
| size | string | auto (default), preview (≤0.25MP, free), small, medium, hd, full |
| type | string | auto (default), person, product, animal, car, other |
| format | string | png (default), jpg, webp, zip |
| bg_color | string | Background color, e.g. #FF0000, blue |
| bg_image_url | string | URL of background image to composite |
| channels | string | rgba (default) or alpha (mask only) |
| crop | boolean | true to crop to foreground, false (default) |
| crop_margin | string | Margin around crop, e.g. 10px, 20% |
| scale | string | Scale relative to original, e.g. 80%, original |
| position | string | Subject position, e.g. center, original, 50% 70% |
Code Samples
cURL
curl -H 'X-Api-Key: YOUR_API_KEY' \
-F 'image_file=@/path/to/photo.jpg' \
-F 'size=auto' \
-f https://api.clearbg.ai/v1.0/removebg \
-o result.pngNode.js
import fs from "node:fs";
async function removeBg(blob) {
const formData = new FormData();
formData.append("size", "auto");
formData.append("image_file", blob);
const response = await fetch("https://api.clearbg.ai/v1.0/removebg", {
method: "POST",
headers: { "X-Api-Key": "YOUR_API_KEY" },
body: formData,
});
if (response.ok) {
return await response.arrayBuffer();
} else {
throw new Error(`${response.status}: ${response.statusText}`);
}
}
const fileBlob = await fs.openAsBlob("/path/to/photo.jpg");
const result = await removeBg(fileBlob);
fs.writeFileSync("result.png", Buffer.from(result));Python
import requests
response = requests.post(
"https://api.clearbg.ai/v1.0/removebg",
files={"image_file": open("/path/to/photo.jpg", "rb")},
data={"size": "auto"},
headers={"X-Api-Key": "YOUR_API_KEY"},
)
if response.status_code == requests.codes.ok:
with open("result.png", "wb") as out:
out.write(response.content)
else:
print("Error:", response.status_code, response.text)PHP
$client = new GuzzleHttp\Client();
$res = $client->post('https://api.clearbg.ai/v1.0/removebg', [
'multipart' => [
['name' => 'image_file', 'contents' => fopen('/path/to/photo.jpg', 'r')],
['name' => 'size', 'contents' => 'auto']
],
'headers' => ['X-Api-Key' => 'YOUR_API_KEY']
]);
$fp = fopen("result.png", "wb");
fwrite($fp, $res->getBody());
fclose($fp);Response Headers
| Header | Description |
|---|---|
| X-Credits-Charged | Number of credits charged (0 for preview) |
| X-Credits-Remaining | Remaining credit balance |
| X-Width | Output image width in pixels |
| X-Height | Output image height in pixels |
| X-Type | Detected foreground type (person, product, animal, etc.) |
Error Responses
| Code | Description |
|---|---|
| 400 | Invalid parameters or unsupported image format |
| 401 | Missing or invalid API key |
| 402 | Insufficient credits |
| 403 | IP rate limit exceeded (free tier) |
| 429 | API rate limit exceeded |
| 500 | Internal processing error |
Account Info
GET/v1.0/account
Retrieve your account details and credit balance.
curl -H 'X-Api-Key: YOUR_API_KEY' \
https://api.clearbg.ai/v1.0/accountResponse:
{
"data": {
"attributes": {
"credits": {
"total": 50,
"subscription": 45,
"payg": 5,
"enterprise": 0
},
"api": {
"free_calls": 50,
"sizes": "all"
}
}
}
}Output Formats
| Format | Max Resolution | Transparency | Notes |
|---|---|---|---|
| PNG | 10 MP | ✓ | Default, best for web |
| JPG | 50 MP | ✗ | Smallest file size |
| WebP | 50 MP | ✓ | Modern browsers |
| ZIP | 50 MP | ✓ | Fastest — color.jpg + alpha.png |
Rate Limits
You can process up to 500 images per minute through the API, scaled by input megapixels.
| Input Size | Megapixels | Rate Limit |
|---|---|---|
| 625 × 400 | 1 MP | 500/min |
| 1600 × 1200 | 2 MP | 250/min |
| 2500 × 1600 | 4 MP | 125/min |
| 4000 × 2500 | 10 MP | 50/min |
| 8000 × 6250 | 50 MP | 10/min |
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After
Libraries & SDKs
Node.jsJavaScript / TypeScript
npm install clearbgPythonPython 3.8+
pip install clearbgRubyRuby 2.7+
gem install clearbgPHPPHP 8.0+
composer require clearbg/sdkCLICross-platform
npm install -g clearbg-cli.NETC# / .NET 6+
dotnet add package ClearBG