---
title: "AI Talking Photo"
method: POST
path: "/v1/ai-talking-photo"
tags: ["Video Projects"]
---

# AI Talking Photo

`POST /v1/ai-talking-photo`

## Request

- Base URL: `https://api.magichour.ai`
- URL: `https://api.magichour.ai/v1/ai-talking-photo`
- Auth: HTTP bearer

Create a talking photo video from an image and an audio file.

## Request body

- object: Provide the assets for creating a talking photo
  - `name` string: Give your video a custom name for easy identification.
  - `start_seconds` number, float, required: The start time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 300s, prompted 60s.
  - `end_seconds` number, float, required: The end time of the input audio in seconds. Maximum clip length depends on style.generation_mode: realistic 300s, prompted 60s.
  - `assets` object, required: Provide the assets for creating a talking photo
    - `image_file_path` string, required: The source image to animate. This value is either - a direct URL to the file. The URL path must end in a supported file extension. - `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls). See the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.
    - `audio_file_path` string, required: The audio file to sync with the image. This value is either - a direct URL to the file. The URL path must end in a supported file extension. - `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls). See the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details.
  - `style` object: Attributes used to dictate the style of the output
    - `generation_mode` 'realistic' | 'prompted' | 'pro' | 'standard' | 'stable' | 'expressive': Controls overall motion style. * `realistic` - Maintains likeness well, high quality, and reliable. * `prompted` - Slightly lower likeness; allows option to prompt scene. **Deprecated values (maintained for backward compatibility):** * `pro` - Deprecated: use `realistic` * `standard` - Deprecated: use `prompted` * `stable` - Deprecated: use `realistic` * `expressive` - Deprecated: use `prompted`
    - `prompt` string: A text prompt to guide the generation. Only applicable when generation_mode is `prompted`. This field is ignored for other modes.
  - `resolution` '480p' | '720p': Output preset. Overrides `max_resolution`. Defaults to 480p in prompted mode; realistic mode uses the mapped plan maximum.

## Response `200`

Success

- object: Success
  - `id` string, required: Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads.
  - `credits_charged` integer, required: The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. If video generation fails, credits will be refunded, and this field will be updated to include the refund.

## Other responses

- `400`: Invalid Request
- `401`: Unauthorized
- `402`: Payment Required
- `404`: Not Found
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-10-14** `e4d79f475b55`: 1 warning, 1 info
  - removed the request property `max_resolution`
  - added the new optional request property `resolution`
- **2026-09-02** `9aeb9397c62a`: 8 info
  - added the non-success response with the status `500`
  - removed the `Not Found` enum value from the `message` response property for the response status `404`
  - removed the `Unauthorized` enum value from the `message` response property for the response status `401`
  - added the required property `code` to the response with the `400` status
  - …4 more
- **2026-03-06** `1f72d520ddc6`: 1 info
  - added the non-success response with the status `402`
- **2026-01-26** `063ea5461786`: 1 warning, 4 info
  - removed the request property `style/intensity`
  - added the new optional request property `style/prompt`
  - the `generation_mode` request property default value changed from `pro` to `realistic`
  - added the new `prompted` enum value to the request property `style/generation_mode`
  - …1 more
- **2026-01-24** `a342af4ecbcf`: 1 breaking
  - removed the required property `estimated_frame_cost` from the response with the `200` status

[Operation history](https://skmtc.dev/magichourhq/apis/magic-hour-api/changes/v1/ai-talking-photo/post.md)

---

[API](https://skmtc.dev/magichourhq/apis/magic-hour-api.md) - [All operations](https://skmtc.dev/magichourhq/apis/magic-hour-api/llms.txt) - [OpenAPI document](https://skmtc.dev/magichourhq/apis/magic-hour-api/revisions/2ee5927306a9?raw)