Templates enable you to add and customize existing text, images, videos, audios, voices, and avatars, while avatar videos consist only of avatars without these elements.

Quick Comparison:

Avatar Videos: Avatar videos are centered around avatars delivering content without any additional elements. They are ideal for straightforward, avatar-focused communication.
Template Videos: In contrast, template videos offer a wide canvas for creativity. They enable you to customize existing text, images, videos, audios, voices, and avatars seamlessly. Ideal for personalized campaigns, automated workflows, or branded content.

Quick Start

Let's get started quickly to see how to create a template, add placeholders, and create a new video by dynamically changing these placeholders using the Template API.

How it Works

Creating a video from a template involves the following steps:

Create a Template in HeyGen interface and add variable placeholders.
Retrieve the template using the Retrieve Template Details (V3) API to access its details and variables.
Set variable values dynamically in your API request to personalize content for each video.
Generate the final video through the Generate Video from Template API.

Creating Template through the Interface

ℹ️
Template creation is currently supported only through the HeyGen Interface.

To create a new template:

Go to the HeyGen Dashboard and open the Templates tab.
Click Create Template. This opens the template editor.
Insert a placeholder variable using double curly brackets {{}}.

For more details on creating and managing templates, see Create Templates.

As shown, we've placed a {{first_name}} placeholder within our scene and script. In this tutorial, we'll set a value for this placeholder using the Template API and create a new video.

Get a List of Your Templates

Using the following API request you will get a list of your templates that you have created in the HeyGen interface, obtain your template_id from here.

curl --request GET \
     --url https://api.heygen.com/v2/templates \
     --header 'accept: application/json' \
     --header 'x-api-key: <your-api-key>'

{
  "error": null,
  "data": {
    "templates": [
      {
        "template_id": "<template_id>",
        "name": "<name>",
        "thumbnail_image_url": "<thumbnail_image_url>",
	      "aspect_ratio": "<aspect_ratio"
      },
      ...
    ]
  }
}

For more details on response fields, see detailed API Reference : List Templates

Retrieve Video Elements

To retrieve video elements for a specific template, use the Retrieve Template Details API to get the variable you want to change.

curl --request GET \
     --url https://api.heygen.com/v3/template/template_id \
     --header 'accept: application/json' \
     --header 'x-api-key: <your-api-key>'

{
  "error": null,
  "data": {
    "variables": {
      "name": {
        "name": "name",
        "type": "text",
        "properties": {
          "content": ""
        }
      }
    },
    "scenes": [
      {
        "scene_id": "scene_1",
        "variables": {
          "name": "name"
        }
      }
    ]
  }
}

For more details on response fields, see detailed API Reference: Retrieve Template Details (V3)

Modify Template Elements and Generate Video

To change template elements and generate videos, you will need to submit an API request as follows. In the request body, specify the elements you want to modify by providing the appropriate object within the variables section.

curl --location 'https://api.heygen.com/v2/template/<template_id>/generate' \
     --header 'X-Api-Key: <your-api-key>' \
     --header 'Content-Type: application/json' \
     --data '{
  "caption": false,
  "title": "New Video",
  "variables": {
    "first_name": {
      "name": "first_name",
      "type": "text",
      "properties": {
        "content": "John"
      }
    }
  }
}'

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

If you want to explore all configurable options - including how to update multiple elements or adjust video metadata, see detailed API Reference: Generate Video from Template

You will receive a video_id after your request. To check the video's status and retrieve further details, you can use the Retrieve Video Status/Details API endpoint. You can view complete status response examples on the right-side Response panel of the API Reference page - open the Examples dropdown to view responses for different video statuses. You can select any example to preview the corresponding response body.

Status Descriptions

pending
The video is queued and waiting to start rendering.

waiting
The video is in waiting state.

processing
The video is currently rendering.

completed
The video has successfully rendered and is ready for download.

failed
The video could not be rendered due to an error (for example, if the duration exceeds plan limits).

📘
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, theExpires and other queries are regenerated accordingly.

Here is the result:

Explore the guides below for detailed information on how to modify and customize template content:

Quick Guides:

Simple Python App for Generating Videos from HeyGen Templates

Conclusion

In summary, HeyGen's Template API empowers users to effortlessly generate customized videos from templates. The process begins with creating a template through the web interface. Users can then use this template to generate tailored videos, replacing variables as needed.