> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.synthesia.io/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.synthesia.io/docs/_mcp/server.

# Guide: Create a video from a template

> Learn how to automate personalized AI video creation using Synthesia’s API templates. This comprehensive guide provides step-by-step instructions on setting up video templates, adding dynamic variables, and generating customized videos programmatically.

This guide walks through calling Synthesia's API to generate a video from a template with variables. For how to build a template and add each type of variable (script, canvas text, media, or avatar), see [Add variables for programmatic video creation](https://docs.synthesia.io/docs/synthesia-templates#add-variables-for-programmatic-video-creation).

## Create a video from a template

**To create a video from a template with Synthesia's API:**

1. Build your template in Synthesia, [adding variables](https://docs.synthesia.io/docs/synthesia-templates#add-variables-for-programmatic-video-creation) for whatever should change between videos.
2. Publish the video as a template, then copy its template ID from your template library.
3. Call the [Create a video from a template endpoint](/docs/video-api-reference/videos/create-a-video-from-a-template) with:
   * `templateId`: The ID from step 2.
   * `templateData`: An object of key-value pairs, where each key is a variable name and each value is what to replace it with.
4. Optionally, personalize the video's `title` and `description` parameters too.
5. Once Synthesia receives your request, the video is processed and available shortly after.

> **Warning**
>
> ### Important:
>
> Variable names are case-sensitive. The casing you use as a key in `templateData` must exactly match the casing you used when naming the variable in your template.

## Supplying values for media variables

For image and video variables, supply a value one of two ways:

* A URL—Synthesia fetches and uses the asset.
* An asset ID, after [uploading the asset](/docs/upload-api-reference/create-an-asset) yourself.

Match the aspect ratio of the replacement image or video to what it's replacing, to avoid unexpected stretching or cropping—see [Add variables for programmatic video creation](https://docs.synthesia.io/docs/synthesia-templates#add-variables-for-programmatic-video-creation) for the specifics per variable type.

## Supplying values for avatar variables

For an avatar variable, supply the target avatar's ID as the value.

**To find an avatar's ID:**

1. Go to the [Avatars](https://docs.synthesia.io/docs/synthesia-avatars) page.
2. Select the three-dot menu in the top-right corner of the avatar you want.
3. Select `Copy ID`.

> **Note**
>
> ### Note:
>
> EXPRESS-2 avatars can't be used with Synthesia's API.

## Special characters in text variable values

By default, special characters in a text variable's value are HTML-escaped when you pass them in your request. For example, `This & that` becomes `This & that`.

To avoid this, pass the escaped entity yourself instead of the raw character. For example:

`templateData: {my_text_variable: 'This & that'}`

See [this list of HTML entities](https://htmlandcssbook.com/extras/html-escape-codes/) for other special characters you might need to escape.

## What's next

* [How do I add a variable to a video? - Synthesia Knowledge Base](https://help.synthesia.io/en/articles/6823627-how-do-i-add-a-variable-to-a-video)