API reference/POST /replace-bg-ai

AI background from a promptComing soon

Describe a scene and get your product placed in it. The generative model never sees your product: we cut the subject out, generate only the backdrop from your prompt, and composite. Product pixels stay untouched and output stays at your source resolution.

POSThttps://useknockout--api.modal.run/replace-bg-ai

Models

Pass one of these ids as model, or leave it on auto. The top models accept reference images, so the scene can match a look you already have. Reference image input arrives with the full launch.

gpt-image-2.5-sunbursttopGPT Image 2.5 SunburstYes
gpt-image-2.5-flaretopGPT Image 2.5 FlareYes
mai-image-2.6topMAI Image 2.6Yes
mai-image-2.6-flashtopMAI Image 2.6 FlashYes
mai-image-2.5-proMAI Image 2.5 ProNo
mai-image-2.5MAI Image 2.5No
mai-image-2.5-flashMAI Image 2.5 FlashNo
mai-image-2eMAI Image 2eNo
gpt-image-2GPT Image 2No
flux2-proFLUX.2 ProNo
flux2-flexFLUX.2 FlexNo
flux1-kontext-proFLUX.1 Kontext ProNo
nano-bananaNano BananaNo

Parameters

Send as multipart/form-data unless noted otherwise.

filerequiredfile–Image to process. JPG, PNG, WebP, HEIC. Up to 10 MB and 4096×4096.
promptrequiredstring–Scene description, up to 500 characters. Example: "white marble countertop, soft window light from the left".
modelstringautoWhich image model generates the backdrop: auto, or any id from the Models table above. auto picks for you.
formatstringjpgOutput format: png, webp, or jpg. Output is opaque.
detectstringstandardSubject detection mode: standard (default) or high_recall. high_recall runs a second model pass on a contrast-boosted copy and unions the two masks, recovering product regions the single pass misses on low-contrast shots (a pale product on a pale surface). It only ever adds to the mask; it never removes included background (that's decontaminate). Runs double inference, so latency roughly doubles and it requires a paid plan: free-tier requests get a 402.
decontaminatebooleanfalseRe-classify pixels near the mask edge using per-image color models of subject vs background, removing background the model kept: base-paper strips under products, lightbox rig fragments at the boundary. Trade-off: it helps least on a white product on a white background (no color evidence to work with), and it can trim the dark underside edge of stacked or thick products, which is partly real product. Available on every tier.
qualityint 1-10092 jpg, 80 webpJPEG/WebP quality. Ignored for PNG.
max_dimint–Clamp the longest output edge to N pixels (downscale only). Aspect preserved.
widthint–Resize output to an exact width in pixels. Use with height, or alone to scale by aspect.
heightint–Resize output to an exact height in pixels.
despillint 0-100100Strength of the edge color-spill cleanup (green/blue fringing bled onto the subject from the old background). 0 turns it off, 100 is full. Full cleanup runs by default on every plan; sending this field to change it requires Knockout Plus.
watermarkstring–URL of a watermark image (PNG with alpha) to overlay on the output. Knockout Plus only.
watermark_opacityfloat 0-10.5Watermark opacity. Only applies when watermark is set. Knockout Plus only.

Request

curl -X POST "https://useknockout--api.modal.run/replace-bg-ai" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@cat.jpg" \
  -F "prompt=white marble countertop, soft window light from the left" -F "format=jpg" \
  -o out.png

Response

HTTP/1.1 200 OK
content-type: image/jpeg
content-length: 254312
x-knockout-latency: 184
x-knockout-model: BiRefNet
x-knockout-engine: standard
x-ratelimit-limit: 60
x-ratelimit-remaining: 59

Errors

401unauthorized–Missing or invalid token.
402payment_required–Free tier exhausted. Add a card to continue.
413payload_too_large–Image exceeds 10 MB or 4096×4096.
422no_subject_detected–Foreground could not be isolated from background.
429rate_limit_exceeded–Slow down. Retry-After header tells you when.
500internal_error–Something broke on our side. Include request_id when reporting.
403forbidden–Your account is not in the limited preview, or the requested model is not available to it.
Every error response also includes a request_id in the JSON body. Quote it when reporting issues.

Notes

  • Coming soon. This endpoint is in a limited preview for allowlisted accounts; other keys get a 403. Email hi@useknockout.com to request access.
  • Not billed during the preview. A global daily cap applies while it is in preview.
  • Backdrops are cached by prompt, model, and aspect ratio, so running one prompt across a whole catalog generates the scene once.
  • detect and decontaminate control the cutout, not the generated scene.
← POST /replace-bgPOST /remove-batch →