HeyGen has revolutionized video creation with its AI-powered platform, allowing users to create stunning avatar videos with ease. Now, with the HeyGen API, you can programmatically integrate these powerful AI capabilities into your own products and workflows. This article provides a quick start guide to get you up and running with the HeyGen API, enabling you to create avatar videos like never before.
The HeyGen API unlocks the potential of HeyGen by allowing you to:
Before diving into the API, you need to take a few essential steps:
If you don't already have one, create a HeyGen account. This will grant you access to the HeyGen platform and the initial free trial of the API.
Here's how to quickly create an avatar video using the HeyGen API:
Use the video/generate endpoint: This endpoint is the workhorse for programmatically creating MP4 video files featuring realistic AI avatars. You can find more information on the detailed API reference.
Make a POST request: Send a POST request to the API endpoint with the necessary parameters in JSON format. Here’s an example using curl:
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 }
}'
Understand the Request Parameters:
X-Api-Key: Replace <your-api-key> with the API key you copied from your HeyGen account settings.video_inputs: This array defines the characteristics of your video, including:
character: Specifies the avatar to use.
type: Set to "avatar".avatar_id: The ID of the desired avatar.avatar_style: The style of the avatar ("normal" is a common option).voice: Configures the voiceover.
type: Set to "text" if you're using text-to-speech.input_text: The text the avatar will speak.voice_id: The ID of the voice to use.background: Sets the background of the video.
type: Set to "color" for a solid color background.value: The hexadecimal color code for the background.dimension: Defines the resolution of the video.Process the Response: The API will return a JSON response containing a video_id. This ID is crucial for tracking the status of your video.
{ "error": null, "data": { "video_id": "<video_id>" } }
Instead of input_text, you can use the input_audio attribute to provide a public audio URL for the voiceover.
You can use the Template endpoint to generate similar videos like the one above in bulk. Click here to find out how.
After initiating video creation, you'll need to monitor its status to know when it's ready for download.
Use the video_status.get endpoint: This endpoint allows you to check the status of a video using its video_id. And for more information you can visit API reference.
Make a GET request: Send a GET request to the API endpoint, including the video_id in the query parameters.
curl -X GET 'https://api.heygen.com/v1/video_status.get?video_id=<video_id>' \
-H 'X-Api-Key: <your-api-key>'
Check the status field: The response will include a status field indicating the current state of the video. Possible values include:
pending: The video is queued for processing.processing: The video is currently being generated.completed: The video is ready for download.failed: An error occurred during video generation. Check the error field for details.Once the status is completed, the response will include a video_url that you can use to download your 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
video_url is temporary and expires after 7 days. You can refresh the URL by calling the video status endpoint again.The HeyGen API opens up a world of possibilities for integrating AI-powered avatar videos into your applications and workflows. By following this quick start guide, you can begin exploring the API's potential and creating engaging video content programmatically. For a deeper dive, consult the comprehensive API reference.
