> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magichour.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Face Swap Photo Tool - Magic Hour Docs

> Replace faces in photos with realistic precision and natural blending.

export const ToolSection = ({type = "image", outputs = [], title = "", productSlug = "", apiSlug = ""}) => <>
    {outputs && outputs.length > 0 && <Tabs>
        {outputs.map((output, idx) => <Tab key={idx} title={`Example Output ${idx + 1}`}>
            <Frame>
              {type === "video" ? <video controls preload="metadata" playsInline className="rounded-lg h-80" src={`${output.src}#t=0.001`} type={`${output.src?.endsWith("mp4") ? 'video/mp4' : "video/webm"}`}>
                </video> : type === "audio" ? <audio controls preload="metadata" className="w-full" src={output.src}>
                  Your browser does not support the audio element.
                </audio> : <img height="320" className="rounded-lg h-80" src={output.src} />}
            </Frame>
          </Tab>)}
      </Tabs>}

    <CardGroup cols={2}>
      <Card title="API Spec" icon="webhook" horizontal href={`/api-reference/${type}-projects/${apiSlug}`}>
        See API details
      </Card>
      <Card title="Product Page" icon="video" horizontal href={`https://magichour.ai/products/${productSlug}`}>
        Learn more about {title}
      </Card>
    </CardGroup>

  </>;

## 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.

<ToolSection
  title="Face Swap Photo"
  productSlug="face-swap?mode=photo"
  apiSlug="face-swap-photo"
  type="image"
  outputs={[
{
  src: "/get-started/images/faceswapphotoexample1.jpg",
},
{
  src: "/get-started/images/mr-bean-swap.jpeg",
},
]}
/>

## 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

<Tip>
  **Use high-resolution images** - Higher quality source images produce better results. Aim for at
  least 512x512 pixels for the face area.
</Tip>

* **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

| Issue              | Cause                      | Solution                                 |
| :----------------- | :------------------------- | :--------------------------------------- |
| Face not detected  | Face too small or obscured | Use a clearer, larger face image         |
| Unnatural blending | Lighting mismatch          | Match lighting between source and target |
| Distorted features | Extreme angle difference   | Use more similar face angles             |
| Low quality output | Low resolution input       | Use higher resolution images             |

## Code Examples

### Basic Face Swap

<CodeGroup>
  ```python Python theme={null}
  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="."
  )

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

  ```javascript Node.js theme={null}
  import { Client } from "magic-hour";

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

  const result = await client.v1.faceSwapPhoto.generate({
    assets: {
      sourceFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png",
      targetFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png",
    },
    name: "My Face Swap",
    waitForCompletion: true,
    downloadOutputs: true,
    downloadDirectory: ".",
  });

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

## Pricing

Face Swap Photo uses a flat credit cost per image:

| Output            | Credits   |
| :---------------- | :-------- |
| 1 face swap image | 5 credits |

<Info>
  Credits are charged when the job is created. If the job fails, credits are refunded automatically.
</Info>

<Tip>
  **Try this in our Google Colab Cookbook:** [Run this API with sample
  code](https://colab.research.google.com/drive/1NTHL_lr_s-qBJ-mSecSXPzRLi9_V5JiU?usp=sharing). Just
  add your API key.
</Tip>

## API Reference

For complete API details including all parameters and response formats:

<Card title="Face Swap Photo API Reference" icon="webhook" href="/api-reference/image-projects/face-swap-photo">
  View full API specification
</Card>

## Error Handling

Common error codes and how to handle them:

| 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 image | Use image with clear, visible face |
| `invalid_file_format` | Unsupported file format          | Use PNG, JPG, JPEG, or WEBP        |
| `file_too_large`      | File exceeds size limit          | Compress or resize the image       |

## Related Tools

<CardGroup cols={2}>
  <Card title="Face Swap Video" icon="video" href="/tools/video/face-swap-video">
    Swap faces in videos with frame-by-frame precision
  </Card>

  <Card title="AI Headshot Generator" icon="user" href="/tools/image/headshot-generator">
    Generate professional headshots from a single photo
  </Card>
</CardGroup>