Skip to main content

​
Overview

Face Swap Photo lets you replace faces in static images with realistic precision and natural blending. The API swaps faces between two photos while preserving facial expressions, lighting conditions, and image quality for seamless results.

API Spec

See API details

Product Page

Learn more about Face Swap Photo

​
How It Works

  1. Provide a source face - Upload an image containing the face you want to use
  2. Provide a target image - Upload the image where you want to swap the face
  3. API processes the swap - AI detects faces, aligns features, and blends seamlessly
  4. Download the result - Retrieve your face-swapped image

​
Use Cases

  • Entertainment content - Create fun social media content and memes
  • Privacy protection - Replace faces to anonymize individuals in photos
  • Creative projects - Character replacement in digital art and design
  • Marketing - Personalized ad experiences with customer faces
  • Photo editing apps - Build face swap features into your application

​
Best Practices

​
Image Quality

Use high-resolution images - Higher quality source images produce better results. Aim for at least 512x512 pixels for the face area.
  • Clear, well-lit faces - Ensure faces are clearly visible with good lighting
  • Front-facing angles work best - Extreme profile angles may reduce quality
  • Avoid obstructions - Glasses, hands, or hair covering the face can affect results
  • Similar lighting conditions - Match lighting between source and target for more natural results

​
Face Detection Tips

  • One clear face per image - The API works best with a single prominent face
  • Visible facial features - Eyes, nose, and mouth should all be visible
  • Neutral to moderate expressions - Extreme expressions may affect alignment

​
Common Issues and Solutions

IssueCauseSolution
Face not detectedFace too small or obscuredUse a clearer, larger face image
Unnatural blendingLighting mismatchMatch lighting between source and target
Distorted featuresExtreme angle differenceUse more similar face angles
Low quality outputLow resolution inputUse higher resolution images

​
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_photo.generate(
    assets={
        "source_file_path": "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png",
        "target_file_path": "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/lebron.jpg"
    },
    name="My 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 Photo uses a flat credit cost per image:
OutputCredits
1 face swap image5 credits
Credits are charged when the job is created. If the job fails, credits are refunded automatically.
Try this in our Google Colab Cookbook: Run this API with sample code. Just add your API key.

​
API Reference

For complete API details including all parameters and response formats:

Face Swap Photo API Reference

View full API specification

​
Error Handling

Common error codes and how to handle them:
Error CodeDescriptionSolution
no_source_faceNo face detected in source imageUse image with clear, visible face
no_target_faceNo face detected in target imageUse image with clear, visible face
invalid_file_formatUnsupported file formatUse PNG, JPG, JPEG, or WEBP
file_too_largeFile exceeds size limitCompress or resize the image

Face Swap Video

Swap faces in videos with frame-by-frame precision

AI Headshot Generator

Generate professional headshots from a single photo