Skip to main content

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:
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.
The 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 a type 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.
The response returns the new video’s 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: requires preset_name (e.g. classic, bold, bright); the other fields override the preset. Supplying it implies captions.
  • reorder_music: true by default, so background-audio tracks move with their scenes. Set false to pin them to the original layout positions.
  • brand_glossary_id: a brand glossary for custom-term pronunciation, from GET /v3/brand-glossaries. brand_voice_id is its deprecated former name.