This step-by-step guide will walk you through the process of selecting avatars, voices, and generating captivating videos for a wide range of applications.

1. Get List of Avatars and Voices

To generate an avatar video, you'll need an avatar and a voice. You can fetch a list of available avatars and voices. For this we need to use List All Avatars (V2) and List All Voices (V2) API endpoints.

List Avatars

Use the List All Avatars (V2) API to obtain a list of available avatars, including your instant avatars. Choose an avatar from the list and note down its avatar_id for the next steps.

List Voices

Use the List All Voices (V2) API to get a list of available voices. Choose a voice from the list and note down its voice_id for the next steps.

Assuming you've selected an avatar and a voice, let's proceed to generate your video.

2. Generate Video

To create your avatar video, make a POST request using the Create Avatar Video (V2) API.

📘
Note:

Text input should be less than 5000 characters. Refer to the API Limits and Credit Consumption Costs > Video Avatar Input section for limit details.

Voice attributes such as speed and pitch can be adjusted.

The export resolution limit for the free API Plan is 720p. You can set the resolution with the dimension argument as follows:
  ...
  "dimension": {
    "width": 1280,
    "height": 720
  }
}

You'll receive a video_id in the response. Note down this ID as you will need it to check the video's generation status.

3. Check Video Generation Status

After creating your video, you can check its status through the Retrieve Video Status/Details API.

When the video generation is complete, the status will change to completed, and you will receive the video's URL. 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

pending
The video is queued and waiting to start rendering.

waiting
The video is in waiting state.

processing
The video is currently rendering.

completed
The video has successfully rendered and is ready for download.

failed
The video could not be rendered due to an error (for example, if the duration exceeds plan limits).

📘
The video file URL you get will expire in 7 days. 📆
You can observe this expiration in the URL parameters. Every time you call the video status endpoint, theExpires and other queries are regenerated accordingly.

Download the video

Once you've successfully generated your avatar video, you will be able to download it. Once your video is ready, you can find a link in the response for you to download the video.

curl <video_url> --output output.mp4

For more guides on create video endpoint, explore:

Conclusion

This guide outlined the steps to generate avatar videos using the HeyGen API. By configuring avatar and voice settings, you can programmatically create videos tailored to your specific use case.