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.

Get an API key

Quickstart

  1. 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. 2. Send your image

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

  3. 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-Remaining header.

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.png

Response

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_KEY

Remove 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 names image_file and file also 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.png

Raw 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.png

Check 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"

ok

Errors

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.

StatusCodeWhat to do
401missing_api_keyNo key sent — set the X-API-Key header.
401invalid_api_keyKey does not exist or was revoked. Make a new one.
401key_expiredKey is past its expiry date. Make a new one.
402insufficient_creditsOut of credits. Top up under Billing.
429rate_limitedOver 60 requests/minute. Wait the Retry-After seconds, then retry.
400no_image_fieldNo image found. Send the file in a field named "image".
400empty_bodyRequest body was empty.
413image_too_largeOver 20 MB or ~30 megapixels. Downscale it.
415invalid_imageFile is not a supported image — credit refunded.
504model_timeoutModel took too long. Retry — credit refunded.
502processing_failedModel failed. Retry — credit refunded.
500internal_errorServer 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.
PlanPriceMonthly imagesExtra credits
Starter$9 a month2,0001,000 for $10
Growth$29 a month10,0001,500 for $10
Scale$79 a month40,0002,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