API reference

Quickstart

curl -X POST https://api.nukebg.com/v1/cutouts \
  -H "X-Api-Key: $NUKEBG_KEY" \
  -F image_file=@shoe.jpg \
  -o shoe.png

Authentication

Send your key in the X-Api-Key header (or Authorization: Bearer). Create keys on your account page; new accounts start with 50 free credits.

Retrying? Send an Idempotency-Key header. A request that succeeded with that key is never charged twice; a failed one can be retried with the same key.

POST/v1/cutouts

Cut out the subject and optionally place it on a background at a marketplace size. Accepts multipart/form-data or application/json.

Scene ids: plinth marble linen pastel noir garden kitchen concrete signal festive

Responses & headers

By default the image bytes are returned. Send Accept: application/json to get result_b64 with metadata instead.

POST/v1/erase

Remove objects. Send mask_file (PNG, white = remove, any size) and optionally a prompt describing it. Pixels outside the mask come back untouched. quality=fast (25 credits) or enhance (40, paid credits). A prompt alone works for obvious objects; a mask is more reliable.

curl -X POST https://api.nukebg.com/v1/erase   -H "X-Api-Key: $NUKEBG_KEY"   -F image_file=@desk.jpg   -F mask_file=@mask.png   -F quality=fast   -o clean.png

POST/v1/upscale

Real-ESRGAN upscaling. scale=2 (2 credits, source up to 16 MP) or scale=4 (4 paid credits, source up to 4 MP). format png, webp or jpg.

POST/v1/backgrounds

Generate an empty AI scene plate from a short description (25 credits; repeating a prompt is free). Use the returned URL as background=url:… or in the Studio. GET /v1/backgrounds lists the built-in scenes for free.

curl -X POST https://api.nukebg.com/v1/backgrounds \
  -H "X-Api-Key: $NUKEBG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "terrazzo counter, soft morning light"}'

# → { "id": "…", "url": "/api/v1/backgrounds/…", "credits_charged": 25 }

Jobs, video & batches

Long work runs as a job. Credits are held when you create it and charged only on success (video by the second actually processed). Upload big files first with POST /v1/uploads: you get a file_id and a signed upload_url to PUT the bytes to.

# 1. get an upload URL, then PUT the clip to it
curl -s -X POST https://api.nukebg.com/v1/uploads -H "X-Api-Key: $KEY"   -H "Content-Type: application/json" -d '{"content_type":"video/mp4"}'
curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @clip.mp4

# 2. start the job (duration_seconds sets the credit hold, max 60)
curl -s -X POST https://api.nukebg.com/v1/jobs -H "X-Api-Key: $KEY" -H "Content-Type: application/json"   -d '{"tool":"video","input":{"file_id":"file_…"},"params":{"duration_seconds":8,"format":"webm"}}'

# 3. poll until status is "succeeded", then download result.url
curl -s https://api.nukebg.com/v1/jobs/job_… -H "X-Api-Key: $KEY"

Batches take up to 500 items (cutout or upscale). DELETE /v1/jobs/:id cancels a queued job and releases its credits. Results stay downloadable for 7 days.

Webhooks

Pass webhook_url on a job or batch to get job.succeeded / job.failed POSTs with the job as JSON. Verify the X-NukeBG-Signature: t=…,v1=… header: v1 is the hex HMAC-SHA256 of t + "." + body using the webhook_secret from GET /v1/account.

GET/v1/account

Returns credits, a balance split into free and paid credits, your plan and webhook_secret. GET /v1/health reports engine status.

remove.bg compatibility

POST /v1.0/removebg and GET /v1.0/account accept remove.bg parameters (size, bg_color, bg_image_url, crop, crop_margin, format=zip, channels) and return the same headers and error shape. Change the base URL and the key.

Errors

Errors are JSON: { "error": { "code", "message", "request_id" } }. No credits are charged for any error.