Synthesia API

https://docs.synthesia.io/reference/
Admin
Synthesia API enables developers to integrate AI-powered video creation into applications, automate...
Tokens:70,208
Snippets:453
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Synthesia Dubbing CLI: Fresh Run Example

Source: https://docs.synthesia.io/reference/upload-large-files-via-temporary-aws-credentials

Perform a fresh dubbing run, ignoring any previously saved state. This is useful for re-processing files or ensuring a clean start.

```shell
python synthesia_dub.py \
 --api-key "<SYNTHESIA_API_KEY>" \
 --path "/abs/path/to/folder" \
 --targets "de-DE" \
 --force-new
```

--------------------------------

### Upload Script Audio Request Body Example

Source: https://docs.synthesia.io/reference/upload-script-audio

This example shows the expected JSON response when script audio is successfully uploaded. The response contains the unique ID of the uploaded asset.

```json
{
  "id": "ac1ea9ed-1337-4969-a9fe-XXXXXX"
}
```

--------------------------------

### Video Completed Event Data Example

Source: https://docs.synthesia.io/reference/webhook-events

An example of the data payload for a 'video.completed' event. This includes fields like callbackId, captions, createdAt, download URL, duration, and video status.

```json
{
  "data": {
    "callbackId": "john@example.com",
    "captions": {

```

--------------------------------

### Synthesia Dubbing CLI: Single File Example

Source: https://docs.synthesia.io/reference/upload-large-files-via-temporary-aws-credentials

Use this command to dub a single video file. Ensure you replace placeholders with your actual API key and file path.

```shell
python synthesia_dub.py \
 --api-key "<SYNTHESIA_API_KEY>" \
 --path "/abs/path/to/video.mp4" \
 --targets "fr-FR,es-ES" \
 --source-language "en"
```

--------------------------------

### AuditLogEvent Example Response

Source: https://docs.synthesia.io/reference/search-audit-log-events

An example of a single audit log event, showing all fields including actor, target, context, details, and metadata.

```json
{
    "id": "256eb609-72cb-4d42-a7a3-59a65d4e6726",
    "action": "user.authentication.login",
    "status": "success",
    "actor": {
        "type": "user",
        "id": "93d3f26c-8bb1-4759-b0c7-eef01cb0321b",
        "name": "local user",
        "email": "dev_user@synthesia.io"
    },
    "target": {
        "type": "user",
        "id": "93d3f26c-8bb1-4759-b0c7-eef01cb0321b",
        "name": "local user"
    },
    "context": {
        "workspaceId": "b93d1427-06d8-412a-b158-6280e68b54d5",
        "organizationId": null,
        "ipAddress": null
    },
    "details": {
        "authMethod": "username_password",
        "isImpersonation": false,
        "emailVerified": true,
        "emailDomain": "synthesia.io",
        "company": "Synthesia"
    },
    "metadata": {
        "createdAt": "2025-10-05T06:58:28.321Z",
        "processedAt": "2025-10-05T06:58:28.322Z"
    }
}
```

--------------------------------

### Retrieve Audit Log Events Filtered by Action and Date

Source: https://docs.synthesia.io/reference/retrieve-audit-log-events

This example shows how to filter audit log events by a specific action and a date range. Unix timestamps are required for the start and end dates.

```http
GET /v2/auditLogs/events?workspaceId=12345678-1234-1234-1234-123456789abc
&actions=billing.credits.consumed&startDate=1704067200&endDate=1706745599
```

--------------------------------

### Synthesia Dubbing CLI: Folder Recursive Example

Source: https://docs.synthesia.io/reference/upload-large-files-via-temporary-aws-credentials

Dub all video files within a specified folder and its subdirectories. The `--recursive` flag is enabled by default.

```shell
python synthesia_dub.py \
 --api-key "<SYNTHESIA_API_KEY>" \
 --path "/abs/path/to/folder" \
 --targets "fr-FR,es-ES" \
 --source-language "en"
```

--------------------------------

### Start Dubbing Job

Source: https://docs.synthesia.io/reference/upload-large-files-via-temporary-aws-credentials

Initiates a dubbing job for a Synthesia asset, specifying source and target languages. Returns the ID of the created imported asset.

```python
def start_dubbing(api_key: str, asset_id: str, src_lang: str, targets: list, title: str) -> str:
    payload = {
        "sourceLanguage": src_lang,
        "targetLanguages": targets,
        "lipsyncEnabled": False,
        "videoDuration": "adaptive",
        "visibility": "private",
        "title": f"{title} (dubbed)" if title else "Dubbed video",
        "sourceAssetId": asset_id,
    }
    log(f"Starting dubbing job for {len(targets)} target(s)…")
    r = requests.post(
        "https://api.synthesia.io/v2/dubbing",
        headers={
            "Authorization": api_key,
            "accept": "application/json",
            "content-type": "application/json",
        },
        json=payload,
        timeout=60,
    )
    if r.status_code != 202:
        raise RuntimeError(f"[Start dubbing] {r.status_code}: {r.text}")
    data = r.json()
    imported_id = data["createdImportedAsset"]["id"]
    log(f"Dubbing started: imported_id={imported_id}")
    return imported_id
```

--------------------------------

### Start/Update Video Translation

Source: https://docs.synthesia.io/reference/put_v2-translations-root-video-id

Initiates the translation workflow for a video in specified target languages. If a translation is already in progress, it will not be restarted. Returns a list of all translations for the video, including a flag indicating if the workflow was started by this request.

```APIDOC
## PUT /v2/translations/root/{video_id}

### Description
Starts or updates the translation workflow for a given video in specified target languages. Returns a unified `translations` list where each entry includes a `startedByRequest` flag.

### Method
PUT

### Endpoint
`/v2/translations/root/{video_id}`

### Parameters
#### Path Parameters
- **video_id** (string) - Required - The ID of the video for which to start or update translations.

#### Request Body
- **target_languages** (array[string]) - Required - A list of language codes for the desired translations.

### Request Example
```json
{
  "target_languages": ["en", "es", "fr"]
}
```

### Response
#### Success Response (200)
- **translations** (array[object]) - A list of translation objects.
  - **language** (string) - The language code of the translation.
  - **startedByRequest** (boolean) - `true` if the workflow was started by this request, `false` if it was already in progress.

#### Response Example
```json
{
  "translations": [
    {
      "language": "en",
      "startedByRequest": true
    },
    {
      "language": "es",
      "startedByRequest": false
    }
  ]
}
```
```

--------------------------------

### Synthesia Dubbing CLI: Top-Level Folder Only Example

Source: https://docs.synthesia.io/reference/upload-large-files-via-temporary-aws-credentials

Dub only video files directly within the specified folder, ignoring subdirectories. Use the `--no-recursive` flag to disable recursion.

```shell
python synthesia_dub.py \
 --api-key "<SYNTHESIA_API_KEY>" \
 --path "/abs/path/to/folder" \
 --targets "fr-FR,es-ES" \
 --no-recursive
```

--------------------------------

### Create Video

Source: https://docs.synthesia.io/reference/create-video

Creates a new video with specified parameters. This includes setting the aspect ratio, title, description, input clips, and visibility.

```APIDOC
## POST /videos

### Description
Creates a new video with specified parameters. This includes setting the aspect ratio, title, description, input clips, and visibility.

### Method
POST

### Endpoint
/videos

### Parameters
#### Request Body
- **folderId** (string) - Optional - Optional folder ID. If provided, the new video will be created under this folder and inherit its permissions.
- **aspectRatio** (string) - Optional - Aspect ratio of the video. Default is `landscape (16:9)`. Enum: `16:9`, `9:16`, `1:1`, `4:5`, `5:4`.
- **ctaSettings** (object) - Optional - Settings for a call-to-action button.
- **callbackId** (string) - Optional - 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** (string) - Optional - Description of the video to be shown on the share page.
- **input** (array) - Required - 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** (string) - Optional - soundtrack option is supported for backward compatibility. You should use the templates functionality for rich videos. Enum: `corporate`, `inspirational`, `modern`, `urban`.
- **soundSettings** (object) - Optional - 
- **test** (boolean) - Optional - 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** (string) - Optional - Title of the video to be shown on the share page.
- **visibility** (string) - Optional - Public videos will be visible to anyone with a share URL. 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. Enum: `private`, `public`.

### Request Example
{
  "example": "request body"
}

### Response
#### Success Response (200)
- **description** (string) - Description of the video to be shown on the share page.
- **test** (boolean) - 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.
- **download** (string) - 
- **duration** (string) - 
- **id** (string) - 
- **lastUpdatedAt** (integer) - 
- **status** (string) - Enum: `complete`, `deleted`, `error`, `in_progress`, `rejected`, `approved`
- **thumbnail** (object) - 
- **title** (string) - Title of the video to be shown on the share page.
- **visibility** (string) - Enum: `private`, `public`.

#### Response Example
{
  "example": "response body"
}
```

--------------------------------

### Create Dubbing Project

Source: https://docs.synthesia.io/reference/create-a-dubbing-project

Creates a dubbing project from an uploaded video asset or a video URL. The video URL option is a beta feature and requires specific workspace access.

```APIDOC
## POST /v2/dubbing

### Description
Use this endpoint to create a dubbing project from an uploaded video asset or a video URL. The `sourceVideoUrl` option is a beta feature and may not be available to all workspaces.

### Method
POST

### Endpoint
https://api.synthesia.io/v2/dubbing

### Parameters
#### Request Body
- **schema**: oneOf - Requires either `CreateDubbingProjectApiRequestFromSourceAssetId` or `CreateDubbingProjectApiRequestFromSourceVideoUrl`.
  - **title**: Create from uploaded asset
  - **description**: Create a dubbing project from a previously uploaded video asset
  - **title**: Create from video URL (BETA)
  - **description**: 🚧 **BETA**: Create a dubbing project directly from a video URL. Only available to selected workspaces. Using without access will return a `403 Forbidden` error. Contact support for access.

### Responses
#### Success Response (202 Accepted)
- **schema**: `CreateDubbingProjectApiResponseSuccess` - Dubbing project created successfully.

#### Error Responses
- **400 Bad Request**: Failed to create dubbing project. This can occur when:
  - The request validation fails
  - The source asset video URL is broken or inaccessible
  - There are errors creating the dubbed videos
  - **schema**: `CreateDubbingProjectApiResponseFail` or an object with `context` and `error` fields.
- **403 Forbidden**: Wrong API key.
  - **schema**: `Error`
- **404 Not Found**: Asset ID was not found.
  - **schema**: `Error`
- **501 Not Implemented**: Only S3 related URLs are supported at the moment.
  - **schema**: Object with an `error` field.
- **default**: Unexpected Server error.
  - **schema**: `Error`
```

--------------------------------

### Video Creation Parameters

Source: https://docs.synthesia.io/reference/create-video

This section details the parameters available when creating a video, covering avatar, background, and sound configurations.

```APIDOC
## Video Creation Parameters

### Description
This endpoint allows for the creation of videos with detailed customization options for avatars, backgrounds, and audio.

### Parameters
#### Avatar Settings
- **style** (string) - Required - Specifies the avatar style. `rectangular` corresponds to "Full body" and `circular` corresponds to "Circle" in STUDIO. Circular avatars are fixed to the center and scale 1.0 covers the full video height.
- **voice** (uuid) - Optional - The ID of the voice to use. If not provided, a default voice is assigned, which may change. Explicitly providing a `voiceId` ensures consistent output.
- **seamless** (boolean) - Optional - Enables seamless video concatenation by matching first and last frames. Only works with specific actors (`anna_costume1_cameraA`, `mia_costume1_cameraA`) and static backgrounds. May result in lower video quality.

#### Background Settings
- **position** (object) - Optional - Defines the position of the background with `x` and `y` integer coordinates.
- **scale** (number) - Optional - The scale of the background. Defaults to 1.
- **videoSettings** (object) - Optional - Settings for video backgrounds.
  - **trim** (object) - Optional - Specifies `startTime` and `endTime` for trimming the background video.
  - **shortBackgroundContentMatchMode** (string) - Optional - How to handle short content with the background. Options: `freeze`, `loop`, `slow_down`. Defaults to `freeze`.
  - **longBackgroundContentMatchMode** (string) - Optional - How to handle long content with the background. Options: `extend_content`, `trim`, `speed_up`. Defaults to `trim`.
  - **volume** (number) - Optional - The volume of the background video. Must be between 0 and 1.

#### Sound Settings
- **soundtrackVolume** (number) - Optional - The volume of the soundtrack.
```

--------------------------------

### Start/Update a video translation

Source: https://docs.synthesia.io/reference/put_v2-translations-root-video-id

Initiates the TranslateVideoWorkflow for specified target languages. This endpoint allows you to start new translations or check the status of ongoing ones. It returns a list of translations, indicating whether each was newly started or already in progress.

```APIDOC
## PUT /v2/translations/{root_video_id}

### Description
Start or update a video translation by initiating the TranslateVideoWorkflow for each requested target language. The response includes a `translations` list, with each entry having a `startedByRequest` flag indicating if the workflow was initiated by this request or was already running.

### Method
PUT

### Endpoint
/v2/translations/{root_video_id}

### Parameters
#### Path Parameters
- **root_video_id** (string) - Required - The ID of the studio video to translate.

#### Request Body
- **targetLanguages** (array of strings) - Required - List of language codes to translate the video into. See https://docs.synthesia.io/docs/supported-languages for accepted values.
- **translateScriptOnly** (boolean) - Optional - If true, only the script is translated. Defaults to false.

### Request Example
```json
{
  "targetLanguages": [
    "es",
    "fr"
  ],
  "translateScriptOnly": false
}
```

### Response
#### Success Response (202)
- **translations** (array) - A list of translation workflows, each with language, status, step, and `startedByRequest` flag.

#### Response Example
```json
{
  "translations": [
    {
      "language": "es",
      "status": "in_progress",
      "step": "translation",
      "startedByRequest": true
    },
    {
      "language": "fr",
      "status": "in_progress",
      "step": "translation",
      "startedByRequest": false
    }
  ]
}
```

#### Error Response (400, 403, 404, default)
- **error** (object) - Contains details about the error.

#### Error Response Example
```json
{
  "error": {
    "code": "string",
    "message": "string"
  }
}
```
```

--------------------------------

### Get Supported Languages

Source: https://docs.synthesia.io/reference/get-supported-languages-for-translations

Fetches a list of languages supported for translation.

```APIDOC
## GET /v1/languages/translations

### Description
Retrieves a list of all languages supported for translation.

### Method
GET

### Endpoint
/v1/languages/translations

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **languages** (array) - A list of supported language objects.
  - **language_id** (string) - The unique identifier for the language.
  - **language_name** (string) - The human-readable name of the language.

#### Response Example
{
  "languages": [
    {
      "language_id": "en",
      "language_name": "English"
    },
    {
      "language_id": "es",
      "language_name": "Spanish"
    }
  ]
}
```

--------------------------------

### Create Video from Template

Source: https://docs.synthesia.io/reference/create-a-video-from-a-template

Creates a new video based on a specified template. You can customize the video's title, description, and other properties. Test videos are free but include a watermark.

```APIDOC
## POST /videos

### Description
Creates a new video from a specified template. This endpoint allows for customization of video content and settings.

### Method
POST

### Endpoint
/videos

### Parameters
#### Request Body
- **templateId** (string) - Required - Unique identifier of the template from which to create this video.
- **templateData** (object) - Required - Data to populate the template.
- **folderId** (string) - Optional - Folder ID to place the new video.
- **callbackId** (string) - Optional - Callback ID for metadata.
- **ctaSettings** (object) - Optional - Call to action settings.
- **description** (string) - Optional - Description of the video.
- **test** (boolean) - Optional - If true, creates a test video with a watermark (does not count towards quota).
- **title** (string) - Optional - Title of the video.
- **visibility** (string) - Optional - Visibility setting ('private' or 'public'). Defaults to 'private'.
- **brandKitId** (string) - Optional - Brand kit ID for the video. Defaults to 'workspace_default'.
```

--------------------------------

### Create Dubbing Project from Source Video URL

Source: https://docs.synthesia.io/reference/create-a-dubbing-project

Creates a new dubbing project using a provided video URL. The API processes the video to prepare it for dubbing into the specified target languages.

```APIDOC
## POST /dubbing/projects

### Description
Creates a new dubbing project from a source video URL.

### Method
POST

### Endpoint
/dubbing/projects

### Parameters
#### Request Body
- **title** (string) - Required - The title of the dubbing project.
- **targetLanguages** (array of strings) - Required - A list of languages to dub the video into.
- **sourceVideoUrl** (string) - Required - The URL of the source video.
- **sourceLanguage** (string) - Optional - The language of the source media asset. If not specified, the language will be detected automatically.

### Request Example
```json
{
  "title": "My Dubbing Project",
  "targetLanguages": ["es", "fr"],
  "sourceVideoUrl": "https://example.com/video.mp4",
  "sourceLanguage": "en"
}
```

### Response
#### Success Response (200 OK)
- **createdImportedAsset** (object) - Contains the ID of the created imported asset.
  - **id** (string) - The unique identifier of the created imported asset.

#### Response Example
```json
{
  "createdImportedAsset": {
    "id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

#### Error Response (4xx/5xx)
- **dubbedErrors** (array of objects) - Errors related to the creation of the dubbed videos.
  - **error** (string) - The error type.
  - **language** (string) - The language of the error.

- **error** (string) - Required - A general error message.
- **context** (string) - Optional - Additional context for the error.
```

--------------------------------

### Get Public API User Uploaded Asset Response

Source: https://docs.synthesia.io/reference/get-user-media-asset

This schema defines the structure of the response when retrieving details of a user-uploaded asset.

```APIDOC
## Get Public API User Uploaded Asset Response

### Description
Retrieves details about a user-uploaded asset.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the asset.
- **title** (string) - The title of the user uploaded asset.
- **contentType** (AssetContentType) - The content type of the user uploaded asset.
- **status** (PublicApiUserUploadedAssetStatus) - The status of the user uploaded asset.
- **metadata** (GetPublicApiMediaAssetMetadataResponse) - Metadata associated with the user uploaded asset.
```

--------------------------------

### Create Video

Source: https://docs.synthesia.io/reference/create-video

This endpoint allows you to create a video by specifying various parameters such as avatar, background, and script details. You can use either text or pre-uploaded audio for the script. Advanced options for avatar and background settings are also available.

```APIDOC
## POST /videos

### Description
Creates a new video with specified parameters.

### Method
POST

### Endpoint
/videos

### Parameters
#### Request Body
- **input** (array) - Required - Array of inputs for the video.
  - **scriptText** (string) - Optional - The text content for the video's script.
  - **scriptAudio** (string) - Optional - The ID of an uploaded script audio file. If used, `scriptLanguage` must also be provided.
  - **scriptLanguage** (string) - Optional - The language code of the script audio. Format: `en-US`. Required if `scriptAudio` is used.
  - **background** (string) - Optional - Specifies the background for the video. Can be a stock background ID, a custom asset ID, a URL, or a predefined solid color.
  - **avatarSettings** (object) - Optional - Settings for the avatar.
    - **voice** (string) - Optional - The voice to be used for the avatar. If null, a default voice will be used.
    - **seamless** (boolean) - Optional - Whether to use seamless avatar transitions.
    - **style** (string) - Optional - The style of the avatar (e.g., "rectangular").
  - **backgroundSettings** (object) - Optional - Advanced settings for the video background.

### Request Example
```json
{
  "input": [
    {
      "scriptText": "Hello, this is a test video.",
      "background": "white_studio",
      "avatarSettings": {
        "voice": "en-US-Standard-C",
        "seamless": true,
        "style": "rectangular"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created video.
- **status** (string) - The current status of the video creation process.

#### Response Example
```json
{
  "id": "vid_abcdef123456",
  "status": "processing"
}
```
```

--------------------------------

### Create Dubbing Project from Source Video URL

Source: https://docs.synthesia.io/reference/create-a-dubbing-project

Creates a dubbing project from a video available at a public URL. This is useful for dubbing videos that are not yet uploaded as assets. Supports only S3 signed URLs.

```APIDOC
## POST /dubbing/projects/from-source-video-url

### Description
Creates a dubbing project from a video accessible via a public URL. Currently, only S3 signed URLs are supported as the source.

### Method
POST

### Endpoint
/dubbing/projects/from-source-video-url

### Parameters
#### Request Body
- **title** (string) - Required - The title of the dubbed video to create.
- **targetLanguages** (array) - Required - The languages to dub the source media asset to. Each element should be a valid `DubbingOutputLanguage`.
- **lipsyncEnabled** (boolean) - Optional - Whether to enable lipsync for the dubbed video. Defaults to `false`.
- **videoDuration** (string) - Optional - The duration of the video to create. Can be `adaptive` or `original`. Defaults to `adaptive`.
- **visibility** (string) - Optional - The visibility of the dubbed video. Can be `private` or `public`. Defaults to `private`.
- **sourceVideoUrl** (string) - Required - The public URL where the video to dub is available. At the moment only supporting s3 signed urls.

### Request Example
{
  "title": "My dubbed video from URL",
  "targetLanguages": [
    "de-DE",
    "fr-FR"
  ],
  "lipsyncEnabled": false,
  "videoDuration": "original",
  "visibility": "public",
  "sourceVideoUrl": "s3://your-signed-url"
}

### Response
#### Success Response (200)
(Response schema not provided in source)

#### Response Example
(Response example not provided in source)
```

--------------------------------

### GET /templates/{templateId}

Source: https://docs.synthesia.io/reference/retrieve-a-template

Retrieves a specific video template by its ID. This allows you to access details about the template, such as its title, visibility, and associated brand kit.

```APIDOC
## GET /templates/{templateId}

### Description
Retrieves a specific video template by its ID. This allows you to access details about the template, such as its title, visibility, and associated brand kit.

### Method
GET

### Endpoint
/templates/{templateId}

### Parameters
#### Path Parameters
- **templateId** (string) - Required - The unique identifier of the template to retrieve.

### Response
#### Success Response (200)
- **templateData** (object) - Contains the data associated with the template.
  - **title** (string) - The title of the video. Defaults to the template title.
  - **visibility** (string) - Describes the private settings of the video. Possible values: 'private', 'public'.
  - **brandKitId** (string) - The brand kit ID for the video. Defaults to 'workspace_default' or can be 'no_brand_kit'.
  - **download** (string) - Download information for the video.
  - **duration** (string) - The duration of the video.
  - **id** (string) - The unique identifier of the video (UUID).
  - **lastUpdatedAt** (integer) - The timestamp when the video was last updated.
  - **variables** (array) - An array of objects representing video variables.
- **templateId** (string) - The ID of the template.

#### Response Example
{
  "templateData": {
    "title": "My Awesome Video",
    "visibility": "public",
    "brandKitId": "uuid-of-brand-kit",
    "download": "some-download-info",
    "duration": "1:30",
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "lastUpdatedAt": 1678886400,
    "variables": [
      { "name": "name", "value": "John Doe" }
    ]
  },
  "templateId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}

#### Error Response (400 or 404)
- **error** (string) - A message describing the error.
- **context** (string) - Additional context about the error.
```

--------------------------------

### Get Supported Languages

Source: https://docs.synthesia.io/reference/get-supported-languages-for-translations

Fetches a list of all languages that are supported for video translations. This is useful for populating language selection dropdowns or validating user input.

```APIDOC
## GET /v2/translate/languages

### Description
Get a list of supported languages for translations.

### Method
GET

### Endpoint
https://api.synthesia.io/v2/translate/languages

### Parameters

### Request Example
(No request body or parameters specified)

### Response
#### Success Response (200)
- **(Array of strings)** - A list of language codes supported for translation.

#### Response Example
```json
[
  "en",
  "de",
  "es"
]
```

#### Error Response (403)
- **error** (string) - Description of the error.
- **context** (string) - Additional context for the error.

#### Error Response Example
```json
{
  "error": "Forbidden - Wrong API key."
}
```
```

--------------------------------

### Create Video

Source: https://docs.synthesia.io/reference/create-video

This endpoint allows you to create a new video. You can specify the avatar, background, script text, and sound settings. The script text supports multiple languages.

```APIDOC
## POST /videos

### Description
Creates a new video with specified parameters including avatar, background, script, and sound settings.

### Method
POST

### Endpoint
/videos

### Parameters
#### Request Body
- **avatar** (string) - Required - The ID of the avatar to use for the video.
- **background** (string) - Required - The background configuration for the video.
- **scriptText** (string) - Optional - The script for text-to-voice. Can be entered in any of the supported languages.
- **soundSettings** (object) - Optional - Settings for audio.
- **transition** (string) - Optional - The transition effect for the video.
```

--------------------------------

### Get Synthesia Asset Details

Source: https://docs.synthesia.io/reference/upload-large-files-via-temporary-aws-credentials

Retrieves the details of an existing Synthesia asset using its ID. Ensure the API key is valid and the asset ID exists.

```python
def get_asset(api_key: str, asset_id: str) -> dict:
    r = requests.get(
        f"https://api.synthesia.io/v2/assets/{asset_id}",
        headers={"Authorization": api_key, "accept": "application/json"},
        timeout=30,
    )
    if r.status_code != 200:
        raise RuntimeError(f"[Get asset] {r.status_code}: {r.text}")
    return r.json()
```

--------------------------------

### List Videos

Source: https://docs.synthesia.io/reference/list-videos

Retrieves an overview of all videos created via the API or Studio.

```APIDOC
## GET /videos

### Description
Retrieves an overview of all videos created via the API or Studio.

### Method
GET

### Endpoint
/videos
```

--------------------------------

### Download Video using cURL

Source: https://docs.synthesia.io/reference/synthesia-api-quickstart

Use this cURL command to download the generated video once it's ready. Replace ${DOWNLOAD_URL} with the actual download link provided in the API response.

```curl
curl ${DOWNLOAD_URL} --output my_first_synthetic_video.mp4
```

--------------------------------

### OpenAPI Definition for Thumbnail Retrieval

Source: https://docs.synthesia.io/reference/retrieve-a-jpg-thumbnail

This OpenAPI definition outlines the GET request for retrieving a video thumbnail. It specifies the path parameter 'video_id' and the expected responses.

```json
{
  "info": {
    "description": "Synthesia public API endpoints",
    "title": "Synthesia API",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.synthesia.io",
      "description": "Synthesia public API URL."
    }
  ],
  "paths": {
    "/{video_id}/thumbnail.jpg": {
      "get": {
        "summary": "Retrieve a thumbnail",
        "description": "Use this endpoint to pull information on a given video thumbnail.",
        "tags": [
          "Videos"
        ],
        "security": [
          {
            "api_key": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "video_id",
            "description": "The ID of the video to retrieve the thumbnail from.",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK."
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Thumbnail not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected Server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "openapi": "3.0.2",
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "context": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization"
      }
    }
  }
}
```

--------------------------------

### Create Video

Source: https://docs.synthesia.io/reference/create-video

Creates a new video based on the provided input. The video can be set to public or private visibility.

```APIDOC
## POST /videos

### Description
Creates a new video. Public videos are visible via a share URL, while private videos require a time-limited download link. Visibility can be updated later.

### Method
POST

### Endpoint
/videos

### Parameters
#### Request Body
- **input** (object) - Required - The input parameters for video creation.
  - **visibility** (string) - Optional - The visibility setting for the video ('public' or 'private'). Defaults to 'private'.
```

--------------------------------

### Get Dubbing Project Videos

Source: https://docs.synthesia.io/reference/get-dubbing-project-status-and-videos

Retrieves the status and dubbed video assets for a given dubbing project ID. The response structure varies depending on the project's status.

```APIDOC
## GET /dubbing/projects/{projectId}/videos

### Description
Retrieves the status and dubbed video assets for a specific dubbing project.

### Method
GET

### Endpoint
/dubbing/projects/{projectId}/videos

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The unique identifier of the dubbing project.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the dubbing project.
- **status** (string) - The current status of the dubbing project. Possible values include 'uploading', 'in_progress', 'complete', or 'error'.
- **dubbedAssets** (array) - (Optional) An array of dubbed video assets. This field is present when the status is 'in_progress' or 'complete'. Each asset can be in a state of 'in_progress', 'complete', or 'error'.
- **errorCode** (object) - (Optional) Contains error details if the status is 'error'.

### Response Example
#### Uploading Status
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "uploading"
}

#### In Progress Status
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "in_progress",
  "dubbedAssets": [
    {
      "id": "asset-1",
      "status": "in_progress"
    }
  ]
}

#### Complete Status
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "complete",
  "dubbedAssets": [
    {
      "id": "asset-1",
      "status": "complete",
      "url": "http://example.com/video.mp4"
    }
  ]
}

#### Error Status
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "error",
  "errorCode": {
    "code": "INVALID_INPUT",
    "message": "The provided input file is not supported."
  }
}
```

--------------------------------

### Create Dubbing Project from Source Asset ID

Source: https://docs.synthesia.io/reference/create-a-dubbing-project

Creates a dubbing project from an existing source media asset. You can specify the title, target languages, lipsync, video duration, visibility, and the source asset ID and language.

```APIDOC
## POST /dubbing/projects/from-source-asset-id

### Description
Creates a dubbing project using a source media asset ID. This allows you to dub an existing asset into multiple languages with various customization options.

### Method
POST

### Endpoint
/dubbing/projects/from-source-asset-id

### Parameters
#### Request Body
- **title** (string) - Required - The title of the dubbed video to create.
- **targetLanguages** (array) - Required - The languages to dub the source media asset to. Each element should be a valid `DubbingOutputLanguage`.
- **lipsyncEnabled** (boolean) - Optional - Whether to enable lipsync for the dubbed video. Defaults to `false`.
- **videoDuration** (string) - Optional - The duration of the video to create. Can be `adaptive` or `original`. Defaults to `adaptive`.
- **visibility** (string) - Optional - The visibility of the dubbed video. Can be `private` or `public`. Defaults to `private`.
- **sourceAssetId** (string) - Required - The ID of the source media asset to create the dubbed video from.
- **sourceLanguage** (string) - Required - The language of the source media asset. Should be a valid `DubbingInputLanguage`.

### Request Example
{
  "title": "My dubbed video",
  "targetLanguages": [
    "es-ES",
    "fr-FR"
  ],
  "lipsyncEnabled": true,
  "videoDuration": "adaptive",
  "visibility": "private",
  "sourceAssetId": "<uuid>",
  "sourceLanguage": "en"
}

### Response
#### Success Response (200)
(Response schema not provided in source)

#### Response Example
(Response example not provided in source)
```
Tokens:
Raw