API reference/POST /face-restore

Face restoration

GFPGAN-based face restoration. Sharpens blurry faces, recovers detail in compressed images. Optional whole-image upscale.

POSThttps://useknockout--api.modal.run/face-restore

Parameters

Send as multipart/form-data unless noted otherwise.

filerequiredfile–Image to process. JPG, PNG, WebP, HEIC. Up to 10 MB and 4096×4096.
only_center_facebooleanfalseRestore only the most prominent face. Faster on group photos.
bg_enhancebooleanfalseAlso upscale the background 2x. Off by default because it can bleed skin tones into warm backgrounds; recommended only for cool or neutral backgrounds.
formatstringpngOutput format: png, webp, or jpg.

Request

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

Response

HTTP/1.1 200 OK
content-type: image/png
x-knockout-latency: 358
x-knockout-model: GFPGAN-1.4

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.
422no_face_detected–No face found in the image. Try /upscale instead.
Every error response also includes a request_id in the JSON body. Quote it when reporting issues.

Notes

  • Restores every detected face, or only the most prominent one with only_center_face=true. Backgrounds are untouched unless bg_enhance=true.
  • For a one-call portrait pipeline, /headshot bundles cutout + restore + crop.
← POST /upscalePOST /colorize →