Documentation

Create Avatar Videos

This API now generates videos with our New AI Studio backend.

Suggest Edits

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 and pitch. 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:

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 about 1 month ago