API documentation

Background Removal API

One POST with an image returns a full-resolution transparent PNG. $0.01 per image, no subscription.

Remove a background in 4 steps

One endpoint, one required header. Most people are done in a couple of minutes.

Get your API key

Create a free account, then generate a key on the API Keys page. Keep it on your server: anyone holding it can spend your credits.

Get an API key

Send your image

POST the file to /v1/remove as multipart form data, in a field named image.

curl -X POST "https://api.nobg.space/v1/remove" \
  -H "X-API-Key: $NOBG_API_KEY" \
  -F "[email protected]" \
  --output result.png

Save the result

A successful response body is the image itself — a transparent PNG at the original resolution, not JSON. Write the bytes straight to a file.

Your remaining balance comes back on the X-Credits-Remaining header, so you don't need to check Billing after every call.

Handle failures

Anything that isn't a 200 returns JSON like { "error": "rate_limited" }. Switch on that code.

You're never charged for a request that returned no image — failures are refunded automatically. Retry on 429, 500, 502 and 504; fix the request for anything else.

Prefer to try it without writing code?

Open the Playground

Reference

Endpoints

POST /v1/remove	Remove the background from an image. Returns a transparent PNG.	1 credit
GET /v1/account	Your credit balance and auto top-up status.	Free
GET /health	Liveness check. Returns "ok" when the API is up.	Free

Check your balance — GET /v1/account

Free and read-only: it never spends a credit. Use it before a large batch, or to show your balance in your own tools. Same authentication and rate limit as /v1/remove.

curl "https://api.nobg.space/v1/account" \
  -H "X-API-Key: $NOBG_API_KEY"

Response

{
  "credits": {
    "remaining": 14936,
    "used": 64,
    "total": 15000
  },
  "auto_topup": {
    "enabled": true,
    "threshold_credits": 500,
    "amount_usd": 25
  }
}

auto_topup.enabled is true only when auto top-up is switched on, has a saved card, and isn't paused after failed payments. When it's false, the threshold and amount are omitted.

All error codes

missing_api_key	401	No key sent — set the X-API-Key header.
invalid_api_key	401	Key does not exist or was revoked. Make a new one.
key_expired	401	Key is past its expiry date. Make a new one.
insufficient_credits	402	Out of credits. Top up under Billing.
rate_limited	429	Over 60 requests/minute. Wait the Retry-After seconds, then retry.
no_image_field	400	Form field must be named exactly "image".
empty_body	400	Request body was empty.
image_too_large	413	Over 25 MB or ~30 megapixels. Downscale it.
model_timeout	504	Model took too long. Retry — credit refunded.
processing_failed	502	Model failed. Retry — credit refunded.
internal_error	500	Server error. Retry — credit refunded.

Image requirements

Formats	JPEG, PNG, WebP, GIF, BMP, TIFF
Max file size	25 MB
Max resolution	~30 megapixels
Output	PNG with transparency, same size as input

Phone photos are auto-rotated using EXIF orientation. Oversized images are rejected before processing, so they never cost a credit.

Authentication & rate limits

Either header works — use whichever your HTTP client makes easier:

X-API-Key: nbg_your_key_here
Authorization: Bearer nbg_your_key_here

60 requests per minute per key. Going over returns 429 with a Retry-After header (seconds to wait), and costs no credit. For bulk jobs, use a small worker pool with backoff rather than firing everything at once.

How credits work

One credit per successful request — size and processing time don’t matter.
The credit is reserved before the model runs, so you can’t overspend.
Failed or timed-out requests are refunded automatically.
Rejected requests (bad key, oversized image, rate limited) never cost anything.
Every charge and refund shows up in Activity.