Quick Start
Welcome to the HeyGen API! 🙌
HeyGen API expands what you can do with HeyGen, allowing you to create amazing avatar videos programmatically and integrate HeyGen's powerful AI capabilities into your product. Unleash the potential of HeyGen's AI capabilities! Welcome to the future of video creation – happy AI video making!
Note:
The HeyGen API is now offered independently from the HeyGen App!
Your HeyGen App plan - Free, Creator, Team, or Enterprise - determines which features and limits you can use on the app.heygen.com web app.
Every HeyGen App user now automatically receives Free Trial access to the HeyGen API, including Video Generation, Video Translation, and Interactive Avatar endpoints, and there are three paid subscription tiers available for increased usage: Pro, Scale, and Enterprise.
For more information on pricing and usage, please refer to our limits page.
Prerequisite
Create a HeyGen account
Create a HeyGen account. After you create a HeyGen account, you are able to make professional avatar videos by leveraging HeyGen's powerful AI capabilities.
Access your API key
After you have registered the HeyGen account, proceed to your account settings and scroll down to the API section and copy your API token.
Quickly Create Avatar Video
See detailed API reference
You can use the video/generate endpoint of the HeyGen API to programmatically create mp4 files featuring HeyGen's realistic AI Avatars. In the below example, we create a video in test mode.
While still on a Free Trial of the HeyGen API, your videos will be watermarked.
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": "Daisy-inskirt-20220818",
"avatar_style": "normal"
},
"voice": {
"type": "text",
"input_text": "Welcome to the HeyGen API!",
"voice_id": "2d5b0e6cf36f460aa7fc47e3eee4ba54"
},
"background": {
"type": "color",
"value": "#008000"
}
}
],
"dimension": {
"width": 1280,
"height": 720
}
}'
{
"error": null,
"data": {
"video_id": "<video_id>"
}
}
You will receive a response with the ID of the newly created video. You can also use the input_audio attribute to pass a public audio URL instead of using the input_text attribute.
You can also use the Template endpoint in order to generate similar videos in bulk. Click here to find out how.
Wait for the Video
See detailed API reference
After creating your video, you can check its status. When the video is ready, the status will change to completed.
curl -X GET 'https://api.heygen.com/v1/video_status.get?video_id=<video_id>' \
-H '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"
}
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
Expiresand other queries are regenerated accordingly.
Download the video
Once your video is ready, you can find a link in the response for you to download the video.
curl <video_url> --output first_video.mp4
...
video_status_url = f"https://api.heygen.com/v1/video_status.get?video_id={video_id}"
while True:
response = requests.get(video_status_url, headers=headers)
status = response.json()["data"]["status"]
if status == "completed":
video_url = response.json()["data"]["video_url"]
thumbnail_url = response.json()["data"]["thumbnail_url"]
print(
f"Video generation completed! \nVideo URL: {video_url} \nThumbnail URL: {thumbnail_url}"
)
# Save the video to a file
video_filename = "generated_video.mp4"
with open(video_filename, "wb") as video_file:
video_content = requests.get(video_url).content
video_file.write(video_content)
break
elif status == "processing" or status == "pending":
print("Video is still processing. Checking status...")
time.sleep(5) # Sleep for 5 seconds before checking again
elif status == "failed":
error = response.json()["data"]["error"]
print(f"Video generation failed. '{error}'")
break
Conclusion
For a comprehensive understanding of HeyGen APIs and their capabilities, please review our detailed API reference.
In conclusion, the HeyGen API empowers you to tap into the remarkable AI capabilities of HeyGen for programmatically generating compelling avatar videos. By creating a HeyGen account and using your API Token, you can explore the vast potential of HeyGen's API to infuse creativity into your business, product, or creative project.
Updated 3 days ago