post https://api.synthesia.io/v2/videos
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.
Synthesia API is not actively being improved
Synthesia API is in BETA. We currently don't provide any support for our API and do not guarantee any further active development.
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"
}