API reference/POST /replace-bg

Replace background

Cut out the subject and composite it onto a new background: solid color, hex, or another image. One call instead of two.

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

Parameters

Send as multipart/form-data unless noted otherwise.

filerequiredfile–Image to process. JPG, PNG, WebP, HEIC. Up to 10 MB and 4096×4096.
bg_filefile–Background image uploaded in the same multipart body as file. Composited beneath the subject, resized to the subject's frame. Highest precedence.
bg_urlstring–URL of a background image, fetched by the API. Same compositing as bg_file. Used when no bg_file is sent.
bg_colorstring#FFFFFFHex color (e.g. #FF5733) or named color (e.g. red, transparent). Used when neither bg_file nor bg_url is sent.
formatstringpngOutput format: png, webp, or jpg. Output is opaque, so jpg is valid here.
qualityint 1-10092JPEG/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.
despillbooleanfalseRemove colored edge spill (green/blue fringing) bled onto the subject from the old background. Knockout Plus only.
watermarkstring–URL of a watermark image (PNG with alpha) to overlay on the output. Knockout Plus only.
watermark_opacityfloat 0-11.0Watermark opacity. Only applies when watermark is set. Knockout Plus only.
presetstring–Apply a saved preset by id (see /presets). Explicit params override the preset's stored values.

Request

curl -X POST "https://useknockout--api.modal.run/replace-bg" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@cat.jpg" \
  -F "bg_color=#0B0D0E" \
  -o out.png

Response

HTTP/1.1 200 OK
content-type: image/png
content-length: 254312
x-knockout-latency: 184
x-knockout-model: BiRefNet
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.
Every error response also includes a request_id in the JSON body. Quote it when reporting issues.

Notes

  • Backgrounds resolve by precedence, not exclusion: bg_file wins, then bg_url, then bg_color, which defaults to white. A call with none of the three returns a white background, not an error.
  • With an image background, response format defaults to JPEG since alpha is no longer needed.
  • bg_file is the practical choice from a browser, where the user has a local file rather than a hosted URL. bg_url suits server-side callers that already host their backgrounds.
← POST /remove-urlPOST /remove-batch →