Overview
A template is a video layout you build once in HeyGen Studio, with named slots for text, media, avatars, and voices. Use the API to find your templates, read what each one exposes, and generate videos from them:GET /v3/templates— list the API-ready templates in your workspace.GET /v3/templates/{template_id}— read a template’s variable schema (with current defaults) and its scenes.POST /v3/templates/{template_id}— fill the variables and render a video.
Create templates in the HeyGen web editor (HeyGen Studio), or over the API with Create Studio Template via API. The detail endpoint supports templates built in the current editor format (draft version 4).
List Templates
GET /v3/templates returns a paginated list of API-ready templates: up to limit per page (1–100, default 100), with the next page fetched by passing the response’s next_token as token.
Get a Template
GET /v3/templates/{template_id} returns the template’s variable schema, with current default values, and its scene list.
variables object is keyed by variable name, and each value is returned in the same shape a generate request accepts, so you can take this response, replace the default values with your own, and submit it back to render a video. The content, asset, and other fields hold the template’s current defaults; a text variable may come back empty when the template leaves it unfilled.
Variable Types
Every variable has atype discriminator that determines the rest of its fields. The Get Template reference lists every field and allowed value.
avatar_look_id, character_id and character_type are deprecated aliases on character variables, still accepted and returned until a published sunset. Send avatar_id.
Asset input
image, video, and audio variables take an asset object in one of three forms: a public URL ({ "type": "url", "url": "https://..." }), an uploaded asset ({ "type": "asset_id", "asset_id": "..." }, from POST /v3/assets, see Upload Assets), or inline base64 ({ "type": "base64", "media_type": "image/png", "data": "<base64>" }).
Scenes
scenes lists the template’s scenes in order. Each has a scene_id (usable to restrict a render to a subset of scenes), the script text with variable placeholders left unreplaced, and the variables referenced in that scene.
Each scene renders up to 30 minutes. A script or audio value that would drive a scene past that needs splitting across scenes in Studio. See Usage Limits.
Generate a Video
POST /v3/templates/{template_id} renders a video from the template, replacing its variables with the values you supply.
id. Generation is asynchronous: poll GET /v3/videos/{video_id} until status is completed, or pass callback_url for a webhook.
The reference lists every option, including fps, caption, subtitles, folder_id and enable_sharing. The ones with rules to know:
variables: send every text variable. An omitted text variable is not filled with its default. Character, voice, image, video and audio variables can be omitted to keep their template values.scene_ids: render, reorder or repeat scenes that already exist in the template. Omit to render every scene.dimension:{ "width": ..., "height": ... }(even,128–4096) must keep the template’s aspect ratio.subtitles: requirespreset_name(e.g.classic,bold,bright); the other fields override the preset. Supplying it implies captions.reorder_music:trueby default, so background-audio tracks move with their scenes. Setfalseto pin them to the original layout positions.brand_glossary_id: a brand glossary for custom-term pronunciation, fromGET /v3/brand-glossaries.brand_voice_idis its deprecated former name.

