> ## 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.

# Digital Twin

> Generate AI avatar video from a script with the HeyGen API. Pick an avatar, voice, and background; HeyGen handles rendering, captions, and final export.

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

## Prerequisites

> [!TIP]
>
> A Digital Twin `avatar_id` (type: `digital_twin`). Use `GET /v3/avatars/looks?avatar_type=digital_twin` to find yours.

> [!TIP]
>
> A `voice_id` for the voice you want. Use `GET /v3/models/audio/voices` to browse voices.

## Step 1 — Find your Digital Twin

List your private Digital Twin looks to get the `avatar_id`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/avatars/looks?avatar_type=digital_twin&ownership=private" \
  -H "x-api-key: YOUR_API_KEY"
```

From the response, copy the `id` field of the look you want. This is your `avatar_id`.

## Step 2 — Choose a rendering engine

HeyGen v3 supports four rendering engines for Digital Twins. You select the engine via the `engine` object in your video creation request. Start with [Avatar 6](https://heygen-1fa696a7.mintlify.site/docs/models/avatar-6.md).

| Engine | Key | Default? | Quality |
| - | - | - | - |
| Avatar 6 | `heygen-avatar-6`, `heygen-avatar-6-turbo` | No, set it explicitly | Newest engine, up to 2K, `motion_prompt` and `engine.motion_expressiveness` |
| Avatar IV | `avatar_iv` | Yes — used when `engine` is omitted | Standard, widely supported |
| Avatar V | `avatar_v` | No — must be explicitly requested | Higher quality, cross-reference-driven animation |
| Avatar III | `avatar_iii` | No — must be explicitly requested | Dedicated photo-to-video pipeline |

> [!NOTE]
>
> Before requesting an engine, check the `supported_api_engines` array on the avatar look via `GET /v3/avatars/looks/{look_id}` — it lists which of `heygen-avatar-6`, `heygen-avatar-6-turbo`, `avatar_iii`, `avatar_iv`, and `avatar_v` the look accepts, and requesting an engine that isn't listed will be rejected. See [Models](https://heygen-1fa696a7.mintlify.site/models) for full details on each engine.

## Step 3 — Create the video

Send a `POST` request to `/v3/videos` with `type: "avatar"`, your Digital Twin ID, a script, and a voice.

A `type: "avatar"` request renders one scene, so its script or audio must stay within **30 minutes**. For a longer piece, compose it as a [studio video](https://heygen-1fa696a7.mintlify.site/studio-videos.md) with several scenes — see [Usage Limits](https://heygen-1fa696a7.mintlify.site/docs/usage-limits.md#output-video-specifications).

### Using Avatar 6 (recommended)

Pass `{"type": "heygen-avatar-6"}` in the `engine` field. Direct the delivery with `motion_prompt`, and set `engine.motion_expressiveness` to `less` for calmer gestures:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_DIGITAL_TWIN_LOOK_ID",
    "script": "Hello! I am your Digital Twin. This video was generated entirely through the HeyGen API.",
    "voice_id": "YOUR_VOICE_ID",
    "title": "My First Digital Twin Video",
    "engine": { "type": "heygen-avatar-6" },
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "motion_prompt": "Smile warmly and use small, open-handed gestures while speaking."
  }'
```

Use `heygen-avatar-6-turbo` for the same inputs on the faster variant, and `"resolution": "2k"` for 2K output. The [Avatar 6 guide](https://heygen-1fa696a7.mintlify.site/docs/models/avatar-6.md#application-api) lists every field.

For Avatar IV, omit `engine` (it is the default) or pass `{"type": "avatar_iv"}`. For Avatar V and its cross-reference-driven animation, pass `{"type": "avatar_v"}`. The rest of the request stays the same.

> [!NOTE]
>
> For digital twins, `motion_prompt` works with Avatar 6 and Avatar V. Avatar IV rejects it.
>
> On Avatar 6, set `engine.motion_expressiveness` to `default` or `less`. The top-level `expressiveness` field works only for photo avatars and images on Avatar IV.

## Step 4 — Poll for completion

Generation is asynchronous. Poll [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) until `status` is `completed` (or `failed`, with `failure_code` and `failure_message`), or skip polling with a [webhook](#using-webhooks-instead-of-polling). A completed video carries `video_url`, `thumbnail_url`, `gif_url`, and `duration`, plus `captioned_video_url` and `subtitle_url` when you request [captions](#captions-and-subtitles). These are presigned URLs with a limited expiry window: download promptly, or fetch the video again for fresh URLs.

## Other parameters

Every other field, such as `title`, `background`, `voice_settings`, and `callback_url`, is in the [Create Video reference](https://heygen-1fa696a7.mintlify.site/reference/create-video.md). Worth knowing: `resolution` takes `2k` on Avatar 6 and `4k` on Avatar III; `aspect_ratio: "auto"` matches the source and falls back to `16:9`; `remove_background` works by default on new digital twins; `output_format: "webm"` returns a [transparent background](https://heygen-1fa696a7.mintlify.site/transparent-background-videos.md).

## Captions and subtitles

Captions are off by default — omit `caption` and `video_url` is a clean render with no subtitles. To generate captions, pass a `caption` object:

```json theme={null}
{
  "caption": { "file_format": "srt" }
}
```

This returns a sidecar subtitle file via `subtitle_url` in the status response, while `video_url` stays clean. To also burn captions into a second render at `captioned_video_url`, add `"style": "default"` to the `caption` object.

> [!NOTE]
>
> `caption` is an object on `/v3/videos`. Boolean-style fields like `caption: true` or `enable_caption` (used by the v2 API and by the [template endpoint](https://heygen-1fa696a7.mintlify.site/templates.md)) fail `/v3/videos` validation with `invalid_parameter` ("Extra inputs are not permitted"). Use the object form above.

If a downloaded video shows captions you didn't ask for, you most likely grabbed `captioned_video_url` (or the `url` from a webhook payload that points at the captioned render). Fetch [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) and download `video_url` for the caption-free file.

## Using webhooks instead of polling

Pass a `callback_url` when creating the video and HeyGen sends a POST to that URL when the video completes or fails. For production, register an endpoint via `POST /v3/webhooks/endpoints` and subscribe to `avatar_video.success` and `avatar_video.fail`.


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