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_colorstring—Hex color (e.g. #FF5733) or named color (e.g. red, transparent).
bg_urlstring—URL of a background image. Composited beneath the subject. Mutually exclusive with bg_color.
fitstringcoverHow the bg image fits behind subject. cover, contain, stretch.
formatstringpngOutput format — png (with alpha) or webp.

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

  • Provide exactly one of bg_color or bg_url.
  • If bg_url is provided, response format defaults to JPEG since alpha is no longer needed.
← POST /remove-urlPOST /remove-batch →