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

# AI Face Editor Tool - Magic Hour Docs

> Edit and enhance facial features with AI-powered precision and natural results.

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

AI Face Editor provides advanced facial editing capabilities using AI to modify and enhance facial features with natural-looking results. The API can adjust expressions, features, and attributes while maintaining realistic proportions and lighting.

<ToolSection
  title="AI Face Editor"
  productSlug="ai-face-editor"
  apiSlug="ai-face-editor"
  type="image"
  outputs={[
{
  src: "/get-started/images/aifaceeditorexample1.png",
},
{
  src: "/get-started/images/aifaceeditorexample2.png",
},
]}
/>

## How It Works

1. **Upload photo** - Provide an image with a clear face
2. **Specify edits** - Describe desired facial modifications
3. **AI processes** - AI applies edits while maintaining natural appearance
4. **Download result** - Retrieve your edited image

## Use Cases

* **Portrait enhancement** - Improve and refine facial features
* **Expression modification** - Adjust facial expressions
* **Beauty editing** - Apply natural-looking enhancements
* **Photo restoration** - Improve quality of facial photos
* **Creative projects** - Experiment with facial modifications

## Best Practices

### Photo Requirements

<Tip>
  **Use high-quality, well-lit photos** - Better source images produce superior editing results.
</Tip>

* **Clear facial features** - All features should be visible
* **Good lighting** - Even lighting produces better results
* **Front-facing preferred** - Works best with frontal angles
* **High resolution** - At least 512x512 pixels recommended

### Edit Guidelines

| Edit Type           | Best Practice                |
| :------------------ | :--------------------------- |
| Feature adjustments | Make subtle, natural changes |
| Expression changes  | Maintain facial structure    |
| Enhancements        | Keep edits realistic         |
| Multiple edits      | Apply one change at a time   |

## Code Examples

### Add Natural Smile

<CodeGroup>
  ```python Python theme={null}
  from magic_hour import Client
  from os import getenv

  client = Client(token=getenv("API_TOKEN"))

  result = client.v1.ai_face_editor.generate(
      assets={
          "image_file_path": "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png"
      },
      style={
          "enhance_face": False,
          "eye_gaze_horizontal": 0.0,
          "eye_gaze_vertical": 0.0,
          "eye_open_ratio": 0.0,
          "eyebrow_direction": 100, # Raise eyebrows
          "head_pitch": 0.0,
          "head_roll": 0.0,
          "head_yaw": 0.0,
          "lip_open_ratio": 0.0,
          "mouth_grim": 0.0,
          "mouth_position_horizontal": 0.0,
          "mouth_position_vertical": 0.0,
          "mouth_pout": 0.0,
          "mouth_purse": 0.0,
          "mouth_smile": 0.0,
      },
      name="Face Editor image",
      wait_for_completion=True,
      download_outputs=True,
      download_directory="."
  )

  if result.status == "complete":
      print(f"✅ Face edit 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.API_TOKEN });

  const result = await client.v1.aiFaceEditor.generate({
    assets: {
      imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png",
    },
    style: {
      enhanceFace: false,
      eyeGazeHorizontal: 0.0,
      eyeGazeVertical: 0.0,
      eyeOpenRatio: 0.0,
      eyebrowDirection: 100, // Raise eyebrows
      headPitch: 0.0,
      headRoll: 0.0,
      headYaw: 0.0,
      lipOpenRatio: 0.0,
      mouthGrim: 0.0,
      mouthPositionHorizontal: 0.0,
      mouthPositionVertical: 0.0,
      mouthPout: 0.0,
      mouthPurse: 0.0,
      mouthSmile: 0.0,
    },
    name: "Face Editor image",
    waitForCompletion: true,
    downloadOutputs: true,
    downloadDirectory: ".",
  });

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

### Raise Eyebrows and Make Mouth Pout

<CodeGroup>
  ```python Python theme={null}
  result = client.v1.ai_face_editor.generate(
      assets={
          "image_file_path": "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png"
      },
      style={
          "enhance_face": False,
          "eye_gaze_horizontal": 0.0,
          "eye_gaze_vertical": 0.0,
          "eye_open_ratio": 0.0,
          "eyebrow_direction": 100, # Raise eyebrows
          "head_pitch": 0.0,
          "head_roll": 0.0,
          "head_yaw": 0.0,
          "lip_open_ratio": 0.0,
          "mouth_grim": 0.0,
          "mouth_position_horizontal": 0.0,
          "mouth_position_vertical": 0.0,
          "mouth_pout": 100, # Make Mouth Pout
          "mouth_purse": 0.0,
          "mouth_smile": 0.0,
      },
      name="Face Editor image",
      wait_for_completion=True,
      download_outputs=True,
      download_directory="."
  )

  if result.status == "complete":
      print(f"✅ Face edit 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}
  const result = await client.v1.aiFaceEditor.generate({
    assets: {
      imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png",
    },
    style: {
      enhanceFace: false,
      eyeGazeHorizontal: 0.0,
      eyeGazeVertical: 0.0,
      eyeOpenRatio: 0.0,
      eyebrowDirection: 100, // Raise eyebrows
      headPitch: 0.0,
      headRoll: 0.0,
      headYaw: 0.0,
      lipOpenRatio: 0.0,
      mouthGrim: 0.0,
      mouthPositionHorizontal: 0.0,
      mouthPositionVertical: 0.0,
      mouthPout: 100, // Make Mouth Pout
      mouthPurse: 0.0,
      mouthSmile: 0.0,
    },
    name: "Face Editor image",
    waitForCompletion: true,
    downloadOutputs: true,
    downloadDirectory: ".",
  });

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

## Pricing

| Output         | Credits   |
| :------------- | :-------- |
| 1 edited image | 1 credits |

<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

<Card title="AI Face Editor API Reference" icon="webhook" href="/api-reference/image-projects/ai-face-editor">
  View full API specification
</Card>

## Related Tools

<CardGroup cols={2}>
  <Card title="AI Headshot Generator" icon="user" href="/tools/image/headshot-generator">
    Generate professional headshots
  </Card>

  <Card title="AI Image Editor" icon="wand-magic-sparkles" href="/tools/image/image-editor">
    Edit and modify full images
  </Card>
</CardGroup>