> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HeyGen Studio Template

> Find your HeyGen Studio templates and read each one's variable schema over the API, then fill the slots and render.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-5.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=422da140ece4b799d490f85bb2013ca5)

## 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`](https://heygen-1fa696a7.mintlify.site/reference/list-templates) — list the API-ready templates in your workspace.
* [`GET /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-template) — read a template's variable schema (with current defaults) and its scenes.
* [`POST /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/generate-video-from-template) — fill the variables and render a video.

> [!NOTE]
>
> Create templates in the HeyGen web editor ([HeyGen Studio](https://app.heygen.com/avatar/studio)), or over the API with [Create Studio Template via API](https://heygen-1fa696a7.mintlify.site/create-template.md). The detail endpoint supports templates built in the **current editor format** (draft version 4).

## List Templates

[`GET /v3/templates`](https://heygen-1fa696a7.mintlify.site/reference/list-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`.

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/templates?limit=100" \
  -H "x-api-key: YOUR_API_KEY"
```

## Get a Template

[`GET /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-template) returns the template's variable schema, with current default values, and its scene list.

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/templates/77e650952c024c6188a35e23e7088617" \
  -H "x-api-key: YOUR_API_KEY"
```

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](https://heygen-1fa696a7.mintlify.site/reference/get-template.md) lists every field and allowed value.

| `type` | Value you send | Notes |
| - | - | - |
| `text` | `content` | Up to `10000` characters. May be empty in a GET response; must be non-empty when generating. |
| `image` | `asset` | Optional `fit` for how it fills the placeholder box (default `contain`). |
| `video` | `asset` | Optional `fit`, `play_style` (default `loop`) and `volume` (`0.0` to `1.0`). |
| `audio` | `asset` | |
| `voice` | `voice_id` | From [`GET /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/list-audio-voices). Optional `locale`, e.g. `en-US`. |
| `character` | `avatar_id` | Any avatar look, including talking photos, from [`GET /v3/avatars/looks`](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-looks). The kind is inferred from the look. |

`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`](https://heygen-1fa696a7.mintlify.site/reference/upload-asset), see [Upload Assets](https://heygen-1fa696a7.mintlify.site/docs/upload-assets.md)), 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](https://heygen-1fa696a7.mintlify.site/docs/usage-limits.md#output-video-specifications).

## Generate a Video

[`POST /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/generate-video-from-template) renders a video from the template, replacing its variables with the values you supply.

```bash theme={null}
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
  }'
```

The response returns the new video's `id`. Generation is asynchronous: poll [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) until `status` is `completed`, or pass `callback_url` for a [webhook](https://heygen-1fa696a7.mintlify.site/docs/webhooks.md).

The [reference](https://heygen-1fa696a7.mintlify.site/reference/generate-video-from-template.md) 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](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary.md) for custom-term pronunciation, from [`GET /v3/brand-glossaries`](https://heygen-1fa696a7.mintlify.site/reference/list-brand-glossaries). `brand_voice_id` is its deprecated former name.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.