Video Face SwapAbout Video Face Swap
Video Face Swap takes a video clip and a reference face image and carries only the facial features onto the person in the footage, keeping their hair, movement, framing and background. Two URLs and an optional finish — there is no prompt field to write.
Call it with the model name popnow/face-swap-video-v1/video-edit on POST /jobs/createTask, from 3.9 credits per second ($0.039). New accounts get 30 free credits to try it in the Playground first.
Introduction
Video Face Swap carries the facial features from a single reference image onto the person in a video, through every frame of the clip. Only the features travel: the performer's hairstyle, head silhouette, movement, wardrobe, lighting, camera work and background all stay as they were shot, which is what keeps the result reading as the original footage rather than an overlay.
Video Face Swap takes a video clip and a reference face image and carries only the facial features onto the person in the footage, keeping their hair, movement, framing and background. Two URLs and an optional finish — there is no prompt field to write.
Key features
Preserve the performance, change the facial identity
Face Swap applies the identity from the approved reference to the person in the supplied footage while keeping the live-action performance intact. Choose a source clip whose subject, framing and lighting already work, because the workflow is for identity replacement rather than rebuilding a shot.
Review continuity, not a synthetic scene
Judge the result at normal playback speed across turns, cuts and fast movement. Check that the identity transfer remains coherent while the performer’s hair, motion, wardrobe and background still read as the original footage; use the clearest discontinuity to guide the next revision.
Request parameters
| Parameter | Required | Description |
|---|---|---|
face_enhance | No | Run a face-enhancement pass on the swapped face for a sharper, more detailed result. Default: false |
face_mapping | No | Multi-person swap: which face in the reference image goes onto which face in the target, one entry per face. Faces are numbered from 0 in detection order. |
reference_image_url | Yes | Reference face image. The facial features from this image are carried onto the person in the video. |
style | No | A preset look or genre. realistic · beautify · lossless · Default: realistic |
video_url | Yes | The clip to work on. |
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 second | ≈ USD |
|---|---|---|
| Standard | 3.9 | $0.039 |
For an exact number before you run, send the same body to POST /jobs/quote.
Use cases
video edit workflow
This endpoint changes facial features across supplied video footage using a separate reference face; it has no text prompt. Use the source clip as the starting point and state the exact edit alongside the timing, identity and continuity that must remain unchanged. This contract accepts reference_image_url, style, video_url.
Make the contract part of the brief
Keep the edit scope narrow on the first run so the source footage remains a useful comparison point. For face-swap/video-v1, the controls most relevant to this endpoint are video_url, reference_image_url, style.
Review the delivered result
Review cut boundaries, motion continuity and the unedited regions against the original footage.
Prompt guide & pro tips
Build a video edit request
face-swap/video-v1: begin with video_url, reference_image_url, style. Use the source clip as the starting point and state the exact edit alongside the timing, identity and continuity that must remain unchanged. This contract accepts reference_image_url, style, video_url.
Change one delivery control at a time
face-swap/video-v1: Keep the submitted inputs consistent while comparing variations so the result can be reviewed against a stable brief. Keep the edit scope narrow on the first run so the source footage remains a useful comparison point.
Turn review notes into the next run
When revising, isolate one edit at a time so it is clear whether the change or the source boundary caused a continuity issue.
Inspect before scaling the next run
Review cut boundaries, motion continuity and the unedited regions against the original footage.
API quick start
Call the Video Face Swap 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-video-v1/video-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-video-v1/video-edit",
"input": {
"video_url": "https://media.popnow.ai/effects/flower-bloom-1abd6efb.mp4",
"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.
Video Face Swap API questions
How much does the Video Face Swap API cost?
Video Face Swap costs 3.9 credits ($0.039) per second. 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 Video Face Swap in the API?
Put popnow/face-swap-video-v1/video-edit for Video Face Swap in the model field of POST /jobs/createTask.
How is this different from Face Swap?
Face Swap changes a still image. Video Face Swap carries the same kind of feature transfer through a whole clip, frame by frame. The reference is a still image in both cases.
Which input goes where?
video_url is the clip being changed and reference_image_url is the photo supplying the face. One is footage and the other is a still, so they cannot be mixed up by accident.
Is there a prompt, a mask or a seed?
No. The schema is video_url, reference_image_url and an optional style. There is nothing to phrase and no region to paint, which removes a whole class of ambiguous-instruction failures.
Which style should I pick?
Start with realistic, the default, which keeps natural skin tone and texture. Beautify smooths and brightens the skin. Lossless keeps the most facial detail from the reference and suits close-ups.
What footage works best?
One person on screen, face reasonably large in frame, lit evenly and not turned away from the camera for long. Heavy profile angles, fast motion blur, hands over the face and tiny faces are where the result degrades.
Can I try Video Face Swap without writing code?
Yes. The Playground runs Video Face Swap on your PopNow credits, needs no API key, and shows the matching code for every run.
All Video Face Swap models
Face Swap does the same for still photos.
- 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
