API reference/POST /studio-shot

E-commerce studio shot

One-call e-commerce preset: cutout, padding, soft drop shadow, neutral background. Tuned for catalog images and Shopify-style product tiles.

POSThttps://useknockout--api.modal.run/studio-shot

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#FFFFFFBackground hex color.
paddingint48Pixels of padding between the subject and the canvas edge.
shadowbooleantrueSoft drop shadow under the product. ON BY DEFAULT: the default output includes a soft black shadow (offset 8,12, 35% opacity). Pass shadow=false explicitly if you want a plain cutout on the background color.
transparentbooleanfalseKeep a transparent background. Ignores bg_color and shadow (a shadow needs an opaque bg). Output is forced to PNG if format=jpg, since jpg can't carry alpha.
aspectstring1:1Output aspect ratio.
enhancebooleanfalseOff by default. Set true for a subtle brightness + saturation lift (ecommerce-ready). Leave off for true-to-life color.
enhance_strengthfloat 0-0.50.15Lift amount. Only applies when enhance=true.
formatstringjpgOutput format: png, webp, or jpg. With transparent=true a jpg request comes back as png, since jpg cannot carry transparency.
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.
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.
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.
presetstring–Apply one of your saved presets by name (see /presets). Explicit params override the preset's stored values. Knockout Plus only.

Request

curl -X POST "https://useknockout--api.modal.run/studio-shot" \
  -H "Authorization: Bearer $KNOCKOUT_TOKEN" \
  -F "file=@product.jpg" \
  -F "transparent=true" \
  --output studio.png

Response

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

Notes

  • shadow defaults to TRUE. If you run this with default parameters expecting a plain product on white, you will get a drop shadow: pass shadow=false to turn it off.
  • Defaults match Shopify and Amazon catalog requirements: 1:1, white bg, 10% padding.
  • Override aspect to 4:5 for Instagram, 16:9 for desktop catalog headers.
  • When transparent=true, bg_color and shadow are ignored.
  • Output is opaque, so jpg is valid (unless transparent=true, which forces PNG).
  • enhance is off by default. Output is unaltered unless you pass enhance=true. Leave it off to match real-life camera color.
  • Saved presets now honor width and height on /studio-shot (previously ignored). Apply one with preset=<name>; explicit width/height still override the stored values.
← POST /shadowPOST /headshot →