> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Audio to Video

> Bring your own audio — a voice memo, a podcast segment, a dubbed track — and lip-sync it onto your avatar, digital twin, or any image with one HeyGen API call.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-8.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=d16cda8ab7835eed66c6a205d16e631f)

## 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`](https://heygen-1fa696a7.mintlify.site/reference/create-video) 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:

| `type` | Subject | You provide |
| - | - | - |
| `avatar` | An avatar you already have — digital twin, studio avatar, or photo avatar look | `avatar_id` |
| `image` | Any single-person image, animated on the fly | `image` (URL, asset ID, or base64) |

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:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_AVATAR_ID",
    "engine": { "type": "heygen-avatar-6" },
    "audio_url": "https://example.com/narration.mp3",
    "title": "Audio to video — narration",
    "aspect_ratio": "auto",
    "resolution": "1080p"
  }'
```

Generation is asynchronous. Poll [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) until `status` is `completed`, then download `video_url` — or pass a `callback_url` to receive a [webhook](https://heygen-1fa696a7.mintlify.site/docs/webhooks.md) instead.

## Audio Sources

Provide exactly one audio source per request — audio fields are mutually exclusive with `script`:

| Field | What it takes |
| - | - |
| `audio_url` | Public HTTPS URL of an audio file. |
| `audio_asset_id` | Asset ID of an uploaded audio file (MP3 or WAV, max 32 MB) — from [`POST /v3/assets`](https://heygen-1fa696a7.mintlify.site/reference/upload-asset). |

> [!NOTE]
>
> 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](https://heygen-1fa696a7.mintlify.site/studio-videos.md) to get a single output. See [Usage Limits](https://heygen-1fa696a7.mintlify.site/docs/usage-limits.md#output-video-specifications).

> [!TIP]
>
> Have text and a voice instead of a recording? Pass `script` + `voice_id` directly, or synthesize audio first with [Text to Speech](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md) ([`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech)) 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](https://heygen-1fa696a7.mintlify.site/generate-avatar-video.md) trained from real footage, a studio avatar, or a [photo avatar](https://heygen-1fa696a7.mintlify.site/photo-avatar.md) look.

```json theme={null}
{
  "type": "avatar",
  "avatar_id": "YOUR_AVATAR_ID",
  "engine": { "type": "heygen-avatar-6" },
  "audio_asset_id": "YOUR_AUDIO_ASSET_ID",
  "background": { "type": "color", "value": "#0b1220" }
}
```

Browse looks with [`GET /v3/avatars/looks`](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-looks). Pass `{ "type": "heygen-avatar-6" }` as `engine` for [Avatar 6](https://heygen-1fa696a7.mintlify.site/docs/models/avatar-6.md) on eligible looks (check `supported_api_engines` on the look), `{ "type": "avatar_v" }` for [Avatar V](https://heygen-1fa696a7.mintlify.site/avatar-v.md), or omit `engine` for [Avatar IV](https://heygen-1fa696a7.mintlify.site/avatar-iv.md). `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](https://heygen-1fa696a7.mintlify.site/transparent-background-videos.md).

## 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](https://heygen-1fa696a7.mintlify.site/image-to-video.md) with your own soundtrack.

```json theme={null}
{
  "type": "image",
  "image": { "type": "asset_id", "asset_id": "YOUR_IMAGE_ASSET_ID" },
  "audio_url": "https://example.com/narration.mp3"
}
```

`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](https://heygen-1fa696a7.mintlify.site/reference/create-video.md): `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.