Generate a WebM video with a transparent background and an avatar speaking the input text. You can customize the avatar's pose, style, and voice, as well as the dimensions of the video.

📘

Note: This API endpoint does not support custom avatars. It only supports HeyGen's studio avatars.

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. This API call will provide you with a list of avatars. Choose one avatar from the list and note down its avatar_id for the next steps.

List Voices

The List All Voices (V2) API call will provide you with a list of voices. Choose one 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 WebM Video

To create your avatar video, make a POST request using the Create a WebM Video API.

You can provide one of the following input types:

• Text and voice: Use the input_textand voice_idfields to generate audio automatically.
• Audio file: Use the input_audio field to provide an existing audio asset i.e., an uploaded asset ID. This can be obtained from the response of the Upload Asset API.

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. Wait until the video's status changes to completed. 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).

When the video generation is complete, the status will change to completed, and you will receive the video's URL.

📘

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.

Conclusion

In this step-by-step guide, you've learned how to generate transparent avatar videos using the HeyGen API.