Quick Start

Suggest Edits

Welcome to 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! 🤖🚀

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.

Create an API key

After you have registered the HeyGen account, proceed to the account settings and scroll down to the API section and copy your API token.

📘

Note:

The HeyGen API is exclusively available for the Enterprise plan users. To use the HeyGen API, you must be on the Enterprise plan. For trial purposes, you can enable the Trial Token through your account page.

(Optional) Configure Webhooks

You can configure webhook endpoints to listen to events from HeyGen. Simply visit your account page to set up your webhook.

For advanced webhook configuration, explore our webhook API guide.

Create Your First Video

See detailed API reference
We'll create the first video in test mode. Test videos are free and do not count towards your quota. However, they 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
  },
  "aspect_ratio": "16:9",
  "test": true
}'

{
  "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.

Also you can create videos from templates as well. Check here to see 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 Expires and 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, obtaining an API key, and optionally configuring webhooks, you can embark on your video-making journey. Explore the vast potential of HeyGen APIs to infuse creativity into your projects, whether for educational, entertainment, or marketing purposes.

Updated 23 days ago