> ## 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 Reference - Magic Hour Docs > Create a talking photo from an image and audio or text input. ## OpenAPI ````yaml post /v1/ai-talking-photo openapi: 3.0.2 info: title: Magic Hour API version: beta description: > Magic Hour provides an API (beta) that can be integrated into your own application to generate videos and images using AI. Webhook documentation can be found [here](https://magichour.ai/docs/webhook). If you have any questions, please reach out to us via [discord](https://discord.gg/JX5rgsZaJp). # Authentication Every request requires an API key. To get started, first generate your API key [here](https://magichour.ai/settings/developer). Then, add the `Authorization` header to the request. | Key | Value | |-|-| | Authorization | Bearer mhk_live_apikey | > **Warning**: any API call that renders a video will utilize credits in your account. termsOfService: https://magichour.ai/terms-of-service servers: - url: https://api.magichour.ai security: [] tags: - name: Files description: API related to uploading assets used for video generation - name: Image Projects description: API related to image projects - name: Video Projects description: API related to video projects - name: Audio Projects description: API related to audio projects paths: /v1/ai-talking-photo: post: tags: - Video Projects summary: AI Talking Photo description: Create a talking photo from an image and audio or text input. operationId: aiTalkingPhoto.createTalkingPhoto parameters: [] requestBody: required: true description: Body content: application/json: schema: type: object properties: name: type: string description: Give your image a custom name for easy identification. example: My Talking Photo image default: Talking Photo - dateTime start_seconds: type: number minimum: 0 description: >- The start time of the input audio in seconds. The maximum duration allowed is 60 seconds. format: float example: 0 end_seconds: type: number minimum: 0.1 description: >- The end time of the input audio in seconds. The maximum duration allowed is 60 seconds. format: float example: 15 assets: type: object properties: image_file_path: type: string minLength: 1 description: > The source image to animate. This value is either - a direct URL to the video file - `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. example: api-assets/id/1234.png audio_file_path: type: string minLength: 1 description: > The audio file to sync with the image. This value is either - a direct URL to the video file - `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. example: api-assets/id/1234.mp3 required: - image_file_path - audio_file_path description: Provide the assets for creating a talking photo style: type: object properties: generation_mode: default: realistic type: string enum: - realistic - prompted - pro - standard - stable - expressive description: >- 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` example: realistic prompt: type: string description: >- A text prompt to guide the generation. Only applicable when generation_mode is `prompted`. This field is ignored for other modes. description: Attributes used to dictate the style of the output max_resolution: type: integer description: >- Constrains the larger dimension (height or width) of the output video. Allows you to set a lower resolution than your plan's maximum if desired. The value is capped by your plan's max resolution. example: 1024 required: - start_seconds - end_seconds - assets description: Provide the assets for creating a talking photo responses: '200': description: Success content: application/json: schema: type: object properties: id: type: string example: cuid-example description: >- 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: type: integer description: >- 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. example: 450 required: - id - estimated_frame_cost - credits_charged description: Success '400': description: Invalid Request content: application/json: schema: type: object properties: message: type: string required: - message description: The request is invalid example: message: Missing request body '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string enum: - Unauthorized required: - message description: The request is not properly authenticated example: message: Unauthorized '402': description: Payment Required content: application/json: schema: type: object properties: message: type: string required: - message description: The request requires payment example: message: Payment required '404': description: Not Found content: application/json: schema: type: object properties: message: type: string enum: - Not Found required: - message description: Requested resource is not found example: message: Not Found '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string example: Unable to create talking photo required: - message description: Unprocessable Entity security: - bearerAuth: [] x-codeSamples: - lang: python source: |- from magic_hour import Client from os import getenv client = Client(token=getenv("API_TOKEN")) res = client.v1.ai_talking_photo.generate( assets={ "audio_file_path": "/path/to/1234.mp3", "image_file_path": "/path/to/1234.png", }, end_seconds=15.0, start_seconds=0.0, name="Talking Photo image", wait_for_completion=True, download_outputs=True, download_directory="." ) - lang: javascript source: |- import { Client } from "magic-hour"; const client = new Client({ token: process.env["API_TOKEN"]!! }); const res = await client.v1.aiTalkingPhoto.generate( { assets: { audioFilePath: "/path/to/1234.mp3", imageFilePath: "/path/to/1234.png", }, endSeconds: 15.0, name: "Talking Photo image", startSeconds: 0.0, }, { waitForCompletion: true, downloadOutputs: true, downloadDirectory: ".", }, ); - lang: go source: "package main\n\nimport (\n\tos \"os\"\n\n\tsdk \"github.com/magichourhq/magic-hour-go/client\"\n\tnullable \"github.com/magichourhq/magic-hour-go/nullable\"\n\tai_talking_photo \"github.com/magichourhq/magic-hour-go/resources/v1/ai_talking_photo\"\n\ttypes \"github.com/magichourhq/magic-hour-go/types\"\n)\n\nfunc main() {\n\tclient := sdk.NewClient(\n\t\tsdk.WithBearerAuth(os.Getenv(\"API_TOKEN\")),\n\t)\n\tres, err := client.V1.AiTalkingPhoto.Create(ai_talking_photo.CreateRequest{\n\t\tAssets: types.V1AiTalkingPhotoCreateBodyAssets{\n\t\t\tAudioFilePath: \"api-assets/id/1234.mp3\",\n\t\t\tImageFilePath: \"api-assets/id/1234.png\",\n\t\t},\n\t\tEndSeconds: 15.0,\n\t\tMaxResolution: nullable.NewValue(1024),\n\t\tName: nullable.NewValue(\"My Talking Photo image\"),\n\t\tStartSeconds: 0.0,\n\t})\n}" - lang: rust source: |- let client = magic_hour::Client::default() .with_bearer_auth(&std::env::var("API_TOKEN").unwrap()); let res = client .v1() .ai_talking_photo() .create(magic_hour::resources::v1::ai_talking_photo::CreateRequest { assets: magic_hour::models::V1AiTalkingPhotoCreateBodyAssets { audio_file_path: "api-assets/id/1234.mp3".to_string(), image_file_path: "api-assets/id/1234.png".to_string(), }, end_seconds: 15.0, max_resolution: Some(1024), name: Some("My Talking Photo image".to_string()), start_seconds: 0.0, ..Default::default() }) .await; - lang: curl source: |- curl --request POST \ --url https://api.magichour.ai/v1/ai-talking-photo \ --header 'accept: application/json' \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --data ' { "name": "My Talking Photo image", "start_seconds": 0, "end_seconds": 15, "assets": { "image_file_path": "api-assets/id/1234.png", "audio_file_path": "api-assets/id/1234.mp3" }, "style": { "generation_mode": "realistic", "prompt": "string" }, "max_resolution": 1024 } ' - lang: php source: |- "https://api.magichour.ai/v1/ai-talking-photo", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => json_encode([ 'name' => 'My Talking Photo image', 'start_seconds' => 0, 'end_seconds' => 15, 'assets' => [ 'image_file_path' => 'api-assets/id/1234.png', 'audio_file_path' => 'api-assets/id/1234.mp3' ], 'style' => [ 'generation_mode' => 'realistic', 'prompt' => 'string' ], 'max_resolution' => 1024 ]), CURLOPT_HTTPHEADER => [ "accept: application/json", "authorization: Bearer ", "content-type: application/json" ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } - lang: java source: >- HttpResponse response = Unirest.post("https://api.magichour.ai/v1/ai-talking-photo") .header("accept", "application/json") .header("content-type", "application/json") .header("authorization", "Bearer ") .body("{\"name\":\"My Talking Photo image\",\"start_seconds\":0,\"end_seconds\":15,\"assets\":{\"image_file_path\":\"api-assets/id/1234.png\",\"audio_file_path\":\"api-assets/id/1234.mp3\"},\"style\":{\"generation_mode\":\"realistic\",\"prompt\":\"string\"},\"max_resolution\":1024}") .asString(); components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your API key. To get your API key, go to [Developer Hub](https://magichour.ai/developer?tab=api-keys) and click "Create new API Key". ````