Documentation

Create Transparent Avatar Videos in WebM Format

Suggest Edits

Generates a WebM video with a transparent background and an avatar speaking the input text. You can customize the avatar's pose, style, and voice, as well as the dimensions of the video.

This API endpoint does not support custom avatars. It only supports HeyGen's studio avatars.

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": "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/v2/voices \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: <your-api-key>'

{
  "error": null,
  "data": {
    "voices": [
			{
        "voice_id": "1bd001e7e50f421d891986aad5158bc8",
        "language": "English",
        "gender": "Female",
        "name": "Sara - Cheerful",
        "preview_audio": "https://static.heygen.ai/voice_preview/func8CFnfVLKF2VzGDCDCR.wav",
        "support_pause": true,
        "emotion_support": false
      },
      ...
    ]
  }
}

Assuming you've selected an avatar and a voice, let's proceed to generate your video.

2. Generate WebM Video

See detailed API reference
To create your avatar video, make a POST request using the following API:

curl -L 'https://api.heygen.com/v1/video.webm' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <your-api-key>' \
-d '{
  "avatar_pose_id": "Zoey-insuit-20220816",
  "avatar_style": "normal",
  "input_text": "This is a WebM video generated by HeyGen API.",
  "voice_id": "1bd001e7e50f421d891986aad5158bc8"
}'

{
  "error": null,
  "data": {
    "video_id": "<video_id>"
  }
}

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.

Conclusion

In this step-by-step guide, you've learned how to generate transparent avatar videos using the HeyGen API.

Updated 5 months ago