Face EnhancerAbout Face Enhancer
The Face Enhancer API is a single image-edit endpoint, popnow/face-enhancer-v1/edit. You send one photo and get back a copy with up to three faces restored, largest first, at the same resolution, with everything outside the faces left alone. There is no prompt. It fits as a post-processing step after an upload or a generation, where the face is the part that looks wrong and the rest of the picture is already right.
Call it with the model name popnow/face-enhancer-v1/edit on POST /jobs/createTask, from $0.012.
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 (/api/image-upscaler-v1).
Faces improve most when they are real, reasonably large and clearly visible.
Task flow
The call is asynchronous.
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. - 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 (/api/image-upscaler-v1) on the photo.
Request parameters
| Parameter | Required | Description |
|---|---|---|
image_url | Yes | The picture to start from. |
output_format | No | File type of the result. jpeg · png · webp · Default: jpeg |
Pricing
Prices are in USD. The API uses a separate USD balance. Website credits cannot be used or transferred to it, and API funds cannot be transferred to website credits. When a task is accepted, we reserve the maximum quoted amount from your API balance. On completion, we charge for actual usage, never more than the hold, and release the remainder. If the task fails, the hold is released.
| Option | USD per image |
|---|---|
| Standard | $0.012 |
Send the same request body to POST /jobs/quote to see the estimated and maximum USD charge before running. A quote does not run the task or charge your balance.
API quick start
Call the Face Enhancer API in three steps
- Create an API key. Sign in to PopNow and create a key in the API console. Keys start with sk-popnow-. API calls use your separate USD balance.
- Send the request. POST /jobs/createTask with model popnow/face-enhancer-v1/edit and an input object that follows the parameter table. The response returns a task ID straight away.
- Get the result. Poll GET /jobs/recordInfo with the task ID, or pass a callBackUrl and we post the result to it. Download the output links when the task succeeds.
# 1. Create the task. Keep the Idempotency-Key if you retry after a network error.
export IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST https://api.popnow.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $POPNOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d '{
"model": "popnow/face-enhancer-v1/edit",
"input": {
"image_url": "https://media.popnow.ai/influencer/examples/marco.webp",
"output_format": "jpeg"
}
}'
# 2. Copy data.taskId from the response, then poll until state is succeeded, failed, canceled or expired.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $POPNOW_API_KEY"Replace the prompt and any links with your own. The API tab has the response, polling and callback reference.
What to build with the Face Enhancer API
- A photo-restoration upload flow that runs every scan through the enhancer and shows a before and after view.
- A headshot or avatar service that restores soft faces in generated portraits before the file is delivered.
- An archive tool for family history projects, paired with the upscaler for users who want more pixels.
Face Enhancer parameter notes
- image_url is the one required field. Send a JPEG, PNG or WebP upload, or a public link. Real, reasonably large and clearly visible faces improve the most.
- output_format accepts jpeg (the default), png or webp. The format does not change the price. png is larger but avoids another lossy pass when the file will be edited again.
- There is no prompt field and no size field. The output keeps the input resolution, so resize on your side if a particular dimension is required.
- Only the three largest faces are enhanced. If the faces beyond that must stay untouched, crop the group photo down to the people who matter first.
How Face Enhancer API pricing adds up
A flat USD price of $0.012 per image, whatever the output format or the size of the photo. There is no per-second component and no minimum size. Failed requests are not charged, and API usage is paid from the separate API balance.
- Face Enhancer: $0.012 per run, $1.20 for 100 runs
Async jobs, webhooks and rate limits
Every Face Enhancer request is asynchronous: createTask returns a taskId straight away, and the result arrives when the job finishes. Poll GET /jobs/recordInfo every few seconds, or pass a public https callBackUrl and verify the X-Webhook-Signature header (HMAC-SHA256 over taskId, timestamp and the body hash) before trusting the payload. Each account gets 1,000 write requests per 10 seconds; a 429 carries Retry-After. Send an Idempotency-Key with createTask so a retried request for popnow/face-enhancer-v1/edit never runs or bills twice.
Common Face Enhancer API errors
| errorCode | What it usually means and how to fix it |
|---|---|
invalid_request | image_url is missing, or output_format is outside jpeg, png and webp. |
invalid_asset | The image could not be fetched, is not a JPEG, PNG or WebP, or the link is not publicly downloadable. Upload local files first and pass the returned reference. |
generation_failed | The enhancer could not process the file, often because it is damaged. Re-export the photo and try again; a failed request is not charged. |
upstream_unavailable | The processing service is temporarily unavailable. Retry after a short delay with the same Idempotency-Key so the request runs at most once. |
Face Enhancer API questions
How much does the Face Enhancer API cost?
Face Enhancer costs $0.012 per image. The API uses a separate USD balance. Website credits cannot be used or transferred to it, and API funds cannot be transferred to website credits. When a task is accepted, we reserve the maximum quoted amount from your API balance. On completion, we charge for actual usage, never more than the hold, and release the remainder. If the task fails, the hold is released.
What is the model name for Face Enhancer in the API?
Put popnow/face-enhancer-v1/edit for Face Enhancer in the model field of POST /jobs/createTask.
Does the output keep my resolution?
Yes. You get back the width and height you sent. For more pixels, pass the restored image to the upscaler as a second call.
How many faces are restored?
Up to three per photo, largest first. Smaller faces beyond that limit are left exactly as they were.
Which output format should I request?
jpeg for web delivery and the smallest file, png when the result will be edited or printed because it avoids another lossy compression, and webp when you want a compact file for the web.
Does the enhancer need a prompt for good results?
No. There is nothing to tune. Feed it the best original you have, because heavily degraded input recovers less detail than a clean scan.
Can I try Face Enhancer without writing code?
Run Face Enhancer in the Playground with your API USD balance, without an API key. Each run appears in your developer history with its matching code.
All Face Enhancer models
Image Upscaler makes the whole picture larger; Face Enhancer fixes faces at the same size.