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.
