Face Swap Video Tool - Magic Hour Docs

Replace faces in videos with frame-by-frame precision and temporal consistency.

Overview

Face Swap Video replaces faces in videos with frame-by-frame precision and temporal consistency. The API swaps faces throughout video sequences while maintaining natural expressions, head movements, and lighting for realistic results.

API Spec

See API details

Product Page

Learn more about Face Swap Video

How It Works

1. Provide a source face - Upload an image containing the face you want to use
2. Provide a target video - Upload the video where you want to swap the face
3. Set start/end times - Define which portion of the video to process
4. API processes frame-by-frame - AI swaps the face consistently across all frames
5. Download the result - Retrieve your face-swapped video

Use Cases

• Entertainment content - Create viral videos and memes
• Privacy protection - Anonymize individuals in video content
• Film and media - Character replacement in post-production
• Personalized experiences - Custom video messages and greetings
• Marketing - Create personalized ad experiences

Best Practices

Source Face Image

Use a clear, high-quality face photo - The better your source image, the better the swap quality.

• Front-facing or slight angle - Avoid extreme profile shots
• Good lighting - Even lighting with no harsh shadows
• High resolution - At least 512x512 pixels for the face area
• Neutral expression - Works best for most video expressions
• No obstructions - Avoid sunglasses, masks, or hair covering face

Target Video Requirements

• Clear face visibility - Face should be clearly visible in the video
• Stable lighting - Consistent lighting throughout produces best results
• One primary face - Works best when targeting a single person
• Moderate motion - Extreme head movements may affect quality

Video Segment Selection

Factor	Recommendation
Duration	Start with 5-10 seconds to test quality
Face size	Larger faces in frame = better results
Motion	Moderate movement works best
Occlusions	Avoid frames where face is partially hidden

Code Examples

Basic Face Swap

Python

from magic_hour import Client
import os

client = Client(token=os.getenv("MAGIC_HOUR_API_KEY"))

result = client.v1.face_swap.generate(
    assets={
        "image_file_path": "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png",
        "video_file_path": "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/obamamicdrop.mov",
        "video_source": "file"
    },
    start_seconds=0,
    end_seconds=2,
    name="Tom Cruise Face Swap",
    wait_for_completion=True,
    download_outputs=True,
    download_directory="."
)

if result.status == "complete":
    print(f"✅ Face swap complete!")
    print(f"Downloaded to: {result.downloaded_paths}")
    print(f"Credits charged: {result.credits_charged}")
else:
    print(f"❌ Job failed with status: {result.status}")
    if hasattr(result, 'error_message'):
        print(f"Error: {result.error_message}")

import { Client } from "magic-hour";

const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY });

const result = await client.v1.faceSwap.generate({
  assets: {
    imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png",
    videoFilePath:
      "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/obamamicdrop.mov",
    videoSource: "file",
  },
  startSeconds: 0,
  endSeconds: 2,
  name: "Tom Cruise Face Swap",
  waitForCompletion: true,
  downloadOutputs: true,
  downloadDirectory: ".",
});

console.log(`✅ Face swap complete!`);
console.log(`Status: ${result.status}`);
console.log(`Downloaded to: ${result.downloadedPaths}`);

Pricing

Face Swap Video uses credits based on video duration and frame rate:

Factor	Impact
Duration	More seconds = more credits
Frame rate	Higher FPS = more credits
Resolution	Affects quality, not cost

Example: A 10-second video at 30 FPS ≈ 300 credits

Error Handling

Common error codes:

Error Code	Description	Solution
no_source_face	No face detected in source image	Use image with clear, visible face
no_target_face	No face detected in target video	Ensure face is visible in video
invalid_file_format	Unsupported file format	Use MP4, MOV, or WEBM for video

Try this in our Google Colab Cookbook: Run this API with sample code. Just add your API key.

API Reference

Face Swap Video API Reference

View full API specification

Related Tools

Face Swap Photo

Swap faces in static images

Lip Sync

Sync audio with video lip movements