API reference/POST /psd

Layered PSD export

Return a layered Photoshop .psd, the subject on its own transparent layer above the original background layer, instead of a flattened cutout. Paid add-on; included free with Knockout Plus.

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

Parameters

Send as multipart/form-data unless noted otherwise.

filerequiredfile–Image to process. JPG, PNG, WebP, HEIC. Up to 10 MB and 4096×4096.
backgroundstring–Optional hex color or image URL added as a third background-fill layer beneath the subject.
despillbooleanfalseRemove colored edge spill on the subject layer. Knockout Plus only.
presetstring–Apply a saved preset by id (see /presets). Explicit params override stored values.

Request

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

Response

HTTP/1.1 200 OK
content-type: image/vnd.adobe.photoshop
content-disposition: attachment; filename="out.psd"
x-knockout-model: BiRefNet

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.
402payment_required–PSD export is a paid add-on. Add a card, or upgrade to Knockout Plus for it free.
Every error response also includes a request_id in the JSON body. Quote it when reporting issues.

Notes

  • $0.10 per image on Pay-as-you-go; included free on Knockout Plus (tier=pro).
  • Layers: a transparent subject cutout above the original background pixels. Editable in Photoshop, Photopea, or GIMP.
  • Scope a restricted token to /psd to allow PSD export without granting full access.
← POST /comparePOST /presets →