Skip to main content

Overview

Audio to Video turns a recorded audio track into a talking video: you supply the audio, pick who says it, and HeyGen handles the delivery and render. It’s the same POST /v3/videos endpoint used for script-driven videos — the difference is that you pass audio_url (or audio_asset_id) instead of script, and the video’s length follows your audio, up to 30 minutes. Two subject choices, both accepting the same audio fields: Use it when the voice already exists: preserving a real person’s recorded voice on their digital twin, dubbing localized audio onto one presenter, or lip-syncing audio produced by another tool.

Quick Example

Lip-sync an audio file onto an avatar:
Generation is asynchronous. Poll GET /v3/videos/{video_id} until status is completed, then download video_url — or pass a callback_url to receive a webhook instead.

Audio Sources

Provide exactly one audio source per request — audio fields are mutually exclusive with script:
One request renders up to 30 minutes of audio. For a longer recording, split it into segments of 30 minutes or less and send one per request — or compose them as scenes of a studio video to get a single output. See Usage Limits.
Have text and a voice instead of a recording? Pass script + voice_id directly, or synthesize audio first with Text to Speech (POST /v3/models/audio/tts) and pass its audio_url here, which lets you reuse the same narration across several videos.

With an Avatar or Digital Twin

"type": "avatar" works with any avatar ID you own — a digital twin trained from real footage, a studio avatar, or a photo avatar look.
Browse looks with GET /v3/avatars/looks. Pass { "type": "heygen-avatar-6" } as engine for Avatar 6 on eligible looks (check supported_api_engines on the look), { "type": "avatar_v" } for Avatar V, or omit engine for Avatar IV. motion_prompt works on photo and video avatars with Avatar 6 and Avatar V, and on photo avatars with Avatar IV. expressiveness (default low) applies to photo avatars on Avatar IV; on Avatar 6, set engine.motion_expressiveness to default or less. remove_background needs a video avatar trained with matting, and output_format: "webm" gives a transparent background.

With an Image

"type": "image" animates any single-person image with lip-sync to your audio — no avatar creation step. It’s Image to Video with your own soundtrack.
image takes { "type": "url", "url": "..." }, { "type": "asset_id", "asset_id": "..." }, or { "type": "base64", "media_type": "image/png", "data": "..." }, and accepts motion_prompt and expressiveness (default low).

Output Settings

Both subject types share the output controls in the Create Video reference: title, aspect_ratio (default 16:9; auto preserves the source and is recommended), resolution, fit (cover fills and may crop, contain fits and may show background), caption, callback_url, and callback_id. A caption object returns a sidecar file via subtitle_url; add "style": "default" to also burn captions in.