You can use this endpoint to bespoke video content. In case there is a feature that STUDIO provides that this API doesn't support, we recommend you use the video from template endpoint.

JSON Params

Description

test

Type: Boolean
Default: false

Test videos are free and not counted towards your quota. If you create a video in the “test” mode, we will overlay a watermark over your video.

title

Type: String

Title of the video to be shown on the share page.

description

Type: String

Description of the video to be shown on the share page.

visibility

Type: String
Possible values: private, public
Default: private

Public videos will be visible to anyone with a share URL: https://share.synthesia.io/{VIDEO_ID}.

Private videos can only be downloaded via a time-limited download link. See Retrieve a video for details.

Visibility can be changed also once the video is created via Update a video.

ctaSettings

Type: Object

Settings for a call-to-action button.

ctaSettings.label

Type: String

Label for a call-to-action button.

ctaSettings.url

Type: String

URL to navigate to, when the call-to-action button is clicked.

callbackId

Type: String

Use callback ID, so you will be able to link videos (from e.g. list video endpoint) back to the initial request. For example, if you are making a personalized video for a customer, you could enter the customer's email as a callback ID. This way, you will be able to tell who the video is for, once we have finished preparing it.

input *

Type: Array of Objects
Max: 6 items

An array of objects that each describe a clip of a multi-clip video. You can think of the clips as different scenes in the video.

input[].scriptText *

Type: String

Script for text-to-voice can be entered in any of the 34 supported languages.

input[].scriptAudio

Type: String

As an alternative to scriptText, you can provide the ID of uploaded script audio. See Upload script audio for details.

In case you use scriptAudio you also need to provide scriptLanguage.

input[].scriptLanguage

Type: String

Language code of the language the script audio was generated in.

The scriptLanguage option can only be used in connection with the scriptAudio option. If you need to control the language/voice of the scriptText, you can use input[].avatarSettings.voice option.

Language code should be in the format: en-US, where the first two characters represent language and the second two-character represent the country.

input[].avatar *

Type: String

You can use one of our stock avatars (see Avatars for complete list) or your custom avatar (contact support to get the ID of your custom avatar).

input[].avatarSettings

Type: Object

Avatar settings.

input[].avatarSettings.voice

Type: String
Default: If a voice is not provided, we will default to our recommended voice for the selected avatar.

See Voices for a complete list of voices.

input[].avatarSettings.horizontalAlign

Type: String
Possible values: left, center, right
Default: center

At the moment verticalAlign field is not exposed via API and is fixed to bottom, however together with horizontalAlign they define a reference point from where we scale the rectangular style avatar.

For example, horizontal alignment: left, would mean that avatar is called from the bottom-left cornet towards the top-right corner.

input[].avatarSettings.scale

Type: Float
Default: 1.0

The scale of the avatar.

input[].avatarSettings.style

Type: String
Possible values: rectangular or circular
Default: rectangular

rectangular style corresponds to the "Full body" avatar style in STUDIO.

circular style corresponds to the "Circle" avatar style in STUDIO.

The position of circular avatar is fixed to the center of the video both vertically and horizontally, and can't be changed. With scale 1.0, circular avatar will cover total height of the video.

Use circular style, if you need to make a round cutout of the avatar to integrate into e.g. screen recording app.

input[].avatarSettings.backgroundColor

Type: String

HEX color code (e.g. #F2F7FF) for the background of circular style avatar.

input[].avatarSettings.seamless

Experimental. This is an experimental feature and has certain limitations.

Type: Boolean
Default: false

When the seamless option is enabled, a video of the avatar will be generated in a way that first and last frames match, so videos can be concatenated seamlessly.

Use seamless option, if you need to play videos back to back seamlessly e.g. in a video chatbot app.

Limitations:

  • Only work with anna_costume1_cameraA and mia_costume1_cameraA actors.
  • Only work with static (image) backgrounds.
  • Videos will have noticeably lower quality. Though, this might not matter, depending on your use case.

input[].background *

Type: String

You can use one of our stock backgrounds (see below) or your custom background.

For the custom background, you can provide the ID of an uploaded asset (see Create an asset), or URL from where we should download the background.

Stock backgrounds:

Transparent:

  • green_screen: Green screen background can be used if you want to replace background using FFMPEG or any of the video editing software.

Solid

  • off_white
  • warm_white
  • light_pink
  • soft_pink
  • light_blue
  • dark_blue
  • soft_cyan
  • strong_cyan
  • light_orange
  • soft_orange

Image:

  • white_studio
  • white_cafe
  • luxury_lobby
  • large_window
  • white_meeting_room
  • open_office

input[].backgroundSettings

Type: Object

Background settings.

input[].backgroundSettings.videoSettings

Type: Object

Video settings.

input[].backgroundSettings.videoSettings
.shortBackgroundContentMatchMode

Type: String
Default: freeze

Possible values:

  • freeze freezes the last frame of the background until the content is finished
  • loop loops the background until the content is finished
  • slow_down slows down the background so that its duration matches the content duration

input[].backgroundSettings.videoSettings
.longBackgroundContentMatchMode

Type: String
Default: trim

Possible values

  • trim trims the background to the duration of the content
  • speed_up speeds up the background so that its duration matches the content duration

soundtrack

Deprecated. We support soundtrack option only due to backward compatibility. We recommend you use our templates functionality for rich videos. See Create a video from a template.

Type: String

Possible values:

  • corporate
  • inspirational
  • modern
  • urban
{
    "test": true,
    "title": "Hello, World!",
    "description": "This is my first synthetic video, made with the Synthesia API!",
    "visibility": "public",
    "ctaSettings": {
        "label": "Click me!",
        "url": "https://www.synthesia.io"
    },
    "callbackId": "[email protected]",
    "input": [{
        "scriptText": "This is my first synthetic video, made with the Synthesia API!",
        "scriptAudio": "12345678-1234-1234-1234-123456789012",
        "scriptLanguage": "en-US",
        "avatar": "anna_costume1_cameraA",
        "avatarSettings": {
            "voice": "1364e02b-bdae-4d39-bc2d-6c4a34814968",
            "horizontalAlign": "center",
            "scale": 1.0,
            "style": "rectangular",
            "backgroundColor": "#F2F7FF",
            "seamless": false
        },
        "background": "off_white",
        "backgroundSettings": {
            "videoSettings": {
                "shortBackgroundContentMatchMode": "freeze",
                "longBackgroundContentMatchMode": "trim"
            }
        }
    }],
    "soundtrack": "urban"
}
Language