API reference/POST /silhouette

Two-tone silhouette portrait

Subject filled with one solid color, background filled with another. Apple Music / Spotify avatar aesthetic. Reuses BiRefNet's mask path — no extra model load.

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

Parameters

Send as multipart/form-data unless noted otherwise.

filerequiredfile—Image to process. JPG, PNG, WebP, HEIC. Up to 10 MB and 4096×4096.
subject_colorstring#7C3AEDHex color for the subject fill. Default is purple.
bg_colorstring#FFFFFFHex color for the background fill. Default is white.
formatstringpngOutput format — png, webp, or jpg.

Request

curl -X POST "https://useknockout--api.modal.run/silhouette" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@portrait.jpg" \
  -F "subject_color=#1E2960" \
  -F "bg_color=#F0857C" \
  -o silhouette.png

Response

HTTP/1.1 200 OK
content-type: image/png
x-knockout-latency: 210
x-knockout-model: BiRefNet

Errors

400invalid_image—Invalid image, unsupported format, or decode failure.
401unauthorized—Missing or invalid token.
403forbidden—Invalid bearer token.
413payload_too_large—Image exceeds 10 MB or 4096×4096.
429rate_limit_exceeded—Slow down. Retry-After header tells you when.
500silhouette_failed—Silhouette generation failed or produced no output.
Every error response also includes a request_id in the JSON body. Quote it when reporting issues.

Notes

  • Reuses BiRefNet's mask path — same warm latency as /mask (~150–300ms).
  • Use cases: stylized profile pictures, podcast cover art, anonymized portraits, branding placeholders, social media avatar generators.
  • Color inputs are valid hex strings — 3-digit (#FFF) or 6-digit (#FFFFFF) with or without the # prefix.
← POST /smart-cropPOST /inpaint →