Synthesia

App · 22 actions

Create and manage avatar videos, templates, dubbing projects, translations, assets and webhooks.

Actions

ActionWhat 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 assetCreate a dubbing project from an uploaded video.
Create a videoCreate a video in your Synthesia account.
Create a video from a templateCreate a video from a Synthesia template.
Create a WebhookCreate a webhook that sends the events you choose to a web address.
Create media assetUpload a media asset, either as a file or from a web address.
Delete a videoDelete a video.
Delete a webhookDelete a webhook.
Get a templateGet a template, including the variables you can customise.
Get a videoGet a video and its status.
Get a webhookGet a webhook and its status.
Get dubbing project status and videosGet a dubbing project's status (uploading, in progress, complete or error) and its dubbed videos.
Get supported languages for translationsList the languages videos can be translated into.
Get user media assetGet 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 idGet a video's translation status in each language: complete, in progress or error.
List templatesList your Synthesia templates, with the variables you can fill in for each.
List videosList the videos created in Synthesia or through the API.
List webhooksList all currently configured webhooks in your Synthesia account.
Query audit log eventsList 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 translationStart translating a video into each language you choose.
Update a videoChange 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 IDdubbing_project_idtextRequired
UUID of the dubbing project (original imported video)
Target languagestarget_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 enabledlipsync_enabledtrue/false
Whether to enable lipsync for the dubbed video.
Burned in captions enabledburned_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 durationvideo_durationtext
The duration of the video to create.One of: adaptive, original.
Visibilityvisibilitytext
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

TitletitletextRequired
The title of the dubbed video to create.
Target languagestarget_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 enabledlipsync_enabledtrue/false
Whether to enable lipsync for the dubbed video.
Burned in captions enabledburned_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 durationvideo_durationtext
The duration of the video to create.One of: adaptive, original.
Visibilityvisibilitytext
The visibility of the dubbed video.One of: private, public.
Source asset IDsource_asset_idtext
The ID of the source media asset to create the dubbed video from.
Source languagesource_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 URLsource_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 IDfolder_idtext
Optional folder ID. If provided, the new video will be created under this folder and inherit its permissions.
Aspect ratioaspect_ratiotext
Aspect ratio of the video. Default is landscape (16:9).One of: 16:9, 9:16, 1:1, 4:5, 5:4.
Cta settingscta_settingsobject
Settings for a call-to-action button.
Callback IDcallback_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..
Descriptiondescriptiontext
Description of the video to be shown on the share page.
InputinputlistRequired
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.
Soundtracksoundtracktext
soundtrack option is supported for backward compatibility. You should use the templates functionality for rich videos.One of: corporate, inspirational, modern, urban.
Sound settingssound_settingsobject
Sound settings.
Testtesttrue/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.
Titletitletext
Title of the video to be shown on the share page.
Visibilityvisibilitytext
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 IDfolder_idtext
Optional folder ID. If provided, the new video will be created under this folder and inherit its permissions.
Callback IDcallback_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 settingscta_settingsobject
Cta settings.
Descriptiondescriptiontext
Description of the video (used on the video's share page). Defaults to the template description.
Templatetemplate_idtextRequired
Unique identifier of the template from which to create this video. This may be retrieved from the templates page in STUDIO.
Template datatemplate_dataobjectRequired
Template data.
Testtesttrue/false
Describes if the video is a test video. Test videos do not count towards your quota but are rendered with a watermark.
Titletitletext
Title of the video (used on the video's share page). Defaults to the template title.
Visibilityvisibilitytext
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 IDbrand_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

EventseventslistRequired
[The webhook events](https://docs.synthesia.io/reference/webhook-events) for which notifications should be sent.One or more of: video.completed, video.failed.
URLurltextRequired
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 typecontent_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.
ConfigurationconfigurationobjectRequired
Public API configuration for dubbing assets.
Content lengthcontent_lengthnumber
The length of the file content to upload. This is used to verify the integrity of the asset during upload.
Content m d5content_m_d5text
The MD5 hash of the file content to upload. This is used to verify the integrity of the asset during upload.
Titletitletext
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 IDvideo_idtextRequired
The id of the video to delete.

Outputs

responseobject
Response.
Example output
{
  "response": {}
}

Delete a webhook

Delete a webhook.

Inputs

Webhook IDwebhook_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

Templatetemplate_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 IDvideo_idtextRequired
The video ID to retrieve
Include rejectedinclude_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 IDwebhook_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 IDdubbing_project_idtextRequired
UUID of the dubbing project (original imported video)
Target languagestarget_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 IDuser_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 IDroot_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

Limitlimitnumber
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.
Offsetoffsetnumber
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.
Sourcesourcelist
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

Limitlimitnumber
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.
Offsetoffsetnumber
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.
Sourcesourcelist
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

Limitlimitnumber
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.
Offsetoffsetnumber
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.
Deleteddeletedtrue/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 IDworkspace_idtext
Workspace UUID to filter events by (mutually exclusive with organizationId)
Organization IDorganization_idtext
Organization UUID to filter events by (mutually exclusive with workspaceId)
Actionsactionstext
Comma-separated list of actions to filter by (e.g. "billing.credits.consumed,dubbing.project.created")
Actor IDSactor_idstext
Comma-separated list of actor IDs to filter by (e.g. "user-123,user-456")
Target IDtarget_idtext
Filter events by target ID
Start datestart_datedate and time
Filter events created on or after this Unix timestamp (seconds since epoch)
End dateend_datedate and time
Filter events created before this Unix timestamp (seconds since epoch)
Cursorcursortext
Opaque cursor for pagination
Limitlimitnumber
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 IDworkspace_idtext
Workspace id.
Organization IDorganization_idtext
Organization id.
Start datestart_datedate and time
Start date.
End dateend_datedate and time
End date.
Actionsactionslist
Actions.
Actor IDSactor_idslist
Actor ids.
Target IDtarget_idtext
Target id.
Cursorcursortext
Cursor.
Limitlimitnumber
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 IDroot_video_idtextRequired
The ID of the studio video to translate.
Target languagestarget_languageslistRequired
List of language codes to translate the video into. See https://docs.synthesia.io/docs/supported-languages for accepted values.
Translate script onlytranslate_script_onlytrue/false
If true, only the script is translated.
Auto generateauto_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 IDvideo_idtextRequired
The ID of the video to update
Cta settingscta_settingsobject
Cta settings.
Descriptiondescriptiontext
Description.
Titletitletext
Title.
Visibilityvisibilitytext
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"
  }
}

On this page