Synthesia
App · 22 actions
Create and manage avatar videos, templates, dubbing projects, translations, assets and webhooks.
Actions
| Action | What it does |
|---|---|
| Add locales to a dubbing project (original imported video) | Add target languages to a dubbing project. |
| Create a dubbing project from an uploaded video asset | Create a dubbing project from an uploaded video. |
| Create a video | Create a video in your Synthesia account. |
| Create a video from a template | Create a video from a Synthesia template. |
| Create a Webhook | Create a webhook that sends the events you choose to a web address. |
| Create media asset | Upload a media asset, either as a file or from a web address. |
| Delete a video | Delete a video. |
| Delete a webhook | Delete a webhook. |
| Get a template | Get a template, including the variables you can customise. |
| Get a video | Get a video and its status. |
| Get a webhook | Get a webhook and its status. |
| Get dubbing project status and videos | Get a dubbing project's status (uploading, in progress, complete or error) and its dubbed videos. |
| Get supported languages for translations | List the languages videos can be translated into. |
| Get user media asset | Get a media asset you uploaded, with its status, title, content type and details such as its detected language when available. |
| Get video translations of a given root video id | Get a video's translation status in each language: complete, in progress or error. |
| List templates | List your Synthesia templates, with the variables you can fill in for each. |
| List videos | List the videos created in Synthesia or through the API. |
| List webhooks | List all currently configured webhooks in your Synthesia account. |
| Query audit log events | List audit log events for a workspace or an organization; give exactly one of the two. |
| Search audit log events (Advanced) | Search audit log events using detailed filters. |
| Start/Update a video translation | Start translating a video into each language you choose. |
| Update a video | Change a video's title or description, or make it public so anyone can watch it on its share page. |
Add locales to a dubbing project (original imported video)
Add target languages to a dubbing project. Languages it already has are skipped.
Inputs
- Dubbing project ID
dubbing_project_idtextRequired - UUID of the dubbing project (original imported video)
- Target languages
target_languageslistRequired - The languages to dub the source media asset to.One or more of:
af,sq,am,ar,ar-DZ,ar-BH,ar-EG,ar-IQ,ar-JO,ar-KW, and 139 more. - Lipsync enabled
lipsync_enabledtrue/false - Whether to enable lipsync for the dubbed video.
- Burned in captions enabled
burned_in_captions_enabledtrue/false - Whether to burn captions into the dubbed video. Applies only to the locales added by this request; existing dubbed videos keep their setting. The captions.srt and captions.vtt files are still returned either way.
- Video duration
video_durationtext - The duration of the video to create.One of:
adaptive,original. - Visibility
visibilitytext - The visibility of the dubbed video.One of:
private,public.
Outputs
responseobject- Response.
Example output
{
"response": {
"createdDubbedAssets": [],
"dubbedErrors": []
}
}Create a dubbing project from an uploaded video asset
Create a dubbing project from an uploaded video. For now, only signed Amazon S3 links are supported.
Inputs
- Title
titletextRequired - The title of the dubbed video to create.
- Target languages
target_languageslistRequired - The languages to dub the source media asset to.One or more of:
af,sq,am,ar,ar-DZ,ar-BH,ar-EG,ar-IQ,ar-JO,ar-KW, and 139 more. - Lipsync enabled
lipsync_enabledtrue/false - Whether to enable lipsync for the dubbed video.
- Burned in captions enabled
burned_in_captions_enabledtrue/false - Whether to burn captions into the dubbed video. Applies to every dubbed video created by this request. The captions.srt and captions.vtt files are still returned either way.
- Video duration
video_durationtext - The duration of the video to create.One of:
adaptive,original. - Visibility
visibilitytext - The visibility of the dubbed video.One of:
private,public. - Source asset ID
source_asset_idtext - The ID of the source media asset to create the dubbed video from.
- Source language
source_languagetext - The language of the source media asset.One of:
af,sq,am,ar,ar-DZ,ar-BH,ar-EG,ar-IQ,ar-JO,ar-KW, and 159 more. - Source video URL
source_video_urltext - The public URL where the video to dub is available. At the moment only supporting s3 signed urls
Outputs
responseobject- Response.
Example output
{
"response": {
"createdImportedAsset": {
"id": "123e4567-e89b-42d3-a456-426614174000"
}
}
}Create a video
Create a video in your Synthesia account.
Inputs
- Folder ID
folder_idtext - Optional folder ID. If provided, the new video will be created under this folder and inherit its permissions.
- Aspect ratio
aspect_ratiotext - Aspect ratio of the video. Default is landscape (16:9).One of:
16:9,9:16,1:1,4:5,5:4. - Cta settings
cta_settingsobject - Settings for a call-to-action button.
- Callback ID
callback_idtext - Use callback ID to link videos 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 can tell who the video is for, once its generated..
- Description
descriptiontext - Description of the video to be shown on the share page.
- Input
inputlistRequired - 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.
- Soundtrack
soundtracktext - soundtrack option is supported for backward compatibility. You should use the templates functionality for rich videos.One of:
corporate,inspirational,modern,urban. - Sound settings
sound_settingsobject - Sound settings.
- Test
testtrue/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
titletext - Title of the video to be shown on the share page.
- Visibility
visibilitytext - Public videos will be visible to anyone with a share URL.One of:
private,public.
Outputs
responseobject- Response.
Example output
{
"response": {
"callbackId": "example",
"captions": {
"srt": "example",
"vtt": "example"
},
"contentProvenance": {
"c2pa": {
"claimGenerator": "example",
"signedAt": "example"
}
},
"createdAt": 1,
"ctaSettings": {
"label": "example",
"url": "example"
},
"description": "example",
"download": "example",
"duration": "example",
"id": "123e4567-e89b-42d3-a456-426614174000",
"lastUpdatedAt": 1,
"status": "complete",
"test": false,
"thumbnail": {
"gif": "example",
"image": "example"
},
"title": "example",
"visibility": "private"
}
}Create a video from a template
Create a video from a Synthesia template.
Inputs
- Folder ID
folder_idtext - Optional folder ID. If provided, the new video will be created under this folder and inherit its permissions.
- Callback ID
callback_idtext - A callback ID that you may attach to the Video object. This is useful in the scenario where you need to store additional metadata on the video.
- Cta settings
cta_settingsobject - Cta settings.
- Description
descriptiontext - Description of the video (used on the video's share page). Defaults to the template description.
- Template
template_idtextRequired - Unique identifier of the template from which to create this video. This may be retrieved from the templates page in STUDIO.
- Template data
template_dataobjectRequired - Template data.
- Test
testtrue/false - Describes if the video is a test video. Test videos do not count towards your quota but are rendered with a watermark.
- Title
titletext - Title of the video (used on the video's share page). Defaults to the template title.
- Visibility
visibilitytext - Describes the private settings of the video. - If public, the video's share page is active. - If private, the video's share page is not active; visitors will receive a 404 Not Found response.One of:
private,public. - Brand kit ID
brand_kit_idtext - Brand kit ID for the video. Defaults to 'workspace_default' if not set. Use 'no_brand_kit' for no branding, or a UUID for a custom brand kit.
Outputs
responseobject- Response.
Example output
{
"response": {
"callbackId": "example",
"captions": {
"srt": "example",
"vtt": "example"
},
"contentProvenance": {
"c2pa": {
"claimGenerator": "example",
"signedAt": "example"
}
},
"createdAt": 1,
"ctaSettings": {
"label": "example",
"url": "example"
},
"description": "example",
"download": "example",
"duration": "example",
"id": "123e4567-e89b-42d3-a456-426614174000",
"lastUpdatedAt": 1,
"status": "complete",
"test": false,
"thumbnail": {
"gif": "example",
"image": "example"
},
"title": "example",
"visibility": "private"
}
}Create a Webhook
Create a webhook that sends the events you choose to a web address.
Inputs
- Events
eventslistRequired - [The webhook events](https://docs.synthesia.io/reference/webhook-events) for which notifications should be sent.One or more of:
video.completed,video.failed. - URL
urltextRequired - The URL to send notifications to
Outputs
responseobject- Response.
Example output
{
"response": {
"createdAt": {},
"id": "example",
"lastUpdatedAt": {},
"secret": "example",
"status": {},
"url": "example"
}
}Create media asset
Upload a media asset, either as a file or from a web address. For now, assets are only used for dubbing.
Inputs
- Content type
content_typetextRequired - The content type of the asset to upload. Must be one of: video/mp4, video/webm, or video/quicktime.One of:
video/mp4,video/webm,video/quicktime. - Configuration
configurationobjectRequired - Public API configuration for dubbing assets.
- Content length
content_lengthnumber - The length of the file content to upload. This is used to verify the integrity of the asset during upload.
- Content m d5
content_m_d5text - The MD5 hash of the file content to upload. This is used to verify the integrity of the asset during upload.
- Title
titletext - The title of the asset to upload.
Outputs
responseobject- Response.
Example output
{
"response": {
"id": "example",
"uploadCredentials": {
"accessKeyId": "example",
"bucket": "example",
"key": "example",
"secretAccessKey": "example",
"sessionToken": "example"
},
"uploadUrl": "example"
}
}Delete a video
Delete a video.
Inputs
- Video ID
video_idtextRequired - The id of the video to delete.
Outputs
responseobject- Response.
Example output
{
"response": {}
}Delete a webhook
Delete a webhook.
Inputs
- Webhook ID
webhook_idtextRequired - The unique identifier of the webhook to delete.
Outputs
responseobject- Response.
Example output
{
"response": {}
}Get a template
Get a template, including the variables you can customise.
Inputs
- Template
template_idtextRequired - The ID of the template to be retrieved.
Outputs
responseobject- Response.
Example output
{
"response": {
"brandKitId": "example",
"callbackId": "example",
"createdAt": 1,
"ctaSettings": {
"label": "example",
"url": "example"
},
"description": "example",
"download": "example",
"duration": "example",
"id": "123e4567-e89b-42d3-a456-426614174000",
"lastUpdatedAt": 1,
"templateData": {},
"templateId": "123e4567-e89b-42d3-a456-426614174000",
"test": false,
"title": "example",
"variables": [],
"visibility": "private"
}
}Get a video
Get a video and its status.
Inputs
- Video ID
video_idtextRequired - The video ID to retrieve
- Include rejected
include_rejectedtrue/false - When true, a video rejected by content moderation is returned with a rejected status instead of a 404 response. Defaults to false.
Outputs
responseobject- Response.
Example output
{
"response": {
"callbackId": "example",
"captions": {
"srt": "example",
"vtt": "example"
},
"contentProvenance": {
"c2pa": {
"claimGenerator": "example",
"signedAt": "example"
}
},
"createdAt": 1,
"ctaSettings": {
"label": "example",
"url": "example"
},
"description": "example",
"download": "example",
"duration": "example",
"id": "123e4567-e89b-42d3-a456-426614174000",
"lastUpdatedAt": 1,
"status": "complete",
"test": false,
"thumbnail": {
"gif": "example",
"image": "example"
},
"title": "example",
"visibility": "private"
}
}Get a webhook
Get a webhook and its status.
Inputs
- Webhook ID
webhook_idtextRequired - The unique identifier of the webhook to retrieve.
Outputs
responseobject- Response.
Example output
{
"response": {
"createdAt": {},
"id": "example",
"lastUpdatedAt": {},
"secret": "example",
"status": {},
"url": "example"
}
}Get dubbing project status and videos
Get a dubbing project's status (uploading, in progress, complete or error) and its dubbed videos. Each dubbed video has download links once it is complete, and a project that failed returns its error code.
Inputs
- Dubbing project ID
dubbing_project_idtextRequired - UUID of the dubbing project (original imported video)
- Target languages
target_languageslist - Optional list of language codes to filter dubbed videos (e.g., es, fr, de)
Outputs
responseobject- Response.
Example output
{
"response": {
"dubbedAssets": [],
"errorCode": "moderation",
"id": "123e4567-e89b-42d3-a456-426614174000",
"status": "error"
}
}Get supported languages for translations
List the languages videos can be translated into.
Inputs
None.
Outputs
responseobject- Response.
Example output
{
"response": {}
}Get user media asset
Get a media asset you uploaded, with its status, title, content type and details such as its detected language when available. For now, this only covers assets uploaded for dubbing.
Inputs
- User media asset ID
user_media_asset_idtextRequired - The unique identifier of the media asset to retrieve.
Outputs
responseobject- Response.
Example output
{
"response": {
"contentType": "image/webp",
"errorCode": "asset_upload",
"id": "example",
"metadata": {
"detectedLanguage": "af"
},
"status": "awaiting_upload",
"title": "example"
}
}Get video translations of a given root video id
Get a video's translation status in each language: complete, in progress or error. A language that was started again shows as in progress.
Inputs
- Root video ID
root_video_idtextRequired - The ID of the studio video.
Outputs
responseobject- Response.
Example output
{
"response": {
"id": "123e4567-e89b-42d3-a456-426614174000",
"translations": []
}
}List templates
List your Synthesia templates, with the variables you can fill in for each. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Limit
limitnumber - This parameter lets you specify the amount of videos to return in your API call. The maximum amount of videos you can have returned to you via this parameter is 100.From 1.0 to 100.0.
- Offset
offsetnumber - Used to page through the videos. Every call to this endpoint will return the next offset value. This value is used in the offset parameter of the next call to get the next page of videos.At least 0.0.
- Source
sourcelist - Filter templates by source. Possible values: synthesia, workspace, shared_with_meOne or more of:
workspace,synthesia.
Outputs
responseobject- Response.
Example output
{
"response": {
"nextOffset": 1,
"templates": []
}
}List videos
List the videos created in Synthesia or through the API. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Limit
limitnumber - This parameter lets you specify the amount of videos to return in your API call. The maximum amount of videos you can have returned to you via this parameter is 100.From 1.0 to 100.0.
- Offset
offsetnumber - Used to page through the videos. Every call to this endpoint will return the next offset value. This value is used in the offset parameter of the next call to get the next page of videos.At least 0.0.
- Source
sourcelist - Filter videos by source. Possible values: workspace, shared_with_me, my_videosOne or more of:
workspace,shared_with_me(shared with me),my_videos(my videos).
Outputs
responseobject- Response.
Example output
{
"response": {
"nextOffset": 1,
"videos": []
}
}List webhooks
List all currently configured webhooks in your Synthesia account. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Limit
limitnumber - This parameter lets you specify the amount of webhooks to return in your API call. The maximum amount of webhooks you can have returned to you via this parameter is 100.From 1.0 to 100.0.
- Offset
offsetnumber - Used to page through the webhooks. Every call to this endpoint will return the next offset value. This value is used in the offset parameter of the next call to get the next page of webhooks.At least 0.0.
- Deleted
deletedtrue/false - If true, fetches deleted webhooks rather than active ones.
Outputs
responseobject- Response.
Example output
{
"response": {
"nextOffset": 1,
"webhooks": []
}
}Query audit log events
List audit log events for a workspace or an organization; give exactly one of the two. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Workspace ID
workspace_idtext - Workspace UUID to filter events by (mutually exclusive with organizationId)
- Organization ID
organization_idtext - Organization UUID to filter events by (mutually exclusive with workspaceId)
- Actions
actionstext - Comma-separated list of actions to filter by (e.g. "billing.credits.consumed,dubbing.project.created")
- Actor IDS
actor_idstext - Comma-separated list of actor IDs to filter by (e.g. "user-123,user-456")
- Target ID
target_idtext - Filter events by target ID
- Start date
start_datedate and time - Filter events created on or after this Unix timestamp (seconds since epoch)
- End date
end_datedate and time - Filter events created before this Unix timestamp (seconds since epoch)
- Cursor
cursortext - Opaque cursor for pagination
- Limit
limitnumber - Number of events per page (max 200)From 1.0 to 200.0.
Outputs
responseobject- Paginated response for audit logs listing. Used for both INTERNAL and PUBLIC APIs INTERNAL API: POST /auditLogs/events PUBLIC API: POST /v2/auditLogs/events
Example output
{
"response": {
"events": [],
"hasMore": false,
"nextCursor": "example"
}
}Search audit log events (Advanced)
Search audit log events using detailed filters.
Inputs
- Workspace ID
workspace_idtext - Workspace id.
- Organization ID
organization_idtext - Organization id.
- Start date
start_datedate and time - Start date.
- End date
end_datedate and time - End date.
- Actions
actionslist - Actions.
- Actor IDS
actor_idslist - Actor ids.
- Target ID
target_idtext - Target id.
- Cursor
cursortext - Cursor.
- Limit
limitnumber - Limit.From 1.0 to 200.0.
Outputs
responseobject- Paginated response for audit logs listing. Used for both INTERNAL and PUBLIC APIs INTERNAL API: POST /auditLogs/events PUBLIC API: POST /v2/auditLogs/events
Example output
{
"response": {
"events": [],
"hasMore": false,
"nextCursor": "example"
}
}Start/Update a video translation
Start translating a video into each language you choose. Returns every translation, each showing whether this request started it or it was already in progress.
Inputs
- Root video ID
root_video_idtextRequired - The ID of the studio video to translate.
- Target languages
target_languageslistRequired - List of language codes to translate the video into. See https://docs.synthesia.io/docs/supported-languages for accepted values.
- Translate script only
translate_script_onlytrue/false - If true, only the script is translated.
- Auto generate
auto_generatetext - Automatically generate the translated video after translation completes. Set to 'private' to generate without sharing publicly, or 'public' to generate and publish immediately.One of:
private,public.
Outputs
responseobject- Response.
Example output
{
"response": {
"id": "123e4567-e89b-42d3-a456-426614174000",
"translations": []
}
}Update a video
Change a video's title or description, or make it public so anyone can watch it on its share page.
Inputs
- Video ID
video_idtextRequired - The ID of the video to update
- Cta settings
cta_settingsobject - Cta settings.
- Description
descriptiontext - Description.
- Title
titletext - Title.
- Visibility
visibilitytext - Visibility.One of:
private,public.
Outputs
responseobject- Response.
Example output
{
"response": {
"callbackId": "example",
"captions": {
"srt": "example",
"vtt": "example"
},
"contentProvenance": {
"c2pa": {
"claimGenerator": "example",
"signedAt": "example"
}
},
"createdAt": 1,
"ctaSettings": {
"label": "example",
"url": "example"
},
"description": "example",
"download": "example",
"duration": "example",
"id": "123e4567-e89b-42d3-a456-426614174000",
"lastUpdatedAt": 1,
"status": "complete",
"test": false,
"thumbnail": {
"gif": "example",
"image": "example"
},
"title": "example",
"visibility": "private"
}
}