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.

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

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

2. Wait for training

   Poll GET /v3/avatars/looks/{look_id} until status leaves processing.

   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.

3. Collect consent

   POST /v3/avatars/{group_id}/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 has the three levels of access and the full flow.

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

   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 recipe walks the render end to end, and Models compares the engines a twin supports.

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

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.

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}. Any voice in your workspace works, including imported clones.

To give the same person more outfits and settings, generate looks from a prompt or a Look Pack.