API Templates

With templates you can automatically produce personalized, professional-looking video content.


Use Templates via API or our Zapier app

You can use our API templates both programmatically via our API or without code via our Zapier app. The way you should define them in Synthesia STUDIO is the same for both use cases (API and Zapier).

The goal of this guide is to give you an overview of the templates feature. We'll start by creating our very own template and rendering videos using it - we'll use the example of an onboarding video to welcome new employees!

Table of contents:

  1. Design a template
  2. Variable types
  3. Generate a video via template
  4. Edit a template

Design a template

Let's start by heading to Synthesia STUDIO to create a template. By creating a template in STUDIO, you have access to the full range of features that we offer. To begin with, we'll target our video at a specific employee and then we'll introduce variables later.

Variable types

The next step is to add variables to our video. A variable is a dynamic value that you can provide later when you "call" the video request with a template.

Available text variable types (how to add):

  • Script: add a text variable as a part of script or even make the whole script a text variable.
  • Canvas text: personalize textual elements on canvas. Eg. "Welcome to ACME {{name}}"

Available image/video variable types (how to add):

  • [IMG] Canvas images: personalize images on canvas. Eg. submit a different company logo based on your users' email domain. For this example you could use Clearbit's free Logo API like logo.clearbit.com/{{domain_name}} (eg. replace the image variable value when calling the our API with https://logo.clearbit.com/tesla.com)
  • [IMG/VIDEO] Background: personalize your background of your video with a template. You can supply both image or video URLs as backgrounds. Make sure to supply images/videos in 1920x1080 resolution to fit the background perfectly.

How to add a text variable?

Specify your variable name wrapped in double curly braces - for example {{variableName}} . This lets us know to expect a dynamic value. You'll see later how to provide a value for this variable.

For our onboarding video, let's replace the name with a variable. We'll do this in the script and canvas text.

How to add an image/video variable?

Images and videos are handled slightly differently - rather than using the curly brace syntax, the STUDIO interface allows you to specify which images and videos should be variables.

To specify an image or video variable, select the asset. In the context menu on the right, you'll have the option to add a variable. Specify a sensible variable name and you're set.


What kind of image/video resolutions should you use?

For background variables: please supply images/videos in 1920x1080 resolution to fit the background perfectly.

For canvas images: please make sure to supply all images with the same resolution as the one used when creating the variable on canvas (eg. all images with 128x128 resolution). This will help you avoid unexpectedly stretched images. We are working on more image fill options, but currently this is the safest option.

Let's add two more variables for good measure. We'll replace the laptop image with an itemImage variable, and we'll add an {{itemScript}} variable to be used in the script. This way, we can customise the onboarding videos for those employees that need something other than a laptop.

Once this is complete, publish your template. From the list, select your template and make a note of the template ID. This will be used in the next step.

Generate a video

With your template published, creating a video is only moments away. We will use the video from template endpoint.

At a minimum, this endpoint requires a template ID (the ID you noted earlier) and template data. The template data is a set of key-value pairs where each key is a variable and each value is the value you'd like the variable to take.

Text variables are provided directly. For image and video variables, there are two ways of providing values. First, you may specify a URL in which case we will attempt to fetch and use the asset on your behalf. Alternatively, you may upload the asset and then use the resulting asset ID.

In our case, let's upload the background video with

curl https://upload.api.synthesia.io/v2/assets \
  -H "Authorization: ${API_KEY}" \
  -H "Content-Type: video/mp4" \
  --data-binary "@/tmp/video.mp4"

Then using the resulting asset ID, we may create the video as follows. Note in particular that we specify assets using both the URL and the ID format.

curl https://api.synthesia.io/v2/videos/fromTemplate \
  -H "Authorization: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"templateId": "0332883a-cd8f-46ee-8f01-ece06dc42388", "templateData": {"name": "Jake", "itemScript": "Second, make sure to open your starter pack. This contains a few useful things to help you get settled in.", "itemImage": "https://unsplash.com/photos/N5fp98wt6h8/download?force=true&w=640", "video": "user.44b87cf9-1451-447b-98ff-efae420d7408"}}'

That's all there is to it! Once we've received your request, we'll start processing your video.

Edit a published template

It might be that you want to make a change to one of your templates without losing the template ID (for example, if it's part of an automated workflow).

To do this, start by editing your template. Whilst it remains in draft mode, the changes will not be reflected in any videos created.

Once you're happy with your changes, publish your template and any future videos will be created based on the latest version of the template.