API reference/POST /mask

Alpha matte only

Returns the grayscale alpha matte: black background, white subject, soft gradient on edges. Drop into your own compositing pipeline (Photoshop, OpenCV, ffmpeg).

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

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 or webp.
enginestringstandardWhich cutout engine runs: standard (default), auto, or product-v1. Use auto for product photography: it runs the standard engine, then switches to product-v1 for flat products (packaging film, paper, sheet goods, lightbox flat-lays) and rescues dark subjects on flat backdrops where the default cut drops them. auto only costs extra time when it escalates, typically 45 to 70 seconds instead of 15 to 30. product-v1 forces the product engine on every image; avoid it for plants, hair, and translucent or pale organic subjects. auto and product-v1 need a paid plan on signed-in accounts (free accounts get a 402). The X-Knockout-Engine response header says which engine actually ran.

Request

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

Response

HTTP/1.1 200 OK
content-type: image/png
x-knockout-latency: 178

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

  • Use this when you want the matte but plan to do your own compositing, for example applying a custom feather or threshold.
  • Output is single-channel grayscale. Some image libraries convert to RGB on load, so explicitly read as L mode.
← POST /remove-batch-urlPOST /sticker →