Skip to main content

​
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

FactorRecommendation
DurationStart with 5-10 seconds to test quality
Face sizeLarger faces in frame = better results
MotionModerate movement works best
OcclusionsAvoid frames where face is partially hidden

​
Code Examples

​
Basic Face Swap

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="./outputs/"
)

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}")

​
Pricing

Face Swap Video uses credits based on video duration and frame rate:
FactorImpact
DurationMore seconds = more credits
Frame rateHigher FPS = more credits
ResolutionAffects quality, not cost
Example: A 10-second video at 30 FPS ≈ 300 credits

​
Error Handling

Common error codes:
Error CodeDescriptionSolution
no_source_faceNo face detected in source imageUse image with clear, visible face
no_target_faceNo face detected in target videoEnsure face is visible in video
invalid_file_formatUnsupported file formatUse 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

Face Swap Photo

Swap faces in static images

Lip Sync

Sync audio with video lip movements