ClearBG.ai

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:

  1. Get your API Key — Sign in and visit your Dashboard to generate a key.
  2. Make your first request — Use the code samples below.
  3. 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/removebg

Remove Background

POST/v1.0/removebg

Request Parameters

ParameterTypeDescription
image_filefileSource image file (binary upload)
image_urlstringSource image URL (alternative to file)
sizestringauto (default), preview (≤0.25MP, free), small, medium, hd, full
typestringauto (default), person, product, animal, car, other
formatstringpng (default), jpg, webp, zip
bg_colorstringBackground color, e.g. #FF0000, blue
bg_image_urlstringURL of background image to composite
channelsstringrgba (default) or alpha (mask only)
cropbooleantrue to crop to foreground, false (default)
crop_marginstringMargin around crop, e.g. 10px, 20%
scalestringScale relative to original, e.g. 80%, original
positionstringSubject 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.png
Node.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

HeaderDescription
X-Credits-ChargedNumber of credits charged (0 for preview)
X-Credits-RemainingRemaining credit balance
X-WidthOutput image width in pixels
X-HeightOutput image height in pixels
X-TypeDetected foreground type (person, product, animal, etc.)

Error Responses

CodeDescription
400Invalid parameters or unsupported image format
401Missing or invalid API key
402Insufficient credits
403IP rate limit exceeded (free tier)
429API rate limit exceeded
500Internal 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/account

Response:

{
  "data": {
    "attributes": {
      "credits": {
        "total": 50,
        "subscription": 45,
        "payg": 5,
        "enterprise": 0
      },
      "api": {
        "free_calls": 50,
        "sizes": "all"
      }
    }
  }
}

Output Formats

FormatMax ResolutionTransparencyNotes
PNG10 MPDefault, best for web
JPG50 MPSmallest file size
WebP50 MPModern browsers
ZIP50 MPFastest — color.jpg + alpha.png

Rate Limits

You can process up to 500 images per minute through the API, scaled by input megapixels.

Input SizeMegapixelsRate Limit
625 × 4001 MP500/min
1600 × 12002 MP250/min
2500 × 16004 MP125/min
4000 × 250010 MP50/min
8000 × 625050 MP10/min

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After

Libraries & SDKs

Node.jsJavaScript / TypeScript
npm install clearbg
PythonPython 3.8+
pip install clearbg
RubyRuby 2.7+
gem install clearbg
PHPPHP 8.0+
composer require clearbg/sdk
CLICross-platform
npm install -g clearbg-cli
.NETC# / .NET 6+
dotnet add package ClearBG