API reference/POST /remove

Remove background

Upload an image and get back a transparent PNG or WebP. Edges are cleaned via closed-form foreground matting: no halos, no fringing.

POSThttps://useknockout--api.modal.run/remove

Parameters

Send as multipart/form-data unless noted otherwise.

filerequiredfile–Image to process. JPG, PNG, WebP, HEIC. Up to 10 MB and 4096×4096.
formatstringpngOutput format: png (with alpha) or webp.
qualityint 1-10092JPEG/WebP quality. Ignored for PNG.
mattingstringclosed-formEdge cleanup algorithm. Options: closed-form, none.
edgestringsoftEdge style. soft (default) preserves partial transparency; hard commits ambiguous edge pixels for a crisper cut. Use hard for product and object shots; keep soft for hair and fur, where hardening makes wispy strands crunchy.
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.
enginestring(default engine)Set to product-v1 to run the alternate cutout engine built for flat product photography: packaging film, paper, sheet goods and lightbox flat-lays, where the default engine can leave a faint light edge where the background met the product. Opt-in per request, so calls that omit it are unchanged. It runs a second refinement pass at full resolution, which costs roughly 25 seconds per image instead of a few, and it needs a paid plan. Choose it for flat, opaque products; leave it off for plants, hair, and translucent or pale organic subjects, where it performs worse than the default.
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/remove" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@cat.jpg" \
  -F "format=png" \
  -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

  • Send all params as multipart form fields (-F), not query-string params, same as /replace-bg and /studio-shot. Affects format, quality, max_dim, width, height, despill, watermark, watermark_opacity, and preset.
  • Transparent output, so format is png or webp only; jpg can't carry alpha. Use /studio-shot or /replace-bg for a jpg.
  • The model runs on a Modal L4 GPU that scales to zero when idle, which is the trade-off for $0 idle cost. The first request after idle can take a minute or more, depending on the endpoint and image size: the container wakes and loads weights, then your image is processed. Once warm, calls are a few seconds. Build a generous timeout and a retry into your first call rather than assuming the API is down.
  • Images are processed in-memory and discarded after the response is returned.
  • EXIF orientation is auto-corrected on every endpoint. Phone photos come back upright, not sideways.
  • For flat e-commerce product shots, combine detect=high_recall with decontaminate=true. They fix opposite defects: high_recall recovers product the mask missed, decontaminate removes background the mask kept.
  • For batch workflows, fan out with Promise.all in Node or asyncio.gather in Python, or use /remove-batch.
← QuickstartPOST /remove-url →