Introduction
Overview
Video Face Swap API transfers a photo’s facial identity through an existing clip, with selectable finish, optional enhancement and explicit mappings for multiple people. Video Face Swap edits identity within supplied footage; review the change at normal speed through turns and occlusions instead of judging only a single successful frame.
Inputs and controls
video_url supplies the MP4 for Video Face Swap, including the performance, camera movement and scene; use a direct file link or upload the clip. The video workflow takes its face from reference_image_url, a still portrait; choose a reference whose lighting is compatible with the footage. Video Face Swap offers style, face_enhance and face_mapping alongside its two required URLs; it does not accept a prompt, mask or seed.
Review and limits
On SpicyAPI, Video Face Swap accepts source clips from 3 to 40 seconds; motion blur, small faces and occlusion can reduce the quality of the transfer.
Task and delivery
Keep the Video Face Swap task ID after submission and poll for completion; compare the delivered clip with the original across cuts, turns and the unchanged scene before saving it. For Video Face Swap, style defaults to realistic, with beautify and lossless alternatives; face_enhance is a separate optional pass and is off by default.
Authorised use
For Video Face Swap, obtain permission for the footage and every adult likeness being replaced or inserted; preserve explicit, informed consent for the specific clip and purpose, without impersonation or defamation.
| Field | Value |
|---|---|
| Input | Video |
| Output | Video |
| Endpoint | Video Edit |
| Required input | Target video URL and reference face image URL |
| What transfers | Facial features only |
| What is preserved | Hair, head shape, movement, wardrobe, lighting, framing and background from the clip |
| Controls | style / |
| Authorisation | Only likenesses you are authorised to process |
Request parameters
| Parameter | Required | Description |
|---|---|---|
video_url | Yes |
|
reference_image_url | Yes | The video workflow takes its face from |
face_mapping | No | Without |
face_enhance | No | For Video Face Swap, |
style | No | realistic (default) keeps natural skin tone and texture; beautify smooths and brightens the skin; lossless keeps the most facial detail from the reference. Try realistic first. |
Pricing
$0.026 / output second
Billed in whole 10-second blocks of the source clip, so a 12-second clip costs the same as 20 seconds. The source clip must run 3 to 40 seconds; the estimate before submission uses the actual length of a clip you uploaded, or the 40-second maximum for a video URL, and any difference is released when the task settles.
Use cases
One face across a generated series
Generate a set of clips with any video model, then bring one consented face across all of them so the series reads as the same person. Movement, wardrobe and set stay with each clip, so the variation you generated survives the pass.
Uncensored content with a consented performer's likeness
For Video Face Swap, obtain permission for the footage and every adult likeness being replaced or inserted; preserve explicit, informed consent for the specific clip and purpose, without impersonation or defamation.
Recasting a take that already works
Keep a take whose lighting, blocking and camera move are already approved and put a different face in it, rather than regenerating the whole shot and losing the performance you had.
Localised or personalised video variants
Produce one master clip and swap in faces of authorised presenters for different markets or customers. With no prompt to write, the pairs can be pushed through the endpoint programmatically.
Prompt guide & pro tips
Authorised use
For Video Face Swap, obtain permission for the footage and every adult likeness being replaced or inserted; preserve explicit, informed consent for the specific clip and purpose, without impersonation or defamation.
Host the clip and the face, then send the pair
Video Face Swap offers style,
face_enhanceandface_mappingalongside its two required URLs; it does not accept a prompt, mask or seed.Start short, then poll the task
Keep the Video Face Swap task ID after submission and poll for completion; compare the delivered clip with the original across cuts, turns and the unchanged scene before saving it.
Overview
Video Face Swap API transfers a photo’s facial identity through an existing clip, with selectable finish, optional enhancement and explicit mappings for multiple people. Video Face Swap edits identity within supplied footage; review the change at normal speed through turns and occlusions instead of judging only a single successful frame.
Inputs and controls
video_url supplies the MP4 for Video Face Swap, including the performance, camera movement and scene; use a direct file link or upload the clip. The video workflow takes its face from reference_image_url, a still portrait; choose a reference whose lighting is compatible with the footage. Video Face Swap offers style, face_enhance and face_mapping alongside its two required URLs; it does not accept a prompt, mask or seed.
Review and limits
On SpicyAPI, Video Face Swap accepts source clips from 3 to 40 seconds; motion blur, small faces and occlusion can reduce the quality of the transfer.
Task and delivery
Keep the Video Face Swap task ID after submission and poll for completion; compare the delivered clip with the original across cuts, turns and the unchanged scene before saving it. For Video Face Swap, style defaults to realistic, with beautify and lossless alternatives; face_enhance is a separate optional pass and is off by default.
Authorised use
For Video Face Swap, obtain permission for the footage and every adult likeness being replaced or inserted; preserve explicit, informed consent for the specific clip and purpose, without impersonation or defamation.
Video Face Swap rounds source duration up to whole 10-second billing blocks: a 12-second clip is billed as 20 seconds, within the 3-to-40-second input limit.
Without face_mapping, every face detected in the clip is replaced with the reference face; to change only one person, add a single entry with that person's target_face_index (numbered from 0 in detection order, which can change after a cut). For Video Face Swap, style defaults to realistic, with beautify and lossless alternatives; face_enhance is a separate optional pass and is off by default.
API quick start
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/face-swap-video-v1/video-edit",
"input": {
"reference_image_url": "https://example.com/reference.png",
"style": "realistic",
"video_url": "https://example.com/reference.mp4"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
See the API reference for authentication, the complete schema, polling, and error handling.









