> ## 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 Talking Photo API

> Animate static photos to speak with realistic lip-sync and facial movements.

export const ToolSection = ({type = "image", outputs = [], title = "", productSlug = "", apiSlug = ""}) => <>
    <CardGroup cols={2}>
      <Card title={`${title} API reference`} icon="webhook" horizontal href={`/api-reference/${type}-projects/${apiSlug}`}>
        Request fields, responses, and examples
      </Card>
      <Card title="API quickstart" icon="forward-fast" horizontal href="/get-started/quick-start">
        Install an SDK and complete your first generation
      </Card>
    </CardGroup>

    <p>
      Check <a href="/billing/overview">API pricing</a> and <a href="/api-reference/models">model credit costs</a>, then <a href={`https://magichour.ai/developer?tab=api-keys&ref=docs-tool-${apiSlug}&utm_source=docs&utm_medium=referral&utm_campaign=tools`}>create an API key</a>.
    </p>
    <p>
      To try {title} without code, use the <a href={`https://magichour.ai/products/${productSlug}${productSlug.includes("?") ? "&" : "?"}utm_source=docs&utm_medium=referral&utm_campaign=tools`}>browser tool</a>.
    </p>

    {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} alt={`${title} example output ${idx + 1}`} />}
            </Frame>
          </Tab>)}
      </Tabs>}

  </>;

## Overview

AI Talking Photo brings static photos to life by animating faces to speak with realistic lip-sync and natural facial movements. The API analyzes facial features and synchronizes mouth movements, head poses, and expressions with the audio file you provide.

**Processing:** See recent [typical API-job times](/api-reference/processing-times). Jobs run
asynchronously, and duration varies with the input, selected settings, and queue load.

<ToolSection
  title="AI Talking Photo"
  productSlug="ai-talking-photo"
  apiSlug="ai-talking-photo"
  type="video"
  outputs={[
{
  src: "/get-started/images/talkingphotoexample1.mp4",
},
{
  src: "/get-started/images/talkingphotoexample2.mp4",
},
]}
/>

## How It Works

1. **Provide a photo** - Upload an image with a clear face
2. **Add audio** - Provide an audio file (required). To generate speech from text, create the audio first with the [AI Voice Generator](/tools/audio/voice-generator)
3. **API animates** - AI creates realistic lip-sync and facial movements
4. **Download video** - Retrieve your animated talking photo

## Use Cases

* **Marketing videos** - Create spokesperson videos from headshots
* **Educational content** - Animate historical figures or characters
* **Personalized messages** - Send video messages from static photos
* **Social media** - Create engaging content from profile pictures
* **Presentations** - Add dynamic talking heads to slides

## Best Practices

### Photo Selection

<Tip>
  **Use clear, front-facing photos** - Best results come from high-quality headshots with visible
  facial features.
</Tip>

* **Good lighting** - Well-lit faces produce better animations
* **Front-facing angles** - Avoid extreme profile shots
* **Clear features** - Eyes, nose, and mouth should be unobstructed
* **High resolution** - At least 512x512 pixels recommended

### Audio Guidelines

| Audio Type       | Best Practice                                                                      |
| :--------------- | :--------------------------------------------------------------------------------- |
| Voice recording  | Clear speech without background noise                                              |
| Generated speech | Create the audio first with the [AI Voice Generator](/tools/audio/voice-generator) |
| Music/songs      | Works best with clear vocals                                                       |
| Length           | Test a short segment first; API limits depend on generation mode                   |

## Generation modes

Set `style.generation_mode` to `realistic`, the default, to preserve likeness, or `prompted` to guide the scene with `style.prompt`. The maximum selected audio duration is 300 seconds for `realistic` and 45 seconds for `prompted`.

The older `pro`, `standard`, `stable`, and `expressive` values are deprecated. Use the current mode names for new integrations; `style.intensity` is also deprecated.

## Code Examples

### Basic Talking Photo

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

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

  result = client.v1.ai_talking_photo.generate(
      assets={
          "image_file_path": "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png",
          "audio_file_path": "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/you-are-just-a-line-of-code.mp3"
      },
      name="Talking Photo",
      start_seconds=0,
      end_seconds=2,
      wait_for_completion=True,
      download_outputs=True,
      download_directory="."
  )

  if result.status == "complete":
      print(f"✅ Talking photo 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}")
  ```

  ```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.aiTalkingPhoto.generate(
    {
      assets: {
        imageFilePath: "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/tomcruise.png",
        audioFilePath:
          "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/you-are-just-a-line-of-code.mp3",
      },
      name: "Talking Photo",
      startSeconds: 0,
      endSeconds: 2,
    },
    {
      waitForCompletion: true,
      downloadOutputs: true,
      downloadDirectory: ".",
    }
  );

  if (result.status === "complete") {
    console.log(`✅ Talking photo complete!`);
    console.log(`Downloaded to: ${result.downloadedPaths}`);
  } else {
    console.error(`Job ended with status: ${result.status}`);
    if (result.error) console.error(result.error.message);
  }
  ```
</CodeGroup>

<Note>
  `start_seconds` and `end_seconds` are **required** — they control which segment of the audio is
  used. Video pricing is duration-based, so shorter segments cost less.
</Note>

## Pricing

Talking Photo pricing depends on the output duration, `end_seconds` minus `start_seconds`. The create response reports estimated `credits_charged`; read the completed job for the final amount.

## Resolution Limits

Use `max_resolution` to constrain the larger output dimension in pixels. The API caps this setting at your plan maximum; supported output sizes also depend on the tool. See [Resolution Limits](/billing/resolution-limits) for current limits.

<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 Talking Photo API Reference" icon="webhook" href="/api-reference/video-projects/ai-talking-photo">
  View full API specification
</Card>

## Related Tools

<CardGroup cols={2}>
  <Card title="Lip Sync" icon="lips" href="/tools/video/lip-sync">
    Sync audio with existing video lip movements
  </Card>

  <Card title="AI Voice Generator" icon="microphone" href="/tools/audio/voice-generator">
    Generate speech audio for your talking photos
  </Card>
</CardGroup>