Video Head Swap | AI Portrait Transfer API

WaveSpeedAI Video Head Swap

WaveSpeedAI Video Head Swap is an advanced AI model for replacing the entire head (face + hair + outline) of a person in a video using a reference portrait. The model keeps the body, pose, and background intact while reconstructing a new, realistic head that matches the original lighting and perspective.

🎬 What this model does

Replaces the full head region of the subject (face, hair, silhouette, accessories)
Preserves body pose, clothing, background, and overall composition
Adapts the new head to scene lighting, color tone, and camera angle
Produces clean, watermark-free outputs ready for editing or publication

⚙️ Why it looks realistic

Full-head geometry replacement Swaps the entire head contour instead of only facial features, avoiding mismatched hairlines or distorted skull shapes.
Pose and expression preservation Follows the motion in the source video so head angle, gaze direction, and expression remain consistent with the original performance.
Lighting and color matching Automatically adjusts skin tone, shadows, and highlights so the new head blends naturally into the scene.
High-resolution blending Smooth transitions around hair, neck, and accessories, minimizing visible seams or flicker across frames.

💰 Pricing

Pricing is based on video duration and output resolution, with a 5-second minimum and 120-second cap.

Resolution	Price per second	Min charge (5 s)	Max charge (120 s)
480p	$0.040	$0.200	$4.800
720p	$0.080	$0.400	$9.600

Minimum billed duration: 5 seconds
Maximum billed duration: 120 seconds per run (longer clips are capped at 120 s)

🔧 Input Parameters

video (required)

The source video whose head you want to replace. This defines body motion, framing, and background.

face_image / head_image (required)

A clear portrait of the target identity. Frontal or three-quarter views with good lighting work best.

resolution

Output resolution for the processed video, for example:

480p – more affordable drafts or quick previews
720p – higher-quality output suitable for most publishing workflows

seed (optional)

Controls stochastic variation in generation:

-1 or empty → random seed each run
Any positive integer → reproducible results for the same inputs

(Exact field name may differ between Playground and API, but behavior is identical.)

🎯 Designed For

Creators & influencers – Turn one performance into many identities without reshooting.
Marketing & brands – Localize or personalize talking-head content while keeping the same body and scene.
Film, TV & post-production – Rapid previs, mockups, and concept tests for head-replacement shots.
Privacy & compliance – Replace real heads with synthetic or authorized identities while preserving situational context.

▶️ How to Use

Upload or paste the URL of the video to edit.
Upload a face/head reference image for the identity you want to swap in.
Select the output resolution (480p or 720p).
(Optional) Set a seed if you need reproducible results.
Click Run to generate the swapped video.
Review the result; if needed, adjust the reference portrait or seed and run again.

📌 Tips & Notes

Use sharp, well-lit videos where the face is not heavily occluded or motion-blurred.
For the reference portrait, keep expression and angle reasonably close to the target shot for the cleanest match.
Avoid extreme mismatches in lighting (e.g., dark blue stage light in video vs. warm daylight portrait) unless you want a stylized look.
Ensure you have the legal right and consent to use all uploaded videos and portraits.

Video Head Swap API — Quick start

Grab a WaveSpeedAI API key, then call POST https://api.wavespeed.ai/api/v3/wavespeed-ai/video-head-swap with your input as JSON. The endpoint returns a prediction id; poll the prediction endpoint until status flips to completed, then read the output URL from data.outputs[0]. Examples for Video Head Swap below.

HTTP example

# Submit the prediction
curl -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/video-head-swap" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -d '{
    "video": "https://example.com/your-input.mp4",
    "prompt": "A cinematic shot of a city at sunset, soft golden light",
    "resolution": "480p",
    "seed": -1
}'

# Response includes a prediction id. Poll for the result:
curl -X GET "https://api.wavespeed.ai/api/v3/predictions/{request_id}/result" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY"

# When status is "completed", read the output from data.outputs[0].

Node.js example

// npm install wavespeed
const WaveSpeed = require('wavespeed');

const client = new WaveSpeed(); // reads WAVESPEED_API_KEY from env

const result = await client.run("wavespeed-ai/video-head-swap", {
        "video": "https://example.com/your-input.mp4",
        "prompt": "A cinematic shot of a city at sunset, soft golden light",
        "resolution": "480p",
        "seed": -1
});

console.log(result.outputs[0]); // → URL of the generated output

Python example

# pip install wavespeed
import wavespeed

output = wavespeed.run(
    "wavespeed-ai/video-head-swap",
    {
    "video": "https://example.com/your-input.mp4",
    "prompt": "A cinematic shot of a city at sunset, soft golden light",
    "resolution": "480p",
    "seed": -1
}
)

print(output["outputs"][0])  # → URL of the generated output

Video Head Swap API — Frequently asked questions

What is the Video Head Swap API?

Video Head Swap is a WaveSpeedAI model for AI inference, exposed as a REST API on WaveSpeedAI. Instant online AI head & face swap for videos with no watermark, delivering realistic, shareable results in seconds. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing. You can call it programmatically or try it from the playground above.

How do I call the Video Head Swap API?

POST your input parameters to the model's REST endpoint (shown in the API tab of this playground) with your WaveSpeedAI API key in the Authorization header. Submission returns a prediction ID; poll the prediction endpoint until status flips to "completed", then read the output URL from the result. The playground generates a ready-to-paste code sample in Python, JavaScript, or cURL for whatever inputs you've set. Full request/response shape is documented at https://wavespeed.ai/docs/docs-api/wavespeed-ai/video-head-swap.

How much does Video Head Swap cost per run?

Video Head Swap starts at $0.20 per run. That figure is the base price — the final charge scales with the parameters you set in the form (output size, length, count, references, or whatever knobs this model exposes), so a higher-quality or larger output costs more than a minimal one. The exact cost for your current input is shown live next to the Generate button before you submit, and the actual per-call charge is recorded on the prediction afterwards.

What inputs does Video Head Swap accept?

Key inputs: `prompt`, `video`, `resolution`, `seed`, `face_image`. The full JSON schema (types, defaults, allowed values) is rendered above the Generate button and mirrored in the API reference at https://wavespeed.ai/docs/docs-api/wavespeed-ai/video-head-swap.

How long does Video Head Swap take to generate?

Average end-to-end generation time on WaveSpeedAI is around 1141 seconds per request — measured across recent runs. Queue time scales with global demand; live status is visible in the prediction record.

Can I use Video Head Swap outputs commercially?

Commercial usage rights depend on the model's license, set by its provider (WaveSpeedAI). The license summary appears on the model card above; see WaveSpeedAI's Terms of Service for platform-level conditions.

ตัวอย่างดูทั้งหมด

โมเดลที่เกี่ยวข้อง

README