Create Avatar Videos
This API now generates videos with our New AI Studio backend.
Create personalized avatar videos with ease using the HeyGen API. 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. Whether you need videos for education, entertainment, or marketing, the HeyGen API makes it simple and efficient.
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 Avatars and List Voices API endpoints.
List Avatars
See detailed API reference
Use this 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.
curl --request GET \
--url https://api.heygen.com/v2/avatars \
--header 'Accept: application/json' \
--header 'X-Api-Key: <your-api-key>'
{
"error": null,
"data": {
"avatars": [
{
"avatar_id": "<avatar_id>",
"avatar_name": "My Instant Avatar",
"gender": "male",
"preview_image_url": "<preview_image_url>",
"preview_video_url": "<preview_video_url>"
},
{
"avatar_id": "Angela-inblackskirt-20220820",
"avatar_name": "Angela in Black Dress",
"gender": "female",
"preview_image_url": "<preview_image_url>",
"preview_video_url": "<preview_video_url>"
},
]
}
}
List Voices
See detailed API reference
This 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.
curl --request GET \
--url https://api.heygen.com/v1/voice.list \
--header 'Accept: application/json' \
--header 'X-Api-Key: <your-api-key>'
{
"code": 100,
"data": {
"list": [
{
"voice_id": "76955c80188a4c149df169b5dc9e1a3a",
"labels": ["Youth", "Explainer", "E-learning", "Audiobooks"],
"language": "English",
"flag": "https://static.movio.la/region_flags/us.png",
"locale": "en-US",
"sort": 12,
"gender": "Female",
"tags": "Young Adult, Assistant",
"display_name": "Emma - Newscaster",
"preview": {
"movio": "https://static.movio.la/voice_preview/c3NuQJ7QnFRXFq8Kn4quwk.wav"
},
"settings": {
"style": "assistant",
"elevenlabs_settings": null
},
"ssml": {
"style": [],
"lang": [],
"break": true,
"prosody": ["rate", "pitch"],
"emphasis": "none",
"say_as": []
},
"is_customer": false,
"is_favorite": false,
"is_paid": false,
"support_realtime": true
}
]
},
"msg": null,
"message": null
}
Assuming you've selected an avatar and a voice, let's proceed to generate your video.
2. Generate Video
See detailed API reference
To create your avatar video, make a POST request using the following API:
curl -X POST https://api.heygen.com/v2/video/generate \
-H 'X-Api-Key: <your-api-key>' \
-H 'Content-Type: application/json' \
-d '{
"video_inputs": [
{
"character": {
"type": "avatar",
"avatar_id": "Angela-inTshirt-20220820",
"avatar_style": "normal"
},
"voice": {
"type": "text",
"input_text": "Welcome to the HeyGen API!",
"voice_id": "1bd001e7e50f421d891986aad5158bc8",
"speed": 1.1
}
}
],
"dimension": {
"width": 1280,
"height": 720
}
}'
{
"error": null,
"data": {
"video_id": "<video_id>"
}
}
Text input should be less than 1500 characters. Here is the limit details.
You can adjust voice attributes such as
speed
andpitch
. Here is the references.
If you are on the free API plan, the export resolution limit 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
See detailed API reference
After creating your video, you can check its status. Wait until the video's status changes to completed.
curl --request GET \
--url https://api.heygen.com/v1/video_status.get?video_id=<video_id> \
--header 'Accept: application/json' \
--header 'X-Api-Key: <your-api-key>'
{
"code": 100,
"data": {
"callback_id": null,
"caption_url": "<caption_url>",
"duration": 1.234,
"error": null,
"gif_url": "<gif_url>",
"id": "<id>",
"status": "completed",
"thumbnail_url": "<thumbnail_url>",
"video_url": "<video_url>",
"video_url_caption": null
},
"message": "Success"
}
{
"code": 100,
"data": {
"callback_id": null,
"caption_url": null,
"duration": null,
"error": null,
"gif_url": null,
"id": "<id>",
"status": "processing",
"thumbnail_url": null,
"video_url": null,
"video_url_caption": null
},
"message": "Success"
}
{
"code": 100,
"data": {
"callback_id": null,
"caption_url": null,
"duration": null,
"error": null,
"gif_url": null,
"id": "<id>",
"status": "pending",
"thumbnail_url": null,
"video_url": null,
"video_url_caption": null
},
"message": "Success"
}
{
"code": 100,
"data": {
"callback_id": null,
"caption_url": null,
"duration": null,
"error": {
"code": 40119,
"detail": "Video is too long (> 3600.0s). Please upgrade your plan to generate longer videos",
"message": "Video is too long"
},
"gif_url": null,
"id": "<id>",
"status": "failed",
"thumbnail_url": null,
"video_url": null,
"video_url_caption": null
},
"message": "Success"
}
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, the
Expires
and other queries are regenerated accordingly.
Download the video
Congratulations! You've successfully generated your avatar video. Download and enjoy your creation. 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:
- Create Personalized Avatars with Photos
- Customize Video Background
- Using Audio Source as Voice
- Create Videos with Your Personal Avatar and Voice
Conclusion
In this step-by-step guide, you've learned how to generate avatar videos using the HeyGen API. By selecting an avatar and a voice, you can create engaging videos for various purposes. Keep experimenting and create amazing content!
Updated 22 days ago