Background removal, one HTTP call away.

Overview

Base URL https://www.bgclear.ai/api/v1. All endpoints are versioned under /api/v1 and will never break — new fields are only ever added. Requests and responses are JSON unless you upload a file (multipart) or download a result (binary image).

• Sync — POST /remove returns the finished image in one call (up to 4 MP, 30 s).
• Async — POST /jobs for larger images or callbacks; poll GET /jobs/{id}.
• Batch — POST /jobs/batch queues up to 50 images at once.
• Credits — previews are free; a full-resolution result costs 1 credit, charged only on success.

Authentication

Create a key on your API dashboard and send it as a Bearer token. Keys look like bgc_live_… (or bgc_test_…). They are shown once at creation and stored hashed — if you lose one, revoke it and create another.

Authorization: Bearer bgc_live_YOUR_KEY

Your first key comes with 10 free credits. Buy more on the pricing page; they never expire.

Quick start

Remove the background from a local file and save the transparent PNG:

curl -X POST https://www.bgclear.ai/api/v1/remove \
  -H "Authorization: Bearer bgc_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "size=full" \
  -o result.png

That's it. size=full returns native resolution and costs 1 credit; drop it (or use size=preview) for a free 800 px preview while you build.

Remove backgrounds from the command line

Keep your image workflow in the terminal. BGClear CLI processes a file, a folder or a quoted wildcard and saves transparent PNGs on your computer. It works with Python 3.10+ on Windows, macOS and Linux, with no extra Python packages to install.

Download BGClear CLI v1.0.0 → One Python file. On Windows, install Python with the Python launcher, then open PowerShell in the folder where you saved the script. Check your installation with py --version.

1. Create a free preview key

Sign in and create a preview-only key on the API dashboard. No card is needed for previews. Set BGCLEAR_API_KEY in your shell; keep the key out of shared scripts, screenshots and source control. The examples set it for the current shell session.

2. Download the script and process your images

# Download BGClear CLI (Python 3.10+ required)
Invoke-WebRequest https://www.bgclear.ai/downloads/bgclear.py -OutFile bgclear.py

# Use a preview-only key from your API dashboard
$env:BGCLEAR_API_KEY = "YOUR_API_KEY"
py .\bgclear.py "photo.jpg" --output "cutout.png"

# Process a folder, including its subfolders
py .\bgclear.py ".\photos" --recursive --output-dir ".\cutouts"

# Read the exit code: 0 = all images saved
$LASTEXITCODE

Inputs can be PNG, JPEG or WebP, up to 25 MiB each. Quote paths containing spaces. Without --output, results go into bgclear-output with _nobg.png added to each filename. Recursive folder processing preserves subfolders and skips the output directory.

Free previews first. Full resolution when you choose.

The default is --size preview: zero credits, original aspect ratio and a longest side of at most 800 pixels. There is no automatic upgrade to paid processing. For full resolution, explicitly add --size full and use a full-access key with credits. Each successful image costs 1 credit; this CLI supports full-resolution inputs up to 4 megapixels.

Images are uploaded to BGClear for processing. The CLI always requests store=false, so results are returned directly rather than saved in your account image history or offered through a reusable result URL. Your local input stays untouched. Read the API data-handling details for infrastructure and retention information.

Use it in a script

py .\bgclear.py ".\photos\*.jpg" --output-dir ".\cutouts"
if ($LASTEXITCODE -ne 0) {
    Write-Error "Some images were not saved. Check the CLI output."
}

• Existing files: choose another output path or add --overwrite. The CLI refuses to overwrite an input image. Outputs need a filesystem with hard-link support, such as Windows NTFS.
• Rate limits: requests run one at a time, with a pause between images. Preview keys allow 10 processing requests per minute, shared with other uses of that key.
• Busy service: rate-limit and explicit GPU-busy responses get up to three retries, respecting the server's wait time. Long waits stop the run.
• Interrupted requests: connection failures are not retried automatically. Check API usage before retrying a full-resolution request, since processing may already have completed.
• Exit codes: 0 means every image was saved; 1 means a processing or file error; 2 means invalid command arguments; 130 means you cancelled.

Run py bgclear.py --help for every option. If Windows cannot find py, try python after checking it is Python 3.10 or newer. For macOS and Linux, use python3. To update, download the script again and check --version.

Moving from remove.bg? This is a separate CLI with its own options. Send your existing command, with the API key removed, through Get help and we can help map it.

Remove a background (sync)

POST/api/v1/remove

Accepts multipart/form-data or application/json. Provide exactly one image source: image_file (binary upload), image_url (public URL) or image_file_b64 (base64). Returns the image bytes by default; send Accept: application/json to get metadata and a download URL instead.

JSON body + JSON response

curl -X POST https://www.bgclear.ai/api/v1/remove \
  -H "Authorization: Bearer bgc_live_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/photo.jpg", "size": "full", "format": "webp", "bg_color": "ffffff"}'

{
  "id": "0b2e5f1c-9a3d-4f2e-b8c1-6d7e8f9a0b1c",
  "url": "https://www.bgclear.ai/api/v1/results/0b2e5f1c-9a3d-4f2e-b8c1-6d7e8f9a0b1c",
  "width": 1600,
  "height": 1067,
  "credits_charged": 1,
  "credits_remaining": 499,
  "processing_ms": 1840
}

Idempotent retries

Send an Idempotency-Key header (any unique string, e.g. a UUID). Retrying with the same key must use identical inputs and parameters. Different requests receive HTTP 409. Retry metadata lasts 24 hours, but saved images expire after six hours. Deleted, expired or unstored images cannot be replayed.

Images over 4 MP at size=full are rejected with invalid_request — use async jobs for those. See parameters for the full list.

Async jobs

POST/api/v1/jobs

Same inputs and parameters as /remove, but the image is queued and processed by a GPU worker. Use it for images over 4 MP, when you don't want to hold a connection open, or when you want a callback. Returns 202 with a job_id. Add an X-Callback-Url header to be notified on completion.

curl -X POST https://www.bgclear.ai/api/v1/jobs \
  -H "Authorization: Bearer bgc_live_YOUR_KEY" \
  -H "X-Callback-Url: https://yourapp.com/hooks/bgclear" \
  -F "[email protected]" \
  -F "size=full"

If the queue is saturated you get 503 gpu_unavailable with a Retry-After header instead of an unbounded wait.

Job status

GET/api/v1/jobs/{job_id}

status is one of queued, processing, done or failed. When done, the response includes url (the result image), credits_charged and credits_remaining. When failed, it includes error and nothing was charged.

curl https://www.bgclear.ai/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer bgc_live_YOUR_KEY"

Batch jobs

POST/api/v1/jobs/batch

JSON only. Pass up to 50 images in images (each with image_url or image_file_b64). Top-level parameters like size or format apply to every image; per-image keys override them. One job is created per image and you get all the ids back.

curl -X POST https://www.bgclear.ai/api/v1/jobs/batch \
  -H "Authorization: Bearer bgc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "size": "full",
    "format": "png",
    "images": [
      {"image_url": "https://example.com/a.jpg"},
      {"image_url": "https://example.com/b.jpg"},
      {"image_file_b64": "<base64 data>"}
    ]
  }'

Callbacks (webhooks)

When a job finishes, we POST the result to your X-Callback-Url. Delivery is retried 3 times with exponential backoff on network errors or 5xx responses. Respond with any 2xx.

POST https://yourapp.com/hooks/bgclear
Content-Type: application/json
X-Bgclear-Signature: sha256=<hex HMAC-SHA256 of the raw body>

{
  "job_id": "0b2e5f1c-9a3d-4f2e-b8c1-6d7e8f9a0b1c",
  "status": "done",
  "url": "https://www.bgclear.ai/api/v1/results/0b2e5f1c-9a3d-4f2e-b8c1-6d7e8f9a0b1c",
  "credits_charged": 1,
  "credits_remaining": 498
}

The X-Bgclear-Signature header carries an HMAC-SHA256 of the raw body. Per-key signing secrets are on the roadmap; until then treat the callback as a hint and confirm with GET /jobs/{id} before acting on it.

Account

GET/api/v1/account

Your current credit balance, plan and credits used this calendar month.

curl https://www.bgclear.ai/api/v1/account -H "Authorization: Bearer bgc_live_YOUR_KEY"

Usage

GET/api/v1/usage

Credits used per day for the last 30 days, newest first.

curl https://www.bgclear.ai/api/v1/usage -H "Authorization: Bearer bgc_live_YOUR_KEY"

Parameters

Shared by /remove, /jobs and /jobs/batch. Send them as form fields or JSON keys.

Headers

Request

Response

Errors

Every non-2xx response has the same shape, so one error handler covers the whole API:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits. Buy credits at https://www.bgclear.ai/api-pricing/",
    "docs": "https://www.bgclear.ai/api-docs/"
  }
}

Limits & rate limits

For a card-free evaluation, use a preview-only key, size=preview, store=false and Accept: image/png. Read the API data-handling and change-notice policy before uploading photographs.

• Max upload 25 MB, max 50 megapixels.
• Sync /remove: up to 4 MP at size=full; hard timeout 30 s. Larger → /jobs.
• Batch: 50 images per request.
• New keys default to preview-only: full, auto and async requests are rejected before processing. No card is required.
• Send DELETE /api/v1/results/{id} with your API key to delete a saved output immediately. Deletion also prevents replaying that output. It cannot remove copies already downloaded by a client.
• API processing uses a separate path without account image history or human-review galleries. New API images are excluded from account backups.
• One API inference runs at a time. A busy GPU returns HTTP 503 with Retry-After; respect that delay, avoid parallel retries and use exponential backoff. Rate limits are ceilings, not guaranteed throughput.
• Rate limit: 10 requests / minute for preview-only keys; up to 60 for full-access keys (sliding window). Need more? Ask via the feedback form in the footer.
• Result URLs (/api/v1/results/{id}) require the owning account’s API key and expire after six hours. Cleanup runs every five minutes; expired results cannot be downloaded even if cleanup is delayed.

Migrating from remove.bg

Field names match remove.bg so most integrations only need a new base URL and key: image_file, image_url, image_file_b64, size, bg_color, crop, type, format.

Questions or a feature you need? Use the feedback form in the footer — it goes straight to the people who built this.