Face Swap Pro API

Introduction

It moves the facial features from one image onto the person in another. Only the features travel: the target's hairstyle, hairline, head silhouette, pose, wardrobe, lighting and background all stay as they were, which is what makes the result sit inside the original photograph rather than on top of it.

Face Swap Pro is the precision tier of the Face Swap line. The engine locates the facial keypoints in both photos by itself and maps one set onto the other, and nothing runs over the result afterwards. The whole request is two image URLs — image_url for the photograph being changed, reference_image_url for the face — posted to popnow/face-swap-pro-v1/edit.

Key features

The engine maps the face by its keypoints

Pro is built for high-precision work. Rather than pasting a region across, it locates the facial keypoints in both photos and maps one set onto the other, which is what keeps eyes, nose and mouth landing where the target's own geometry puts them. On this endpoint the detection is automatic: you send two images and nothing else. No enhancement pass runs afterwards either, so pores, fine lines and grain survive and the face matches the sharpness of everything around it. That is also why a result can look less flattering than a filtered swap — accuracy and flattery are not the same goal.

Two image URLs and nothing else to get wrong

It is the only face swap endpoint in this catalogue that takes nothing but the two images: no prompt to phrase, no region to paint, no strength to tune and no seed to pin. That removes the whole class of failures which come from an ambiguous instruction, and it makes the endpoint trivially batchable, because a list of pairs goes through without a per-item decision. Unknown keys are rejected rather than ignored, so a misspelled field name fails at submit time instead of quietly falling back to a default. The one thing that does matter is which URL goes where: the two fields are not symmetrical, and swapping them is still a perfectly valid request with a completely different outcome.

The target photograph survives the swap

There is no aspect ratio and no resolution setting here, because the frame is not being regenerated — one region of an existing photograph is replaced. That is what makes the endpoint usable on a plate you have already signed off: nothing outside the face is put back in play.

Request parameters

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.

For an exact number before you run, send the same body to POST /jobs/quote.

Use cases

Editorial and campaign frames that will be printed

A smoothed face falls apart at print size: the skin reads as plastic next to a sharp garment and a sharp background. Keeping the original texture means the frame holds together when someone looks at it closely instead of at thumbnail size.

Recasting a plate you have already approved

The lighting, pose and set already work, and regenerating the whole frame would put all of that back in play. Move one face into the plate instead and everything you signed off on stays exactly where it was.

Consistent characters across a series

Generate the scenes with any model, then bring one face across all of them so the set reads as the same person. Hair and wardrobe stay with each target frame, so the variation you generated survives the pass.

Prompt guide & pro tips

There is no prompt, so the tuning happens before the call

Most image endpoints give you a sentence to rewrite when a result disappoints. This one does not: the request is two URLs, so the only variables are which photographs you send. That makes iteration easy to reason about — change one image, hold the other, and you know exactly what moved — but it also means a bad pair cannot be rescued by a better instruction.

Choosing the target and the reference

image_url is the photograph being changed; reference_image_url supplies the face. Both should show one clearly visible face, 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 first. The single most useful thing you control is lighting direction: pick a reference lit from roughly the same side as the target, because the target's light is not changed by the swap and a mismatch reads as a seam along the jaw.

When the result is not what you wanted

Picking the right endpoint for the job

Running it as a batch

Because nothing is decided per item, a batch is a loop over pairs.

API quick start

Call the Face Swap Pro API in three steps

1. 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.
2. Send the request. POST /jobs/createTask with model popnow/face-swap-pro-v1/edit and an input object that follows the parameter table. The response returns a task ID straight away.
3. 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-pro-v1/edit",
  "input": {
    "image_url": "https://media.popnow.ai/influencer/examples/marco.webp",
    "reference_image_url": "https://media.popnow.ai/influencer/examples/ava.webp"
  }
}'

# 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 Pro API questions

All Face Swap Pro models

Face Swap keeps the target's hair and accepts a seed; Face Swap Plus matches skin tone for you.

• 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

Other image APIs

• Celebrity Look-Alike APIFind your celebrity look-alike from one portraitFrom 8 credits per image
• Head Swap APIReplace the whole head, hairstyle includedFrom 2 credits per image

More about Face Swap Pro

Try it

Face Swap Pro AI Face Swap onlineCreate images with Face Swap Pro in PopNow

Docs

Face Swap Pro model ID and input schema in the API docsPopNow API quickstart: your first request in five minutesImage generation guide for the PopNow APIWebhooks: get Face Swap Pro results without polling