HeyGen Studio Template

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.

Templates are created and edited in the HeyGen web editor. Only templates that have variables defined appear in the list, and the detail endpoint supports templates built in the current editor format (draft version 4). Create a template in HeyGen Studio first, then drive it from the API.

List Templates

Endpoint: GET /v3/templates
Purpose: Return a paginated list of API-ready templates in the workspace.

curl -X GET "https://api.heygen.com/v3/templates?limit=100" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "data": {
    "templates": [
      {
        "id": "77e650952c024c6188a35e23e7088617",
        "name": "Quarterly Update",
        "thumbnail_url": "https://.../thumb.png",
        "aspect_ratio": "16:9",
        "created_at": 1711929600,
        "updated_at": 1711929600
      }
    ],
    "has_more": false,
    "next_token": null
  }
}

Query Parameters

Parameter	Type	Required	Default	Description
`limit`	integer	No	`100`	Templates per page, `1`–`100`.
`token`	string	No	—	Opaque pagination cursor from a previous response’s `next_token`.

Get a Template

Endpoint: GET /v3/templates/{template_id}
Purpose: Return template details including its variable schema (with current default values) and scene list.

curl -X GET "https://api.heygen.com/v3/templates/77e650952c024c6188a35e23e7088617" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "data": {
    "id": "77e650952c024c6188a35e23e7088617",
    "name": "Quarterly Update",
    "aspect_ratio": "16:9",
    "variables": {
      "headline": {
        "type": "text",
        "content": "Q3 in review"
      },
      "cover_image": {
        "type": "image",
        "asset": { "type": "url", "url": "https://.../cover.png" },
        "fit": "cover"
      }
    },
    "scenes": [
      {
        "scene_id": "scene_1",
        "script": "Welcome to the {{headline}} update.",
        "variables": [
          { "name": "headline", "variable_type": "text" }
        ]
      }
    ]
  }
}

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:

`text`

Field	Type	Required	Description
`content`	string	Yes	Replacement text, up to `10000` characters. May be empty in a GET response (an unfilled default); must be non-empty when generating.

`image`

Field	Type	Required	Default	Description
`asset`	object	Yes	—	Image to place — see Asset input.
`fit`	string	No	`contain`	How the image fits the placeholder box: `cover`, `contain`, `crop`, or `none`.

`video`

Field	Type	Required	Default	Description
`asset`	object	Yes	—	Video to place — see Asset input.
`fit`	string	No	`contain`	How the video fits the placeholder box: `cover`, `contain`, `crop`, or `none`.
`play_style`	string	No	`loop`	Playback when the video is shorter than the scene: `fit_to_scene`, `freeze`, `loop`, `once`, or `full_video`.
`volume`	number	No	`1.0`	Audio volume of the video track, `0.0` (muted) to `1.0`.

`audio`

Field	Type	Required	Description
`asset`	object	Yes	Audio to place — see Asset input.

`voice`

Field	Type	Required	Description
`voice_id`	string	Yes	Voice used for text-to-speech. Browse with `GET /v3/voices`.
`locale`	string	No	Optional voice locale, e.g. `en-US`.

`character`

Field	Type	Required	Default	Description
`character_id`	string	Yes	—	Avatar ID or talking photo ID to place.
`character_type`	string	No	`avatar`	Kind of character `character_id` refers to: `avatar` or `talking_photo`.

Asset input

image, video, and audio variables take an asset object, discriminated by type. Provide one of:

Form	Shape
Public URL	`{ "type": "url", "url": "https://..." }`
Uploaded asset	`{ "type": "asset_id", "asset_id": "..." }` — from `POST /v3/assets` (see Upload Assets).
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.

Generate a Video

Endpoint: POST /v3/templates/{template_id}
Purpose: Render a video from the template, replacing its variables with the values you supply.

Quick Example

curl -X POST "https://api.heygen.com/v3/templates/YOUR_TEMPLATE_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "headline": { "type": "text", "content": "Q3 in review" },
      "cover_image": {
        "type": "image",
        "asset": { "type": "url", "url": "https://example.com/cover.png" },
        "fit": "cover"
      }
    },
    "title": "Quarterly Update — Q3",
    "caption": false
  }'

Response

{
  "data": {
    "video_id": "vid_9f2c..."
  }
}

Generation is asynchronous. Poll GET /v3/videos/{video_id} until status is completed, then read the download URL.

Request Body

Parameter	Type	Required	Default	Description
`variables`	object	Yes	—	Replacements keyed by variable name, each following the per-type shapes in Variable Types. Only include the variables you want to change.
`title`	string	No	—	Title for the generated video.
`scene_ids`	array of strings	No	—	Scene IDs to render, in order — repeats allowed to duplicate a scene. Scenes must already exist in the template; the API can’t create new ones. Omit to render every scene.
`dimension`	object	No	—	Output resolution override as `{ "width": ..., "height": ... }` (even, `128`–`4096`). Must keep the template’s aspect ratio.
`fps`	number	No	`25`	Output frame rate: `25`, `30`, or `60`.
`caption`	boolean	No	`false`	Burn captions into the video.
`subtitles`	object	No	—	Subtitle style — see Subtitle settings. Supplying this implies captions.
`reorder_music`	boolean	No	`true`	When `true`, background-audio tracks move with their scenes; when `false`, they stay pinned to the original layout positions.
`keep_text_vertically_centered`	boolean	No	`false`	Re-center replaced text elements based on their rendered height.
`include_gif`	boolean	No	`false`	Include a GIF preview URL in the webhook payload.
`enable_sharing`	boolean	No	`false`	Make the generated video’s share page publicly accessible.
`callback_url`	string	No	—	Webhook URL called with the result, in addition to any registered endpoints.
`callback_id`	string	No	—	Opaque ID echoed back in webhook events for this video.
`folder_id`	string	No	—	Folder to place the generated video in.
`brand_voice_id`	string	No	—	Brand voice ID controlling pronunciation and term handling.

Subtitle settings

When you pass subtitles, preset_name is required; the rest override the preset.

Field	Type	Required	Default	Description
`preset_name`	string	Yes	—	Subtitle preset, e.g. `classic`, `bold`, `bright`.
`alignment`	integer	No	`2`	Subtitle alignment.
`disable_highlight`	boolean	No	`false`	Override the preset’s word-highlight style.
`font_size`	integer	No	—	Font-size override for the preset.
`position`	object	No	—	Position override as `{ "x": ..., "y": ... }`.

From template to video

The typical flow is three steps:

Discover — GET /v3/templates to find the template and its id.
Inspect — GET /v3/templates/{template_id} to read the variable schema and defaults.
Fill and generate — replace the defaults in the variables object with your own values and POST them to POST /v3/templates/{template_id}, then poll GET /v3/videos/{video_id} for the result.

Auth

User Info

Models

Video Generation

Video Composition

Realtime Video

Video Translation

Video Agent

Lipsync

Tools

Avatar Management

Voice Management

Asset Management

Batches

Webhook

Limits

Pricing

Socials

For Agents

Integrations

Legacy APIs

Overview

List Templates

Query Parameters

Get a Template

Variable Types

`text`

`image`

`video`

`audio`

`voice`

`character`

Asset input

Scenes

Generate a Video

Quick Example

Request Body

Subtitle settings

From template to video

​Overview

​List Templates

​Query Parameters

​Get a Template

​Variable Types

​text

​image

​video

​audio

​voice

​character

​Asset input

​Scenes

​Generate a Video

​Quick Example

​Request Body

​Subtitle settings

​From template to video

Overview

List Templates

Query Parameters

Get a Template

Variable Types

`text`

`image`

`video`

`audio`

`voice`

`character`

Asset input

Scenes

Generate a Video

Quick Example

Request Body

Subtitle settings

From template to video