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

<img className="w-full h-44 object-cover rounded-xl" src="https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-8.webp?fit=max&auto=format&n=hfMXXwJzjE7vBSYZ&q=85&s=d16cda8ab7835eed66c6a205d16e631f" alt="" noZoom width="1400" height="788" data-path="images/theme/research-8.webp" />

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.

<Steps>
  <Step title="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`](/docs/upload-assets), or base64 content. Add `avatar_group_id` to attach the twin to a character you already have.

    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.
  </Step>

  <Step title="Wait for training">
    Poll [`GET /v3/avatars/looks/{look_id}`](/reference/get-avatar-look) until `status` leaves `processing`.

    ```bash theme={null}
    curl -X GET "https://api.heygen.com/v3/avatars/looks/$LOOK_ID" \
      -H "X-Api-Key: $HEYGEN_API_KEY"
    ```

    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`.
  </Step>

  <Step title="Collect consent">
    [`POST /v3/avatars/{group_id}/consent`](/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.

    [Avatar Consent](/docs/avatar-consent) has the three levels of access and the full flow.
  </Step>

  <Step title="Render">
    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",
        "voice_id": "voice_cloned123",
        "script": "Thanks for joining today. Here is what shipped this week."
      }'
    ```

    The [Digital Twin](/generate-avatar-video) recipe walks the render end to end, and [Models](/models) compares the engines a twin supports.
  </Step>
</Steps>

## Footage that trains well

| Attribute       | Target                                           |
| --------------- | ------------------------------------------------ |
| Duration        | 15 to 600 seconds                                |
| People in frame | One, facing camera for the whole recording       |
| Audio           | Clear, audible speech throughout                 |
| Framing         | The face stays in frame from first frame to last |

Longer footage with varied natural speech gives the model more to learn from.

## The cloned voice

<Info>
  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.
</Info>

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}`](/reference/update-avatar-group). Any voice in your workspace works, including [imported clones](/docs/voices/instant-voice-clone).

To give the same person more outfits and settings, generate looks from [a prompt](/docs/avatar-from-prompt) or a [Look Pack](/docs/avatar-look-packs).