remove.bg-compatible Background Removal API

Migrate from remove.bg in one line

The only differences in a typical call are the host and the key:

curl -H 'X-Api-Key: YOUR_REMOVE_BG_KEY' \
  -F 'image_file=@photo.jpg' \
  -F 'size=auto' \
  -f https://api.remove.bg/v1.0/removebg -o no-bg.png

curl -H 'X-Api-Key: YOUR_CLEARBG_KEY' \
  -F 'image_file=@photo.jpg' \
  -F 'size=auto' \
  -f https://api.clearbg.org/v1.0/removebg -o no-bg.png

Background removal API endpoint and authentication

POST https://api.clearbg.org/v1.0/removebg removes the background. GET https://api.clearbg.org/v1.0/account returns your balance and costs nothing.

Send your key in the X-Api-Key header. Keys start with cbg_live_, are shown once when you create them, and can be revoked on your account page; each account can have 10 active keys. OAuth is not supported. The API has no CORS headers: call it from your server, never from a browser, so the key stays private.

Request bodies can be multipart/form-data, application/json or application/x-www-form-urlencoded. Give exactly one image source: image_file (a file upload), image_file_b64 (base64, with or without a data: prefix) or image_url (a public http or https address we download, up to 3 redirects, 20 seconds and 25 MB).

Input images: JPG, PNG or WebP (checked from the file's bytes, not its name), up to 25 MB and 12,000 pixels on a side.

Parameters

Fields that don't change the picture are accepted and ignored. Fields that would change it in a way we can't do are refused with a 400 error, so you never get a different image without knowing.

Response

By default the response body is the image itself (image/png, image/webp or image/jpeg). Send Accept: application/json to get remove.bg's JSON instead, with the image as base64 in data.result_b64 and the foreground box in foreground_top, foreground_left, foreground_width and foreground_height.

curl -H 'X-Api-Key: YOUR_CLEARBG_KEY' \
  -H 'Accept: application/json' \
  -F 'image_url=https://example.com/photo.jpg' \
  -F 'size=full' -F 'format=jpg' -F 'bg_color=ffffff' \
  https://api.clearbg.org/v1.0/removebg

{"data":{"result_b64":"iVBORw0KGgo…","foreground_top":0,"foreground_left":0,"foreground_width":1200,"foreground_height":800}}

Response headers

Check your balance

curl -H 'X-Api-Key: YOUR_CLEARBG_KEY' https://api.clearbg.org/v1.0/account

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

Errors

Errors use remove.bg's shape: {"errors":[{"title":"…","code":"…","detail":"…"}]} (detail is sometimes missing). A failed request never costs a credit.

HTTP/1.1 402 Payment Required
{"errors":[{"title":"Insufficient credits","code":"insufficient_credits","detail":"A full-resolution image costs 1 credit. Buy credits on https://clearbg.org/pricing."}]}

Rate limits and free previews

• 500 requests a minute per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; past the limit you get a 429 with Retry-After. remove.bg counts megapixel-weighted images instead of requests.
• 50 preview calls (0.25 megapixels, the default size) a month are free per email address (several accounts on one address share them). After that, previews return 402 until the next calendar month (UTC); remove.bg charged 0.25 credits each instead.
• Up to 4 images per account are processed at the same time, across all of its keys. A fifth request at once gets a 429 with Retry-After: 2; send in parallel up to 4 and queue the rest.
• If the service is paused or busy you get a 503 with Retry-After, and nothing is charged.
• Requests are synchronous: we wait up to 90 seconds for the GPU, and if it was still starting up we try once more for up to 45 seconds. Set your client timeout to at least 150 seconds.

Background removal API price per image

One credit is one full-resolution image, on the API and on the website. Plan credits are used first, then pack credits. Packs never expire; plan credits reset every month. See pricing to buy.

Code samples

Each sample uploads photo.jpg at full resolution and saves the transparent PNG. Put your key in the CLEARBG_API_KEY environment variable.

curl -H 'X-Api-Key: YOUR_CLEARBG_KEY' \
  -F 'image_file=@photo.jpg' \
  -F 'size=full' \
  -f https://api.clearbg.org/v1.0/removebg -o photo-clearbg.png

import os
import requests

response = requests.post(
    "https://api.clearbg.org/v1.0/removebg",
    files={"image_file": open("photo.jpg", "rb")},
    data={"size": "full"},
    headers={"X-Api-Key": os.environ["CLEARBG_API_KEY"]},
    timeout=120,
)
if response.status_code == 200:
    with open("photo-clearbg.png", "wb") as out:
        out.write(response.content)
else:
    print(response.status_code, response.json()["errors"])

// Node.js 18 or later (built-in fetch, FormData and Blob)
import { readFile, writeFile } from 'node:fs/promises';

const form = new FormData();
form.append('image_file', new Blob([await readFile('photo.jpg')]), 'photo.jpg');
form.append('size', 'full');

const res = await fetch('https://api.clearbg.org/v1.0/removebg', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.CLEARBG_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!res.ok) throw new Error(JSON.stringify(await res.json()));
await writeFile('photo-clearbg.png', Buffer.from(await res.arrayBuffer()));

<?php
$ch = curl_init('https://api.clearbg.org/v1.0/removebg');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('CLEARBG_API_KEY')],
    CURLOPT_POSTFIELDS => [
        'image_file' => new CURLFile('photo.jpg'),
        'size' => 'full',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status === 200) {
    file_put_contents('photo-clearbg.png', $body);
} else {
    echo $body;
}

Get a background removal API key

Sign in with Google or an email link, then create a key under API keys on your account page. Copy it when it is shown: we only keep a hash of it.

Get an API key