Image Head Swap | AI Portrait Transfer API

WaveSpeedAI Image Head Swap

WaveSpeedAI Image Head Swap is an advanced AI model for replacing the entire head (face + hair + outline) of a person in a static image using a reference portrait. It keeps body, pose and background intact while rebuilding a new, realistic head that matches the scene’s 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 general 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 whole head contour instead of only facial features, avoiding mismatched hairlines or skull shape.
Pose and expression preservation Uses the base image to keep head angle, gaze direction and expression consistent with the original shot.
Lighting and color matching Automatically adjusts skin tone, shadows and highlights so the new head sits naturally in the scene.
High-resolution blending Seamless edges around neck, hair and accessories, minimizing visible artifacts.

🧾 Inputs and Parameters

Required fields:

image: Base image whose body, background and composition you want to keep.
face_image: Reference portrait that defines the new identity/head to be inserted.

Other options:

output_format: Choose the final image format:
jpeg
png
webp

💰 Pricing

Operation	Price (USD)
Full head swap (per image run)	$0.025

💡 Best Use Cases

Casting and concept design Test different actors’ heads on the same body or costume for film, TV or advertising pitches.
Privacy and anonymization Replace real heads with synthetic or authorized identities while keeping scenes and actions intact.
Photo and key art exploration Quickly iterate on hero posters, thumbnails and cover images with different looks.
Social media and creator workflows Create stylized or character-based versions of yourself while preserving your original photos’ composition.

📎 Tips and Notes

Use clear, reasonably high-resolution portraits for both image and face_image.
Try to keep camera angle and approximate lighting similar between the two inputs for best results.
Avoid heavily occluded faces or extreme motion blur in the base image.
Always ensure you have the legal right and consent to use all images and likenesses involved in your edits.

Image Head Swap API — Quick start

Grab a WaveSpeedAI API key, then call POST https://api.wavespeed.ai/api/v3/wavespeed-ai/image-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 Image Head Swap below.

HTTP example

# Submit the prediction
curl -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/image-head-swap" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -d '{
    "image": "https://example.com/your-input.jpg",
    "output_format": "jpeg",
    "enable_base64_output": false,
    "enable_sync_mode": false
}'

# 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/image-head-swap", {
        "image": "https://example.com/your-input.jpg",
        "output_format": "jpeg",
        "enable_base64_output": false,
        "enable_sync_mode": false
});

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

Python example

# pip install wavespeed
import wavespeed

output = wavespeed.run(
    "wavespeed-ai/image-head-swap",
    {
    "image": "https://example.com/your-input.jpg",
    "output_format": "jpeg",
    "enable_base64_output": false,
    "enable_sync_mode": false
}
)

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

Image Head Swap API — Frequently asked questions

What is the Image Head Swap API?

Image Head Swap is a WaveSpeedAI model for AI inference, exposed as a REST API on WaveSpeedAI. Instant online AI head & face swap for photos 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 Image 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/image-head-swap.

How much does Image Head Swap cost per run?

Image Head Swap starts at $0.025 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 Image Head Swap accept?

Key inputs: `image`, `enable_base64_output`, `enable_sync_mode`, `face_image`, `output_format`. 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/image-head-swap.

How long does Image Head Swap take to generate?

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

Can I use Image 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.

ExamplesView all

Related Models

README