Introduction
What this endpoint does
It takes one photo and returns a copy with up to three faces restored and sharpened, largest first. Everything outside the faces is left as it was, and the resolution does not change. There is no prompt.
Inputs that matter
image_url is the photo: a JPEG, PNG or WebP upload, or a public URL. `Choose a real, clearly visible face that occupies enough of the source image for Face Enhancer to work on; facial detail restoration in a still photo with Face Enhancer benefits more from that detail than from a distant or hidden face. Choose a real, clearly visible face that occupies enough of the source image for Face Enhancer to work on; facial detail restoration in a still photo with Face Enhancer benefits more from that detail than from a distant or hidden face.
What you get back
One image per request at the same resolution you sent, served from platform storage once the task finishes. For more pixels, use /models/image-upscaler-v1.
| Field | Value |
|---|---|
| Input | Image |
| Output | Image |
| Endpoint | Image edit |
| Faces | Up to three, largest first |
| Everything else | Left as it was |
| Controls | No prompt — just the file format |
Request parameters
| Parameter | Required | Description |
|---|---|---|
image_url | Yes | The photo to restore: a JPEG, PNG or WebP upload, or a public link to the file. at least 1 characters |
output_format | No | jpeg (default), png or webp. png avoids another round of lossy compression but the file is larger. |
Pricing
$0.012 / image
Billed at a flat price per image. The output format does not change the price, and failed requests are not charged.
Use cases
Photos that were resized and recompressed
Pictures that went through a chat app, a social feed or a few rounds of saving lose detail in the face first. Run them through once to bring back eyes, brows, beard and skin texture.
Profile and team photos
Clean up a portrait that is a little soft before it goes on a profile, a team page or a speaker bio. The framing, lighting and background stay as shot.
Before a bigger layout
Get the faces clean first, then use Image Upscaler at /models/image-upscaler-v1 if the photo also needs more pixels for a banner or a print.
Prompt guide & pro tips
Check the faces
Choose a real, clearly visible face that occupies enough of the source image for Face Enhancer to work on; facial detail restoration in a still photo with Face Enhancer benefits more from that detail than from a distant or hidden face. Heavily covered, very small or extremely blurred faces, and illustrated or anime faces, improve less.
Send
image_urlimage_urlis the photo, as a JPEG, PNG or WebP upload or a public URL. Addoutput_formatif you want png or webp instead of jpeg.Poll, then compare
The call is asynchronous: create the task, poll until it finishes and download the image from platform storage. Compare it with your original at full size around the eyes and skin.
Introduction
Face Enhancer restores and sharpens the faces in one photo. It finds up to three faces, largest first, and rebuilds the detail that compression, resizing or softness took away: eyes, eyebrows, beard and skin texture. Everything outside the faces is left as it was, and the picture comes back at the same resolution you sent. There is no prompt and nothing to tune beyond the file format.
Request
{
"image_url": "https://example.com/portrait.jpg",
"output_format": "jpeg"
}
image_url is the one required field. output_format defaults to jpeg; set it to png or webp if you prefer.
What changes and what stays
The faces change, the rest of the photo does not. In our test we took a 720×404 JPEG portrait of a man at a bar and degraded it on purpose: halved its size, scaled it back up and compressed it heavily. It came back at 720×404 after about 9 seconds of processing. Eyes, eyebrows, beard and skin texture were clearly sharper, and he was still recognisably the same man. The skin came back a little smoother than a real photo would be, and the bottle shelf behind him kept its original compression blocks, because the background is not touched.
The size does not change either. Face Enhancer restores faces at the resolution you send; if you also need more pixels, use Image Upscaler (/models/image-upscaler-v1).
Faces improve most when they are real, reasonably large and clearly visible. Face Enhancer has less facial information to restore when the source is an illustration or anime, or the face is tiny, covered or severely blurred; this limits facial detail restoration in a still photo with Face Enhancer.
Task flow
The call is asynchronous. Create a Face Enhancer task for facial detail restoration in a still photo with Face Enhancer, poll its ID to completion and download the finished file from SpicyAPI storage. One image comes back per request, billed at a flat price per image, and a failed request is not charged.
Tips
- Start from a photo where the faces are reasonably large and clearly visible. A face just a few dozen pixels wide has little to rebuild.
- Up to three faces are restored, largest first. Any further faces are left as they were.
- Use
pngif the result will be edited or compressed again: it avoids another round of lossy compression, but the file is larger. The format does not change the price. - Compare the result with your original at full size around the eyes and skin. Our test came back slightly smoother than a real photo, so keep the source file.
- Need more pixels as well as cleaner faces? Run Image Upscaler (
/models/image-upscaler-v1) on the photo.
API quick start
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/face-enhancer-v1/edit",
"input": {
"image_url": "https://example.com/reference.png",
"output_format": "jpeg"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
See the API reference for authentication, the complete schema, polling, and error handling.
