Face Swap Video API

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. Processing: See recent typical API-job times. Jobs run asynchronously, and duration varies with the input, selected settings, and queue load.

How It Works

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

Use Cases

Entertainment content - Create viral videos and memes
Try alternate faces for a scene.
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

Multiple faces and versions

The default assets.face_swap_mode="all-faces" uses one image_file_path to replace every detected face. To target particular people, use individual-faces with up to five face_mappings, obtained using the face detection API. style.version="default" follows the recommended version over time. Set v1 or v2 when you need a specific version. Deprecated width and height fields do not control output resolution.

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

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 ended with status: {result.status}")
    if result.error:
        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: ".",
  }
);

if (result.status === "complete") {
  console.log(`✅ Face swap complete!`);
  console.log(`Downloaded to: ${result.downloadedPaths}`);
} else {
  console.error(`Job ended with status: ${result.status}`);
  if (result.error) console.error(result.error.message);
}

Pricing

Face Swap Video uses credits based on video duration and frame rate — credits are only charged for the frames that actually render:

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

The create response returns an estimated credits_charged; the final amount can change after rendering based on the actual output frame rate. Check the completed job’s credits_charged for the exact cost.

Error Handling

When a render fails, the video project returns status="error" with an error object containing code and message. For example, no_source_face means the source needs a detectable face. Check result.error.message for guidance; canceled jobs can have no error object. Request failures are reported separately as HTTP errors. See Get Video Details.

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

API Reference