Template API

Generate a video based on a specified template, including scene IDs and dynamic variable replacements.

Legacy Endpoint — This is a legacy endpoint that supports template-based video generation with scene-by-scene control. The V3 APIs do not offer scene-by-scene generation. Use this endpoint only if your workflow requires template-driven video creation with variable substitution.

Overview

POST https://api.heygen.com/v2/template/{template_id}/generate

Generates a video based on the specified template, including scene IDs to define the sequence of scenes and variable values for replacement.

Authentication

Header	Value
x-api-key	Your HeyGen API key
Content-Type	application/json

Path Parameters

Parameter	Type	Required	Description
template_id	string	Yes	Unique identifier of the template.

Request Body

Parameter	Type	Required	Description
variables	string (JSON)	Yes	Dynamic variables used within the template.
caption	boolean	No	Enable captions in the video. Default: false.
title	string	No	Title of the video.
dimension	object	No	Custom output dimensions. Must match the template’s aspect ratio.
dimension.width	integer	No	Width of the output video. Default: 1280.
dimension.height	integer	No	Height of the output video. Default: 720.
include_gif	boolean	No	Include a GIF preview URL in the webhook response. Default: false.
enable_sharing	boolean	No	Make the video publicly shareable immediately after creation.
folder_id	string	No	Folder ID where the video is stored.
brand_voice_id	string	No	Brand Glossary ID for applying predefined translation and pronunciation rules (translation exclusions, enforced terms, vocabulary mappings, tone preferences).
callback_url	string	No	URL to notify when video rendering is complete. If both a webhook and callback_url are configured, events are sent to both.
keep_text_vertically_centered	boolean	No	When true, replaced text elements are vertically centered based on their actual rendered height.

Example Request

POST /v2/template/YOUR_TEMPLATE_ID/generate

{
  "title": "My Template Video",
  "caption": false,
  "dimension": {
    "width": 1280,
    "height": 720
  },
  "variables": {
    "script": {
      "name": "script",
      "type": "text",
      "properties": {
        "content": "Hello, welcome to our product demo."
      }
    },
    "headline": {
      "name": "headline",
      "type": "text",
      "properties": {
        "content": "Product Overview"
      }
    }
  }
}

Response

200 — Success

{
  "error": null,
  "data": {
    "video_id": "763fca2469b98a65b351eqr8c449f4e8"
  }
}

Field	Type	Description
error	string | null	Error message if the request fails; null on success.
data.video_id	string	Unique identifier of the generated video.

Full API Reference

For complete details, see the Generate Video from Template (V2) endpoint documentation.