API reference/POST /headshot

Portrait headshot cleanup

Portrait-tuned cutout + light face restoration + neutral background. For profile photos, team pages, and avatar uploads.

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

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#FFFFFFHex color of the solid background. Ignored when bg_blur is on.
bg_blurbool | int 2-100falseInstead of a solid color, put the subject on a blurred copy of the original photo. true uses blur_radius; a number from 2 to 100 sets the intensity directly and overrides blur_radius (2 is the faintest).
blur_radiusint20Blur radius used when bg_blur=true.
aspectstring4:5Canvas aspect ratio, as W:H.
paddingint64Pixels of padding around the subject.
head_top_ratiofloat0.18Empty space above the head, as a fraction of canvas height.
formatstringjpgOutput format: png, webp, or jpg.

Request

curl -X POST "https://useknockout--api.modal.run/headshot" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@cat.jpg" \
  -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-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

  • Combines /remove + /face-restore + /smart-crop in a single GPU pass, faster than chaining them.
  • Falls back to /studio-shot if no face is detected (request still succeeds).
← POST /studio-shotPOST /compare →