> ## 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.

# Create Studio Template via API

> Create a template from a video you generated with the API or saved in the HeyGen editor, then mark which parts change. The API version of "Create template" and the editor's variable panel, so the whole template loop runs from code.

<video autoPlay loop muted playsInline>
  <source src="https://mintcdn.com/heygen-1fa696a7/shARILAqoyez3uIy/images/templates-authoring/hero-one-template-three-videos.mp4?fit=max&auto=format&n=shARILAqoyez3uIy&q=85&s=dd1344fe94bd4f650983bc642dfe94f5" type="video/mp4" />
</video>

Left: the source video (Brandon, 42 Maple Lane). Middle: generated from the template with a new listing. Right: generated with a new agent, Caroline, and a new listing. Each generated video is one API call.

<video autoPlay loop muted playsInline>
  <source src="https://mintcdn.com/heygen-1fa696a7/shARILAqoyez3uIy/images/templates-authoring/source-video.mp4?fit=max&auto=format&n=shARILAqoyez3uIy&q=85&s=f76eb0f2435046cf9a28a423bf10f9f4" type="video/mp4" />
</video>

The source video (Brandon, 42 Maple Lane).

<video autoPlay loop muted playsInline>
  <source src="https://mintcdn.com/heygen-1fa696a7/shARILAqoyez3uIy/images/templates-authoring/variant-same-agent.mp4?fit=max&auto=format&n=shARILAqoyez3uIy&q=85&s=67d4a8918c00ab441d29b92e6c8cfb48" type="video/mp4" />
</video>

Generated from the template: same agent, new listing.

<video autoPlay loop muted playsInline>
  <source src="https://mintcdn.com/heygen-1fa696a7/shARILAqoyez3uIy/images/templates-authoring/variant-new-agent.mp4?fit=max&auto=format&n=shARILAqoyez3uIy&q=85&s=a361c1bed09efef8f35cf80e091c6ac8" type="video/mp4" />
</video>

Generated from the template: new agent (Caroline), new listing.

Create Studio templates **via the API**: turn a video into a reusable template and mark which parts change, without opening the HeyGen editor. Make one good video, promote it to a template, declare its variables, then generate a personalized version per agent, listing or customer.

## What this adds

You could already list templates, read them and generate videos from them over the API. Creating a template (**Create template** on the Videos page) and marking its variables (the editor's **API variable** menu, or typing `{{name}}`) needed the HeyGen editor. The authoring endpoints cover that half too, including videos you generate through the API, so the whole loop runs from code.

Authoring is about **what changes**, not layout. Positions, timing and scenes come from the source video. To change those, edit the template in the HeyGen editor.

> [!TIP]
>
> Built your template in the HeyGen editor instead? See [Building a Studio Template](https://heygen-1fa696a7.mintlify.site/templates-guide.md).

## The endpoints

| Endpoint | What it does | Scopes |
| - | - | - |
| [`POST /v3/templates`](https://heygen-1fa696a7.mintlify.site/reference/create-template-from-video) | Create a template from a video | `templates:write`, `videos:read` |
| [`GET /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-template) | Read a template and its composition | `templates:read` |
| [`PUT /v3/templates/{template_id}/variables`](https://heygen-1fa696a7.mintlify.site/reference/set-template-variables) | Declare the template's variables | `templates:write` |
| [`POST /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/generate-video-from-template) | Generate a video from the template | `templates:read`, `videos:write` |
| [`PATCH /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-template) | Rename a template | `templates:write` |
| [`DELETE /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-template) | Delete a template | `templates:write` |

The rest of this page builds one real-estate listing template end to end. The agent introduces a property over a photo of the house, and four things become swappable: **the agent** (avatar), **their voice**, **the listing photo**, and **four phrases** in the script.

## Before you start

* An **API key**, sent as the `x-api-key` header.
* A **Creator role or higher** in the workspace, with template creation allowed in the workspace settings. Otherwise the authoring endpoints return `403` `resource_access_denied`.
* A **source video**. It must be one you generated with `POST /v3/videos`, or one you created or saved in the HeyGen editor. URL-to-Video and older editor videos can't be used (`template_source_unsupported`).
* Your own **IDs**. The video, template and element IDs in the examples won't exist in your workspace. Use the ones your responses return. Brandon and Caroline are public avatars and voices, so those IDs work anywhere.

## Step 1: Make the source video

Write the script with real values, not placeholders. Anything you later want to swap should appear as plain text you can point at, like `42 Maple Lane`. Here the listing photo is the background, and the avatar's own background is removed so the photo shows behind them.

```bash cURL theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "type": "avatar",
  "title": "Listing - 42 Maple Lane (template source)",
  "avatar_id": "Brandon_Business_Standing_Front_public",
  "voice_id": "513b14b431b64a578c467c480dd0a9c3",
  "script": "Hi, I'm Brandon with Bayview Realty. Take a look at 42 Maple Lane: three bedrooms, a sunny kitchen, and a backyard made for summer. It's listed at $749,000. Book your private tour today.",
  "remove_background": true,
  "background": {
    "type": "image",
    "url": "https://images.unsplash.com/photo-1568605114967-8130f3a36994?w=1920&q=80"
  },
  "aspect_ratio": "16:9",
  "resolution": "1080p"
}
JSON
```

The response returns the new `video_id`.

> [!TIP]
>
> You don't have to wait for the render. A template copies the video's draft, not its rendered file, so you can create it as soon as you have the `video_id`.

## Step 2: Promote it to a template

Pass the video ID and, optionally, a name (it defaults to the video's title). The template is private to your workspace and starts with **no variables**.

```bash cURL theme={null}
curl -X POST "https://api.heygen.com/v3/templates" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_id": "3c8e1f6a9b2d4c7e8a5f0b1d6e9c2a47", "name": "Listing video - agent intro"}'
```

```jsonc Example response (201 Created, abbreviated) theme={null}
{
  "data": {
    "id": "6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64",
    "name": "Listing video - agent intro",
    "source_video_id": "3c8e1f6a9b2d4c7e8a5f0b1d6e9c2a47",
    "edit_version": "0",
    "variables": {},
    "composition": {
      "scenes": [
        {
          "id": "scene_0_1790737769242_zrnu3qfqm",
          "background": {
            "id": "bg_image_0_1790737769242_8e1hrymj6",
            "type": "image",
            "url": "https://static.heygen.ai/example-listing-photo.jpg",
            "bindable_as": ["image"]
          },
          "elements": [
            {
              "id": "avatar_0_1790737769242_ltg7rc9hp",
              "type": "avatar",
              "avatar_id": "Brandon_Business_Standing_Front_public",
              "bindable_as": ["character"]
            }
          ],
          "script": [
            {
              "id": "script_0_1790737769242_2bae1yu2m",
              "type": "text",
              "text": "Hi, I'm Brandon with Bayview Realty. Take a look at 42 Maple Lane: three bedrooms, a sunny kitchen, and a backyard made for summer. It's listed at $749,000. Book your private tour today.",
              "voice_id": "513b14b431b64a578c467c480dd0a9c3",
              "bindable_as": ["voice", "text"]
            }
          ]
        }
      ],
      "background_audio": []
    },
    // also returned: aspect_ratio, created_at, updated_at, thumbnail_url when one exists, and the older scenes and scene_ids
  }
}
```

The response is the full template. Note its `id`: every call after this one uses it. Two other fields matter for the next steps: `composition`, which lists every part of the video, and `edit_version`, which starts at `"0"`.

## Step 3: Find the parts you can swap

`composition.scenes` describes each scene. Every part that can take a variable has an `id` and a `bindable_as` list, which says what kind of variable it accepts.

![The source frame with the background outlined and labeled image, and the avatar outlined and labeled character](https://mintcdn.com/heygen-1fa696a7/shARILAqoyez3uIy/images/templates-authoring/composition-parts.jpg?fit=max\&auto=format\&n=shARILAqoyez3uIy\&q=85\&s=65e6c9769d6cea2d865299a6b0e750da)

The source video's parts, as listed in composition. The spoken line is the third part: it has no box because you hear it rather than see it.

This template has three: the background (`image`), the avatar element (`character`) and the script line (`voice`, `text`). Your template will have different IDs, so take them from your own response.

A template can also contain on-screen text, image and video elements, and `composition.background_audio` tracks for music and sound effects that bind as `audio`. Call `GET /v3/templates/{template_id}` at any time to read the same structure again. Use `composition` rather than the older `scenes` and `scene_ids` fields, which are kept for existing integrations.

## Step 4: Declare the variables

A variable is a name plus the part it controls. There are two ways to create one, and most templates use both.

> [card] Bind a part by element\_id
>
> For `character`, `voice`, `image`, `video` and `audio` variables. Point at a part from Step 3. Each part takes at most one of these.

> [card] Match text
>
> For `text` variables. Give the exact, case-sensitive text. Every occurrence in the script and on-screen text becomes `{{name}}`, and the matched text becomes the default. Add `element_ids` to limit it to specific parts.

> [!WARNING]
>
> `PUT` replaces the template's complete list of variables. On a template that already has variables, read it first and send the full list with its current `edit_version`. [More on this below](#the-put-replaces-the-whole-list).

We bind the agent, their voice and the listing photo, and turn four phrases into text variables:

```bash cURL theme={null}
curl -X PUT "https://api.heygen.com/v3/templates/6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64/variables" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "expected_edit_version": "0",
  "variables": {
    "agent": {
      "type": "character",
      "element_id": "avatar_0_1790737769242_ltg7rc9hp"
    },
    "agent_voice": {
      "type": "voice",
      "element_id": "script_0_1790737769242_2bae1yu2m"
    },
    "listing_photo": {
      "type": "image",
      "element_id": "bg_image_0_1790737769242_8e1hrymj6"
    },
    "agent_name": {
      "type": "text",
      "match": "Brandon"
    },
    "brokerage": {
      "type": "text",
      "match": "Bayview Realty"
    },
    "address": {
      "type": "text",
      "match": "42 Maple Lane"
    },
    "price": {
      "type": "text",
      "match": "$749,000"
    }
  }
}
JSON
```

The response is the updated template. In `composition.scenes[0].script[0].text`, the four phrases are now placeholders:

```text theme={null}
Before: Hi, I'm Brandon with Bayview Realty. Take a look at 42 Maple Lane: ... It's listed at $749,000. ...
After:  Hi, I'm {{agent_name}} with {{brokerage}}. Take a look at {{address}}: ... It's listed at {{price}}. ...
```

Each bound part now carries a `variable` field with its variable's name, the script lists its `text_variables`, `edit_version` went from `"0"` to `"1"`, and `variables` lists each variable with its default value.

### The PUT replaces the whole list

**The body you send becomes the complete list of variables.** Anything you leave out is deleted, and its text goes back to the default.

To add a variable, send the same list again plus the new one. Re-sending a `match` that is already a placeholder is fine.

```jsonc Wrong: only the new variable theme={null}
{
  "variables": {
    "bedrooms": { "type": "text", "match": "three bedrooms" }
  }
}
// Result: 1 variable. The other 7 are deleted and the script is back to
// "Hi, I'm Brandon with Bayview Realty. Take a look at 42 Maple Lane: {{bedrooms}}, ..."
```

```jsonc Right: the full list plus the new one theme={null}
{
  "expected_edit_version": "1",
  "variables": {
    "agent":         { "type": "character", "element_id": "avatar_0_1790737769242_ltg7rc9hp" },
    "agent_voice":   { "type": "voice",     "element_id": "script_0_1790737769242_2bae1yu2m" },
    "listing_photo": { "type": "image",     "element_id": "bg_image_0_1790737769242_8e1hrymj6" },
    "agent_name":    { "type": "text", "match": "Brandon" },
    "brokerage":     { "type": "text", "match": "Bayview Realty" },
    "address":       { "type": "text", "match": "42 Maple Lane" },
    "price":         { "type": "text", "match": "$749,000" },
    "bedrooms":      { "type": "text", "match": "three bedrooms" }
  }
}
// Result: 8 variables, edit_version "2", and the script reads
// "Hi, I'm {{agent_name}} with {{brokerage}}. Take a look at {{address}}: {{bedrooms}}, ..."
```

### Protect against overwrites with `expected_edit_version`

Every change to the variables increases `edit_version`. Send the version you read as `expected_edit_version`, and the API applies your change only if nobody changed the template since. Without it, a PUT built from a stale read silently deletes a variable a teammate added in between, because the PUT replaces the whole list. With it, the API rejects the request with `409` [`stale_edit_version`](https://heygen-1fa696a7.mintlify.site/docs/error-codes#stale-edit-version) and changes nothing: read the template again, add your change, and resend with the new version.

## Step 5: Generate a video per agent, per listing

Send the values for this video, keyed by variable name. Character, voice and image variables you leave out keep the template's value.

This call swaps in a different agent, Caroline, with her own voice, and a new listing:

```bash cURL theme={null}
curl -X POST "https://api.heygen.com/v3/templates/6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "title": "Listing - 7 Birch Court (Caroline)",
  "variables": {
    "agent": {
      "type": "character",
      "avatar_id": "Caroline_Business_Standing_Front_public"
    },
    "agent_voice": {
      "type": "voice",
      "voice_id": "f8a2cbd411e84454afc4aba8895d0a3b"
    },
    "agent_name": {
      "type": "text",
      "content": "Caroline"
    },
    "brokerage": {
      "type": "text",
      "content": "Summit Homes"
    },
    "address": {
      "type": "text",
      "content": "7 Birch Court"
    },
    "price": {
      "type": "text",
      "content": "$615,000"
    },
    "listing_photo": {
      "type": "image",
      "asset": {
        "type": "url",
        "url": "https://images.unsplash.com/photo-1600596542815-ffad4c1539a9?w=1920&q=80"
      }
    }
  }
}
JSON
```

The response comes back right away with the new video's `id`. Both videos below came from the same template:

> [card] Same agent, new listing
>
> Only the text and photo were sent. Brandon and his voice came from the template.
>
> <video controls playsInline>
>   <source src="https://mintcdn.com/heygen-1fa696a7/shARILAqoyez3uIy/images/templates-authoring/variant-same-agent.mp4?fit=max&auto=format&n=shARILAqoyez3uIy&q=85&s=67d4a8918c00ab441d29b92e6c8cfb48" type="video/mp4" />
> </video>

> [card] New agent, new listing
>
> The request above: Caroline, her own voice, and new text and photo.
>
> <video controls playsInline>
>   <source src="https://mintcdn.com/heygen-1fa696a7/shARILAqoyez3uIy/images/templates-authoring/variant-new-agent.mp4?fit=max&auto=format&n=shARILAqoyez3uIy&q=85&s=a361c1bed09efef8f35cf80e091c6ac8" type="video/mp4" />
> </video>

> [!WARNING]
>
> **Always send every text variable.** A text variable you leave out is not filled with its default. HeyGen reads the placeholder name out loud instead. This video was generated with only `address` sent, and it says *"Hi, I'm Agent Name with Brokerage... It's listed at price."*
>
> <video controls playsInline>
>   <source src="https://mintcdn.com/heygen-1fa696a7/shARILAqoyez3uIy/images/templates-authoring/omitted-text-variables.mp4?fit=max&auto=format&n=shARILAqoyez3uIy&q=85&s=bec0e9a1fc8a40399652f0b1a793230a" type="video/mp4" />
> </video>
>
> Read the list of variables from `GET /v3/templates/{template_id}` and fill all the text ones, so a variable added to the template later never slips through.

### Swapped media keeps the source video's framing

When you omit `fit`, a template created with `POST /v3/templates` places the new image or video the way the source video placed the original: a background that filled the frame still fills it, and a photo placed inside a box still fits inside that box. Send `fit` only to change that, for example `"fit": "contain"` to show the whole photo with bars, or `"fit": "cover"` to fill a box that used to show a whole image.

The variable list from `GET /v3/templates/{template_id}` echoes `"fit": "contain"` for image and video variables. That is the default for templates built in the HeyGen editor. On a template created from a video, omitting `fit` keeps the source framing, shown on the left.

> [card] Default (source framing kept)
>
> ![Swapped listing photo filling the whole frame](https://mintcdn.com/heygen-1fa696a7/shARILAqoyez3uIy/images/templates-authoring/fit-cover.jpg?fit=max\&auto=format\&n=shARILAqoyez3uIy\&q=85\&s=62070cd322a9e40f53e607e5ad9d8c6d)

> [card] fit: "contain"
>
> ![Swapped listing photo with white bars on both sides](https://mintcdn.com/heygen-1fa696a7/shARILAqoyez3uIy/images/templates-authoring/fit-contain.jpg?fit=max\&auto=format\&n=shARILAqoyez3uIy\&q=85\&s=3de367dcf088f077d53f13f22a7e9285)

## Step 6: Wait for the video

Poll [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) until `status` is `completed` (or `failed`), or pass `callback_url` on the generate call to get a webhook instead. When you generate many videos, use webhooks: polling each one adds up against your rate limit.

`video_url` and `thumbnail_url` are signed links that expire. Call this endpoint again whenever you need fresh ones.

## Rename and delete

### Rename

`PATCH` renames the template and returns the full template. Renaming does not change `edit_version`. Other changes go through `PUT /v3/templates/{template_id}/variables` or the HeyGen editor.

```bash cURL theme={null}
curl -X PATCH "https://api.heygen.com/v3/templates/6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Listing video - agent intro (v2)"}'
```

### Delete

`DELETE` removes the template from your list so it can no longer generate videos. Videos you already generated from it are not affected. There is no request body.

```bash cURL theme={null}
curl -X DELETE "https://api.heygen.com/v3/templates/6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64" \
  -H "x-api-key: YOUR_API_KEY"
```

The response confirms `"deleted": true`. Reading the template afterwards returns `404` `template_not_found`.

## Errors

[Error codes](https://heygen-1fa696a7.mintlify.site/docs/error-codes.md) explains each authoring code and its fix: `template_source_unsupported`, `variable_match_not_found`, `variable_match_spans_styles`, `template_limit_reached` (2000 templates per workspace) and `stale_edit_version`. A `403` `forbidden` means the authoring endpoints aren't enabled for your workspace yet: contact support.

## FAQ

> [accordion] Which avatars can I swap in?
>
> Any avatar look you can use, from [`GET /v3/avatars/looks`](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-looks), including your own digital twin or photo avatar. Pair a `character` variable with a `voice` variable so the voice matches the person.

> [accordion] My template already has \{\{placeholders}} from the editor. How do I keep them?
>
> Declare the text variable without `match`, for example `"first_name": { "type": "text" }`. Placeholders that already exist are kept.

> [accordion] Can I render only some scenes?
>
> Yes. Pass `scene_ids` on the generate call to pick, reorder or repeat scenes that exist in the template.

## Related

> [card] [Studio Template reference](https://heygen-1fa696a7.mintlify.site/templates.md)
>
> Every variable type, asset input and generate option.

> [card] [Building a Studio Template](https://heygen-1fa696a7.mintlify.site/templates-guide.md)
>
> The same flow, with the template built in the HeyGen editor.


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