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 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 within 24 hours returns the cached result and never charges twice.

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

• 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.
• Rate limit: 60 requests / minute per key (sliding window). Need more? Ask via the feedback form in the footer.
• Result URLs (/api/v1/results/{id}, no auth needed) stay valid for 24 hours — keep your own copy.

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.