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

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

Multiple faces

assets.face_swap_mode defaults to all-faces, which uses source_file_path to replace every detected target face. For selective swaps, use individual-faces and provide up to 5 face_mappings with original_face and new_face. Obtain original_face paths from face detection.

Code Examples

Basic Face Swap

Pricing

Face Swap Photo uses a flat credit cost per image:
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

Request failures return a code and message; for example, invalid_request indicates invalid parameters and insufficient_credits means the account needs more credits. See the API reference for request error responses. A render failure appears as status: "error" in image project details, with error.code and error.message. For example, no_source_face means the API could not detect a face in the source. Inspect the returned message before retrying.

Bulk Face Swap Guide

Process a bounded list while preserving project IDs and recovery state

Head Swap

Replace the full head while retaining the body and scene

Body Swap

Place a person into a different scene

Face Swap Video

Swap faces in videos with frame-by-frame precision

AI Headshot Generator

Generate professional headshots from a single photo