On this page
Background removal API docs
Send an image to one endpoint and get a transparent PNG back. This guide covers everything from your first request to running in production.
Quickstart
1. Create an API key
Sign up, then create a key on the API Keys page. New accounts get 20 free credits, and no card is needed.
2. Send your image
POST the file to
/v1/removeas multipart form data, in a field namedimage.3. Save the result
A successful response body is the PNG itself, not JSON. Write the bytes straight to a file. Your remaining balance comes back in the
X-Credits-Remainingheader.
Prefer to try it without writing code? Use the Playground.
curl -X POST "https://api.nobg.space/v1/remove" \
-H "X-API-Key: $NOBG_API_KEY" \
-F "[email protected]" \
--output result.pngResponse
HTTP/2 200
content-type: image/png
x-credits-remaining: 749
<binary PNG, same dimensions as your upload>Authentication
Send your key in the X-API-Key header on every request. Authorization: Bearer works too.
Keep your key on your server. Anyone holding it can spend your credits, and browsers on other websites can't call the API directly, so send requests through your own backend.
A missing key returns missing_api_key, and a wrong or revoked key returns invalid_api_key. If you set an expiry date on a key, it returns key_expired after that date.
Headers
# Recommended
X-API-Key: YOUR_KEY
# Also accepted
Authorization: Bearer YOUR_KEYRemove a background
POST /v1/remove
Returns a transparent PNG. Costs 1 credit, and only when it succeeds.
Request body
- imagefile, required
- The image, sent as
multipart/form-data. The field namesimage_fileandfilealso work.
You can also skip the form and send the image bytes as the request body.
Request headers
- X-API-Keyrequired
- Your API key.
- X-File-Nameoptional
- A name to show for this request in your activity log, up to 256 characters.
Response headers
- Content-Typealways
image/png- X-Credits-Remainingalways
- Your balance after this request.
Timing
Most images take 3 to 6 seconds, and the largest take about 12. A request can occasionally fall back to a slower path, so set your client timeout to at least 90 seconds.
cURL
curl -X POST "https://api.nobg.space/v1/remove" \
-H "X-API-Key: $NOBG_API_KEY" \
-F "[email protected]" \
--output result.pngRaw body
curl -X POST "https://api.nobg.space/v1/remove" \
-H "X-API-Key: $NOBG_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary "@photo.jpg" \
--output result.pngCheck your balance
GET /v1/account
Returns your balance and auto top-up settings. It's free, though it counts toward your rate limit. Use it before a large batch to check you have enough credits.
Response fields
- credits.remainingnumber
- Images you can process right now.
- credits.usednumber
- Credits used on this account so far.
- credits.totalnumber
- Credits added to this account so far.
- auto_topup.enabledboolean
- Whether automatic top-ups are on.
- auto_topup.threshold_creditsnumber
- The balance that triggers a top-up.
- auto_topup.amount_usdnumber
- The amount charged for each top-up.
cURL
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
}
}Health check
GET /health
Returns ok when the API is up. It needs no key and costs nothing.
cURL
curl "https://api.nobg.space/health"
okErrors
Anything other than a 200 returns JSON with an error code. Switch on that code, not the message. You're never charged for a request that returned no image, because failures are refunded automatically.
Retry only on 429, 500, 502, 504, with a short wait between attempts. Any other error needs a change to the request.
| Status | Code | What to do |
|---|---|---|
| 401 | missing_api_key | No key sent — set the X-API-Key header. |
| 401 | invalid_api_key | Key does not exist or was revoked. Make a new one. |
| 401 | key_expired | Key is past its expiry date. Make a new one. |
| 402 | insufficient_credits | Out of credits. Top up under Billing. |
| 429 | rate_limited | Over 60 requests/minute. Wait the Retry-After seconds, then retry. |
| 400 | no_image_field | No image found. Send the file in a field named "image". |
| 400 | empty_body | Request body was empty. |
| 413 | image_too_large | Over 20 MB or ~30 megapixels. Downscale it. |
| 415 | invalid_image | File is not a supported image — credit refunded. |
| 504 | model_timeout | Model took too long. Retry — credit refunded. |
| 502 | processing_failed | Model failed. Retry — credit refunded. |
| 500 | internal_error | Server error. Retry — credit refunded. |
Error response
HTTP/2 429
retry-after: 60
x-ratelimit-limit: 60
{ "error": "rate_limited" }Rate limits
Each key can make 60 requests a minute. Each IP address can make 300 a minute, so one server can run several keys.
Going over returns 429 rate_limited with a Retry-After header, in seconds, and X-RateLimit-Limit. Wait that long before trying again.
Need more? Contact us with your expected volume.
Retry with backoff (Node)
async function removeBackground(file, attempt = 0) {
const form = new FormData()
form.append('image', file)
const res = await fetch('https://api.nobg.space/v1/remove', {
method: 'POST',
headers: { 'X-API-Key': process.env.NOBG_API_KEY },
body: form,
signal: AbortSignal.timeout(90_000),
})
if (res.ok) return Buffer.from(await res.arrayBuffer())
const retryable = [429, 500, 502, 504].includes(res.status)
if (!retryable || attempt >= 3) {
const { error } = await res.json()
throw new Error(error)
}
const seconds = Number(res.headers.get('retry-after')) || 2 ** attempt
await new Promise(resolve => setTimeout(resolve, seconds * 1000))
return removeBackground(file, attempt + 1)
}Image requirements
- Input formats
- JPG, PNG, WebP, GIF, BMP, TIFF
- Max file size
- 20 MB
- Max resolution
- About 30 megapixels
- Output
- Transparent PNG at your original dimensions
BMP files use a slower path, so they can take longer than other formats.
Credits and billing
One successful image costs one credit. A plan's monthly images are used first, then any credits you bought.
- Monthly images reset each billing month and don't roll over.
- Credits you buy never expire.
- Without a plan, $10 buys 500 credits.
- Auto top-up can buy more credits when your balance runs low.
| Plan | Price | Monthly images | Extra credits |
|---|---|---|---|
| Starter | $9 a month | 2,000 | 1,000 for $10 |
| Growth | $29 a month | 10,000 | 1,500 for $10 |
| Scale | $79 a month | 40,000 | 2,500 for $10 |
Processing in batches
- Check your balance first with
GET /v1/account. - Run 2 to 4 requests at a time, not the whole batch at once.
- Check the file type and size before uploading to avoid wasted requests.
- Retry with a growing wait, as in the rate limit example.
For a one-off folder of images, the bulk tool does this for you, with no code.
Moving from remove.bg
If you upload files directly, change the URL and the key. The image_file field and the X-Api-Key header work as they are.
NoBG takes file uploads only and always returns a transparent PNG, so image_url, bg_color and other remove.bg options have no effect here.
cURL
# Before
curl -X POST "https://api.remove.bg/v1.0/removebg" \
-H "X-Api-Key: $REMOVEBG_KEY" \
-F "[email protected]" \
--output result.png
# After
curl -X POST "https://api.nobg.space/v1/remove" \
-H "X-Api-Key: $NOBG_API_KEY" \
-F "[email protected]" \
--output result.png