Face Swap API

About Face Swap

Face Swap takes a target image and a reference face and transfers only the facial features, keeping the target's head shape, hair, pose and background. Two URLs and an optional seed — there is no prompt field to write.

Call it with the model name popnow/face-swap-v1/edit on POST /jobs/createTask, from 2 credits per image ($0.02). New accounts get 30 free credits to try it in the Playground first.

Introduction

Face Swap 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.

The request is two image URLs and an optional seed: image_url is the photograph being changed and reference_image_url supplies the face. There is no prompt field to write, and one image comes back per request.

Key features

Preserve the plate, change the identity

This is the narrow choice when the target photo already has the right hair, pose, wardrobe, framing and environment. It transfers facial identity while protecting the rest of the approved composition, so a recast does not become a full image-generation pass.

Built for repeatable paired assets

The workflow is deliberately simple: prepare a cleared target and a cleared reference with compatible angle and lighting, then review the jawline, eyes and skin transition. That makes it useful for controlled avatar, catalogue and campaign variants where the plate must remain recognisable.

Choose the swap scope before you start

Use Face Swap when the target's hairstyle and head silhouette are part of the composition. If the incoming identity must bring its hair and whole head shape into the plate, route the job to Head Swap instead; choosing the right scope avoids an avoidable rerun.

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.

Each task is rounded up to whole credits, so one run at the lowest tier costs 2 credits per image ($0.02).

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

Use cases

A new face for a portrait whose hair already works

Use this endpoint when the target photograph's hairstyle, hairline and head silhouette belong to the composition and only the facial features should change. Send the target as image_url and the face as reference_image_url, then compare the eyes and jawline with the source at full size before accepting the result.

Recasting a stock or generated plate

Take a plate whose lighting, pose and set already work and put a different face in it, rather than regenerating the whole frame and losing the composition you had already approved.

Bulk avatar and profile pipelines

With no prompt to write, a list of target-reference pairs can be pushed through the endpoint programmatically. Pin a seed per pair when a retry has to stay comparable with the first run.

Consistent characters across a shoot

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

Prompt guide & pro tips

Confirm you hold the rights to both faces

Before anything technical: the target and the reference both depict people, and you need authorisation for the likeness you are moving and for the image you are moving it into. Keep the release with the job record.

Host both images and send the pair

image_url is the picture being changed; reference_image_url supplies the face. No prompt is involved — a general editor needs one such as: "Face swap: take the face and hairline of the woman in the second image and place it onto the woman in the first image. Keep the first image's pose, outfit, magazine layout, lighting, framing and colour grade completely unchanged. Match skin tone and lighting so the result reads as one photograph." — this endpoint needs neither.

Check the result before iterating

Both images should show a clearly visible, reasonably frontal, well-lit face; heavy profile angles, motion blur, dense occlusion and very small faces are where the transfer degrades or fails outright. A large mismatch in lighting direction or skin tone between the two images shows at the jawline, so pick a reference whose light roughly matches the target. By default one face is swapped per image; for a group shot, list the pairs in face_mapping (which reference face goes onto which target face, numbered from 0). There is no prompt, no mask and no strength control: if the result is wrong, the fix is a different input pair, not a reworded request.

API quick start

Call the Face Swap 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-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-v1/edit",
  "input": {
    "image_url": "https://media.popnow.ai/influencer/examples/marco.webp",
    "reference_image_url": "https://media.popnow.ai/influencer/examples/ava.webp",
    "style": "realistic"
  }
}'

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

All Face Swap models

Head Swap moves the whole head, hair included; pick by whether the hair should change.

• 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

Try it

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

Docs

Face Swap 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 results without polling