AI Clipping4

API Keys1

Asset Batches4

Assets7

Audio9

Avatars12

Background Removal4

Batches3

Brand10

Custom Agents5

Durable Workflows13

Filler Word Removal2

Folders2

HyperFrames4

Images2

Lipsync5

Lipsync Batches3

Models12

Podcasts4

Templates7

User2

Video Agent9

Video Analysis2

Video Generations2

Video Quality4

Video Translate16

Video Translation Batches3

Videos10

Voices8

Webhooks7

Workflows4

Templates

Generate Video from Template

Changed on Nov 3, 2026

Generates a video from a template by filling its variables. Use scene_ids to select, reorder or repeat the template's existing scenes. Poll GET /v3/videos/{video_id} or use webhooks for completion. An idempotent replay returns the original response, not the video's current state.

post/v3/templates/{template_id}

Request

Base URL
https://api.heygen.com
URL
https://api.heygen.com/v3/templates/{template_id}
Auth
- API key in header x-api-key
- or HTTP bearer

Path parameters

template_idstring required

Unique template identifier

Headers

Idempotency-Keystring

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Request body

variablesobject required

Template variable replacements, keyed by the variable name defined in the template. Supply every text variable you want filled: an omitted text variable is not substituted, so its literal {{variable_name}} placeholder remains in the text it is bound to, whether that is a spoken script or an on-screen text element. Omitting an image, video, audio, character or voice variable is safe and keeps the value the template already holds. The defaults returned by GET /v3/templates/{template_id} are the template's current values, not fallbacks applied at generation time.

titlestring nullable

Title for the generated video

captionboolean

Whether to burn captions into the video

callback_idstring nullable

Opaque ID echoed back in webhook events for this video

callback_urlstring nullable

URL called with the video result in addition to registered webhook endpoints

folder_idstring nullable

Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder.

brand_voice_idstring nullable

Legacy field name for brand_glossary_id. Both are accepted and resolve to the same workspace record. Prefer brand_glossary_id.

brand_glossary_idstring nullable

Brand glossary controlling how custom terms are pronounced in generated speech. Discover IDs via GET /v3/brand-glossaries.

fpsnumber

Output frame rate. One of 25, 30, or 60.

scene_idsstring[] nullable

Scene IDs to render, in order (repeats allowed). Scenes must already exist in the template; the API can select, reorder, and repeat scenes but cannot create new ones. Omit to render all scenes in template order.

reorder_musicboolean

When true (default), background audio tracks move with their scenes. When false, tracks stay pinned to layout positions.

keep_text_vertically_centeredboolean

When true, replaced text elements are vertically re-centered based on their rendered height

include_gifboolean

Whether to include a GIF preview in the webhook payload

enable_sharingboolean

Whether the generated video's share page is publicly accessible

Response

Successful response

Example response

{
  "data": {
    "id": "v_abc123def456",
    "title": "My Generated Video",
    "created_at": 1711929600,
    "completed_at": 1711930200,
    "video_url": "https://files.heygen.ai/video/abc123.mp4",
    "thumbnail_url": "https://files.heygen.ai/thumb/abc123.jpg",
    "gif_url": "https://files.heygen.ai/gif/abc123.gif",
    "captioned_video_url": "https://files.heygen.ai/video/abc123_captioned.mp4",
    "subtitle_url": "https://files.heygen.ai/srt/abc123.srt",
    "duration": 30.5,
    "folder_id": "folder_abc123",
    "output_language": "en-US",
    "failure_code": "rendering_failed",
    "failure_message": "Avatar rendering timed out",
    "video_page_url": "https://app.heygen.com/video/abc123"
  }
}

Changes

Nov 3, 20267dfa5e59b4f5 Revision changes
- breaking
  removed the enum value avatar of the request property ///
- breaking
  removed the enum value talking_photo of the request property ///
- info
  added the new optional request property
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  the request property /// became optional
- info
  the request property default value avatar was removed
- info
  request property deprecated
- info
  request property /// deprecated
- info
  request property /// deprecated
- info
  added asset_id base64 url discriminator mapping keys to the /// request property
- info
  added asset_id base64 url discriminator mapping keys to the /// request property
- info
  added asset_id base64 url discriminator mapping keys to the /// request property
- info
  added audio character image text video voice discriminator mapping keys to the / request property
- info
  request property /// list-of-types was widened by adding types null to media type application/json
- info
  request property /// list-of-types was widened by adding types null to media type application/json
- info
  the /// request property's minLength was decreased from 1 to 0
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status

Operation history