Face SwapAbout Face Swap Plus
Face Swap Plus is the tier that decides for you. It reconciles skin tone between the two photos by itself, judges per pair whether moving the face alone or the whole head reads more naturally, and is the only Face Swap endpoint that lets you choose the output file format. There is an optional instruction field, but our own testing found no visible effect from it — integrate as though it were not there.
Call it with the model name popnow/face-swap-v1-plus/edit on POST /jobs/createTask, from 24 credits per image ($0.24). New accounts get 30 free credits to try it in the Playground first.
Introduction
It moves a face from one image onto the person in another and reconciles skin tone between the two as part of the transfer. How much it moves is decided for you: the engine blends either the face alone or the whole head, whichever reads more naturally for that pair, so the hairline is not always left untouched. The target's pose, wardrobe, lighting and background stay as they were.
Face Swap Plus is the steerable tier of the Face Swap line. On top of the two images it takes a short written instruction, an output file format and a seed, and it is posted to popnow/face-swap-v1-plus/edit.
Key features
Skin tone is reconciled for you
The place a face transfer most often gives itself away is the boundary: a reference shot under warm light dropped into a cool-lit target leaves a ring around the jaw and a neck that no longer belongs to the head. This engine reconciles tone between the two photos as part of the transfer, so a pair that is close but not identical usually lands without a manual colour pass afterwards. It does not make lighting direction irrelevant — a face lit from the other side still reads as wrong — but it takes the most common mismatch off your plate.
The blend depth is decided per pair
This is a smart head swap: for each pair the engine judges whether blending the face alone or the whole head reads more naturally, and there is no setting to force one or the other. That is the practical difference from the rest of the line, where the hairline always stays with the target. It is also why a result can come back with a slightly different hairline than you expected — the engine decided the fuller blend was the more believable of the two options.
Request parameters
| Parameter | Required | Description |
|---|---|---|
image_url | Yes | The picture to start from. |
output_format | No | File type of the result. png · jpeg · webp · Default: jpeg |
output_quality | No | Requested image quality for the result, from 10 to 100. ≥ 10 · ≤ 100 · Default: 95 |
prompt | No | Optional short note guiding one subtle attribute of the result, such as an accessory, an expression or a different hairstyle. |
reference_image_url | Yes | Reference face image. The facial identity from this image is transferred onto the target. |
seed | No | Reuse the same number to get a repeatable result. ≥ 0 · ≤ 2147483647 |
Pricing
Prices are in credits, the same credits you use on the website (1 credit = $0.01). The hold is taken when the task is accepted and settled to the actual charge when it finishes; failed tasks are refunded.
| Option | Credits per image | ≈ USD |
|---|---|---|
| Standard | 24 | $0.24 |
For an exact number before you run, send the same body to POST /jobs/quote.
Use cases
Bulk avatar and profile pipelines
A list of target-reference pairs goes through the endpoint programmatically, one call per pair. Pin a seed per pair when a retry has to stay comparable with the first run, and pick WebP when the results are headed straight for the web.
Consumer features behind an upload form
The interaction is one photo from the user and one frame you supply. There is nothing for the user to configure and no prompt for them to write, so the whole feature is a single form field and a background job.
Catalogue and template work
One reference face across a set of prepared frames gives a coherent series without regenerating any of them. The output format setting keeps the files in whatever shape your pipeline already expects; any accessory a template calls for has to be in the frame before the swap.
Prompt guide & pro tips
The instruction field does nothing here
prompt is accepted by the model and capped at 200 characters, but we have not been able to make it change anything.
| What we sent | What came back |
|---|---|
add mirrored aviator sunglasses | No sunglasses; identical to sending nothing |
wearing black sunglasses | No sunglasses; identical to sending nothing |
restyle the hair into a sleek straight bob | Hair unchanged |
soften the expression into a faint half smile | Expression unchanged |
a wide open-mouthed laugh | Expression unchanged |
Five real calls on 2026-09-20, each compared against the same request with the field left empty. Nothing errors and nothing warns, so the response gives you no way to tell the value was ignored. Build without it — if you need an accessory or a different expression, put it into the target frame before the swap.
What the engine decides for you
Two runs through this endpoint came back with opposite decisions, which is the clearest way to see it:
| Target | What travelled |
|---|---|
| A tight black ponytail | The whole head — the reference's red hair arrived with the features |
| Wet slicked-back hair | The face alone — the target's hair stayed exactly as shot |
If you needed an accessory or a different expression
The instruction field cannot get you there, so the change has to exist before the swap runs:
| What you wanted | Where to do it instead |
|---|---|
| Sunglasses, a hat, jewellery | Put it on the person in the target frame before you call this |
| A different expression or hairstyle | Shoot or generate the target frame that way; the swap keeps both |
Choosing the output format and the seed
Pin a seed only when you intend to compare runs; it gives two runs over the same pair the same draw so a single changed variable is the only thing moving, and it is a comparison tool rather than a promise of a byte-identical image. In production a fresh draw each time is usually what you want.
When the result is not what you wanted
| What you see | What to change first |
|---|---|
| A seam at the jaw despite tone matching | Use a reference lit from the same direction — tone is matched, direction is not |
| The hairline changed and you wanted it kept | Expected here; use Face Swap or Face Swap Pro |
| The instruction had no visible effect | Expected — the field has no effect here; change the target frame instead |
| The wrong person changed | Crop the target down to one subject |
| Features look soft or approximate | Use a reference where the face is larger and sharper |
Picking the right endpoint for the job
| What you need | Endpoint |
|---|---|
| Tone matching and a choice of file format | This endpoint |
| Landmark accuracy and the original texture, no knobs | Face Swap Pro |
| The plain swap with a seed, hair always left alone | Face Swap |
| The whole head, hair included, every time | Head Swap |
| One face across a moving clip | Video Face Swap |
Running it as a batch
Two required fields and three defaults make a batch a loop over pairs.
API quick start
Call the Face Swap Plus 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- and use the same credits as the website.
- Send the request. POST /jobs/createTask with model popnow/face-swap-v1-plus/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-swap-v1-plus/edit",
"input": {
"image_url": "https://media.popnow.ai/influencer/examples/marco.webp",
"reference_image_url": "https://media.popnow.ai/influencer/examples/ava.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.
Face Swap Plus API questions
How much does the Face Swap Plus API cost?
Face Swap Plus costs 24 credits ($0.24) per image. Credits are the same as on the website (1 credit = $0.01), new accounts get 30 free credits, and failed tasks are refunded.
What is the model name for Face Swap Plus in the API?
Put popnow/face-swap-v1-plus/edit for Face Swap in the model field of POST /jobs/createTask.
Which image should go in image_url?
The one being changed. reference_image_url supplies the face. The two are not interchangeable, and swapping them is still a valid request with a completely different outcome, so no error will catch the mistake.
There is a `prompt` field. Does it do anything?
In our own testing, no. On 2026-09-20 we ran five real calls through this endpoint — two asking for sunglasses, one for a different hairstyle, two for a changed expression — and every result was indistinguishable from the same request with the field left empty. The model accepts the value and returns no error and no warning, so a call that relies on it looks like it worked. Treat the field as inert and leave it out.
Does holding the seed guarantee an identical result?
No. It gives two runs over the same pair the same random draw, which makes them fair to compare when you change one thing. It is a comparison tool, not a promise of a byte-identical image.
What do the two images need to look like?
One clearly visible face each, reasonably frontal, in focus and large enough in frame that the features are legible, as JPEG, PNG or WebP. Crop a group shot down to a single subject before sending. Skin tone is reconciled for you, but lighting direction is not, so a reference lit from roughly the same side as the target still gives the cleanest jawline.
What are the limits of the Face Swap Plus API?
Prompt length (characters): 200. Requests outside these limits are rejected before anything is charged.
Can I try Face Swap Plus without writing code?
Yes. The Playground runs Face Swap Plus on your PopNow credits, needs no API key, and shows the matching code for every run.
All Face Swap Plus models
Face Swap Pro keeps the original skin texture with no smoothing; Face Swap moves only the facial features.
- Face Swap Pro APIPrecise face swap that keeps natural skin textureFrom 24 credits per image
- Face Swap Plus APIFace swap with automatic skin-tone matchingFrom 24 credits per image
- Face Swap APISwap just the face, keep hair, pose and backgroundFrom 2 credits per image
- Video Face Swap APICarry one face through every frame of a clipFrom 3.9 credits per second