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

# Video to Avatar

> Train a digital twin from video footage of a person with POST /v3/avatars. Covers footage that trains well, the voice cloned alongside it, consent, and polling to completed.

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

A **digital twin** is trained from footage of a real person, and clones a voice from the same recording so the twin speaks in the subject's own voice.

**1. Create the twin**

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/avatars" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "digital_twin",
    "name": "Sarah",
    "file": { "type": "url", "url": "https://example.com/sarah-footage.mp4" }
  }'
```

`file` also takes `{ "type": "asset_id", "asset_id": "..." }` from [`POST /v3/assets`](https://heygen-1fa696a7.mintlify.site/docs/upload-assets), or base64 content.

`avatar_group_id` decides which character the twin belongs to:

* **Pass an existing `avatar_group_id`** to add the twin as another look of a character you already have. Only do this for the same person, since consent is tracked per group.
* **Leave it out** to create a new avatar group (a new character) for this person. The new group id is returned as `avatar_group.id`.

> [!NOTE]
>
> A `url` input is fetched when you call the endpoint and is capped at 32 MB, the same as [`POST /v3/assets`](https://heygen-1fa696a7.mintlify.site/docs/upload-assets). Signed or presigned HTTPS URLs work as long as they are reachable at that moment, but they do not raise the cap. Base64 input is capped at 16 MB after decoding. For recommended footage (about 2 minutes at 1080p), use [direct upload](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md), then pass `{ "type": "asset_id", "asset_id": "asset_abc123" }`. An `asset_id` stays usable until you delete it, so reuse the same one if you retry creation.

Keep two values from the response: `avatar_item.id` is the `avatar_id` you render with, and `avatar_group.id` is what the consent flow acts on. Store the group id per person, since it is also the `avatar_group_id` you pass to add more looks of them later.

**2. Wait for training**

Poll [`GET /v3/avatars/looks/{look_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-avatar-look) until `status` leaves `processing`; training usually completes within a few minutes. To be notified instead of polling, subscribe a [webhook endpoint](https://heygen-1fa696a7.mintlify.site/docs/webhooks.md) to the `instant_avatar.success` and `instant_avatar.fail` [events](https://heygen-1fa696a7.mintlify.site/docs/webhook-events.md).

A `failed` look carries an `error` object: `training_failed` when the footage could not be trained, `moderation_failed` when it did not pass content review. The reason is in `error.message`.

**3. Collect consent**

[`POST /v3/avatars/{group_id}/consent`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar-consent) returns a link, valid for 24 hours, that the subject opens to record a short statement on camera. Enterprise workspaces can upload a pre-recorded consent video or have the step waived.

An uploaded consent video must be under 35 seconds and show the same person as the footage. Record it as its own short clip, separate from the training footage. [Avatar Consent](https://heygen-1fa696a7.mintlify.site/docs/avatar-consent.md) has [what it must contain](https://heygen-1fa696a7.mintlify.site/docs/avatar-consent.md#what-the-consent-video-must-contain), the three levels of access and the full flow.

**4. Render**

Render once the look reports `status: "completed"` and the group has cleared consent. No other publish step is needed.

Pass the look id as `avatar_id`. Omitting `voice_id` falls back to the character's default voice, which is the group's linked voice when the twin joined an existing group. Pass `avatar_item.default_voice_id` from the create response to speak in the voice cloned from this footage.

```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": "look_abc123",
    "engine": { "type": "heygen-avatar-6" },
    "voice_id": "voice_cloned123",
    "script": "Thanks for joining today. Here is what shipped this week."
  }'
```

The [Digital Twin](https://heygen-1fa696a7.mintlify.site/generate-avatar-video.md) recipe walks the render end to end, and [Models](https://heygen-1fa696a7.mintlify.site/models) compares the engines a twin supports.

## Footage that trains well

| Attribute | Requirement | Recommended |
| - | - | - |
| Duration | 15 to 600 seconds | About 2 minutes of natural talking |
| Resolution | Long edge at least 640 px, at most 4096 px (4K) | 1080p |
| Format | mp4 or webm | mp4 |
| People in frame | One, facing camera for the whole recording | |
| Audio | Clear, audible speech throughout | Quiet room, no background music |
| Framing | The face stays in frame from first frame to last | |

Longer footage with varied natural speech gives the model more to learn from. About 2 minutes at 1080p gives the best twin quality.

A clip like that is usually larger than 32 MB, so upload it with [direct upload](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md), which accepts video files up to 200 MB, and pass the `asset_id`. If your recording is over 200 MB, export it at a lower bitrate before uploading.

## The cloned voice

> [!NOTE]
>
> Creating a digital twin clones one voice from the training footage automatically. There is no separate voice request and no opt-in step. The id is returned immediately as `avatar_item.default_voice_id`, while the avatar and the voice finish processing.
>
> The cloned voice is its own resource. Deleting the twin's look or group does not delete it; remove it with [`DELETE /v3/models/audio/voices/{voice_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-an-audio-voice).

Two voice ids travel with a twin and they can differ. `avatar_item.default_voice_id` is the voice cloned from this request's footage. `avatar_group.default_voice_id` is the effective voice for the character: a linked group voice takes precedence, falling back to the new look's clone.

Set the character's voice deliberately by sending `default_voice_id` to [`PATCH /v3/avatars/{group_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-avatar-group). Any voice in your workspace works, including [cloned voices](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-instant-clone.md).

To give the same person more outfits and settings, generate looks from [a prompt](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-prompt.md) or a [Look Pack](https://heygen-1fa696a7.mintlify.site/docs/avatar-look-packs.md).


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