Unlike photo avatars, which are generated from images or AI prompts, digital Twin use real training footage to create high-fidelity, lifelike avatars ready for use in video generation.

📘

Note:

These APIs are Enterprise-only and consume API credits. They are intended for organizations that wish to create personalized, studio-quality avatars for corporate or production use.

1. Prepare Your Training Footage and Consent Statement

Before creating a Digital Twin, prepare the following:

• Training Footage (MP4) - A clear, high-quality video of the person speaking. Must be at least 2 minutes long and 720p or higher
• Consent Statement (MP4) - A video that explicitly grants HeyGen permission to use the submitted footage to create the avatar.

Upload both files to a publicly accessible URL (for example, AWS S3, Google Cloud Storage, or another accessible endpoint). You will need to provide these URLs in the API request in the next step.

2. Submit a Digital Twin Creation Request

To create a digital Twin, submit a request providing the training_footage_url,video_consent_urland avatar_name. This request starts the avatar creation process, where HeyGen uses your uploaded footage to generate a personalized video avatar.

For full request and response details, see API reference: Submit Digital Twin Creation Request.

3. Check Digital Twin Generation Status

After submitting the creation request, you can check the progress using the Check Digital Twin Generation Status API. Use the avatar_idreturned from the previous request.

You can view complete status response examples on the right-side Response panel of the API Reference page - open the Examples dropdown to view responses for different video statuses. You can select any example to preview the corresponding response body.

Status Descriptions

in_progress The avatar is currently being processed.

complete
The avatar has been successfully created and is ready for use.

failed
The rendering process failed.

Error messages may include:

• Invalid Training Footage Format
• Object Download Failed

4. Delete a Digital Twin

If you no longer need a Digital Twin, you can remove it using the Delete Digital Twin API.

Best Practices

• Always provide high-quality training footage (well-lit, stable, and with clear speech).
• Keep your consent statement up to date for compliance.
• Use consistent naming conventions for avatar groups (e.g., Enterprise_Creators).