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.

Creating Template through the Interface

To create templates, visit HeyGen Template page and click on Create Template. After that, add a placeholder in your template by using double curly brackets {{}}.

As shown, we've placed a {{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.

📘
Note:
When using your template in the API, certain guidelines must be followed. See Template Guidelines

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 --location '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>"
      },
      ...
    ]
  }
}

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 --location 'https://api.heygen.com/v2/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": ""
        }
      }
    }
  }
}

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

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 Response panel of the API reference page.

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

Template Scene Guidelines

There are certain guidelines to follow when using your template in the API. The new AI Studio allows your script to span multiple scenes. While users can save their templates as desired, to use the template in the API, scripts must be contained within a scene, or scenes must be contained within a script.

📘
Note:
Failure to adhere to these guidelines will result in the "End of scene 1 does not align with script" error.

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. This approach provides a versatile tool for video creation and personalization.