# Generate Video from Template

Create and customize Videos using HeyGen's Template V3 API

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:

1. Create a Template in HeyGen interface and add variable placeholders.
2. Retrieve the template using the [Retrieve Template Details (V3)](https://movio-api.readme.io/reference/get-template-v3) API to access its details and variables.
3. Set variable values dynamically in your API request to personalize content for each video.
4. Generate the final video through the [Generate Video from Template](https://movio-api.readme.io/reference/generate-from-template-v2)  API.

## Creating Template through the Interface

<Callout icon="ℹ️" theme="info">
  Template creation is currently supported only through the HeyGen <Anchor label="Interface" target="_blank" href="https://app.heygen.com/templates">Interface</Anchor>.
</Callout>

To create a new template:

1. Go to the HeyGen Dashboard and open the [Templates](https://app.heygen.com/templates) tab.
2. Click **Create Template**. This opens the template editor.
3. Insert a placeholder variable using double curly brackets `{{}}`.

> For more details on creating and managing templates, see <Anchor label="Create Templates" target="_blank" href="https://help.heygen.com/en/articles/10344284-personalized-video-step-one-creating-a-template">Create Templates</Anchor>.

<Image align="center" border={false} src="https://files.readme.io/8f113677d641ebfffcc4cd8118c6dd43ddcbbfafa78f1485d4b9359ee035206e-image.png" />

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.

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

```json Response
{
  "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](https://movio-api.readme.io/reference/list-templates-v2)

## 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.

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

```json Response
{
  "error": null,
  "data": {
    "variables": {
      "name": {
        "name": "name",
        "type": "text",
        "properties": {
          "content": ""
        }
      }
    },
    "scenes": [
      {
        "id": "<scene_id>",
        "script": "",
        "variables": {
          "name": "name"
        }
      }
    ]
  }
}

```

For more details on response fields, see detailed API Reference: [Retrieve Template Details (V3)](https://movio-api.readme.io/reference/get-template-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.

```bash Request
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"
      }
    }
  }
}'
```

```json Response
{
  "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](https://movio-api.readme.io/reference/generate-from-template-v2)

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](https://movio-api.readme.io/reference/video-status) 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, the`Expires` and other queries are regenerated accordingly.*

Here is the result:

<Embed url="https://app.heygen.com/embeds/7cba9d29d6db46b88471221fdbc4fb75" href="https://app.heygen.com/embeds/7cba9d29d6db46b88471221fdbc4fb75" typeOfEmbed="iframe" height="450px" width="100%" iframe="true" html="false" />

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

* 🖼️ [Replace Image in Template](https://movio-api.readme.io/docs/replace-image-in-template-1)
* 🎥 [Replace Video in Template](https://movio-api.readme.io/docs/replace-video-in-template-1)
* 👩‍💼 [Replace Avatar in Template](https://movio-api.readme.io/docs/replace-avatar-in-template-1)
* 🗣️ [Replace Text/Voice in Template](https://movio-api.readme.io/docs/replace-textvoice-in-template)
* 🔈 [Replace Audio in Template](https://docs.heygen.com/docs/replace-audio-in-template-1)
* ▶️ [Video Playback Styles in Template](https://movio-api.readme.io/docs/video-playback-styles-in-template-1)

Quick Guides:

* [Simple Python App for Generating Videos from HeyGen Templates](https://movio-api.readme.io/docs/guide-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.

<br />