---
title: "Create a video"
method: POST
path: "/v2/videos"
tags: ["Videos"]
---

# Create a video

`POST /v2/videos`

Create a video within your Synthesia account. To get started on this endpoint check the [API Quickstart guide](https://docs.synthesia.io/reference/synthesia-api-quickstart).

## Request body

- CreateVideoRequest
  - `folderId` string, uuid, nullable — Optional folder ID. If provided, the new video will be created under this folder and inherit its permissions.
  - `aspectRatio` '16:9' | '9:16' | '1:1' | '4:5' | '5:4' — Aspect ratio of the video. Default is `landscape (16:9)`.
  - `ctaSettings` CtaSettings
    - `label` string, required — Label for a call-to-action button.
    - `url` string, required — URL to navigate to, when the call-to-action button is clicked.
  - `callbackId` string — 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 — Description of the video to be shown on the share page.
  - `input` Input[], 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.
    - `avatar` string, required — Use one of [Synthesia stock avatars or your custom avatar](https://docs.synthesia.io/reference/avatars).
    - `avatarSettings` ActorSettings
      - `backgroundColor` unknown
      - `horizontalAlign` 'left' | 'center' | 'right' | 'null', nullable — 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 corner towards the top-right corner.
      - `scale` number, nullable — The scale of the avatar.
      - `style` 'circular' | 'rectangular' | 'voiceOnly', required — `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
      - `voice` string, uuid, nullable — If a voice is not provided, a default voice is assigned automatically. This default is subject to change, which may cause inconsistent voices across videos. Specify voiceId explicitly to ensure consistent output. See the complete list of voices.
      - `seamless` boolean — 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.
    - `background` string, required — Use Synthesia' stock backgrounds or your custom background. For the custom background, provide the ID of an uploaded asset (see [Create an asset](https://docs.synthesia.io/reference/create-an-asset)), or URL from where Synthesia should download the background. 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`
    - `backgroundSettings` InputBackgroundSettings
      - `position` InputBackgroundPosition
        - `x` integer, required
        - `y` integer, required
      - `scale` number
      - `videoSettings` InputVideoBackgroundSettings
        - `trim` InputBackgroundTrim
          - `startTime` number, required
          - `endTime` number, required
        - `shortBackgroundContentMatchMode` 'freeze' | 'loop' | 'slow_down' — 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
        - `longBackgroundContentMatchMode` 'extend_content' | 'trim' | 'speed_up' — 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
        - `volume` number, nullable
    - `scriptAudio` string — As an alternative to `scriptText`, provide the ID of uploaded script audio. See [Upload script audio for details](https://docs.synthesia.io/reference/upload-script-audio). If you use `scriptAudio` you must provide `scriptLanguage`.
    - `scriptLanguage` 'MISSING' | 'af' | 'af-001' | 'sq-AL' | 'sq-001' | 'am' | 'am-001' | 'ar-DZ' | 'ar-BH' | 'ar-EG' | 'ar-IQ' | 'ar-JO' | 'ar-KW' | 'ar-LY' | 'ar-MA' | 'ar-QA' | 'ar-SA' | 'ar-SY' | 'ar-TN' | 'ar-AE' | 'ar-YE' | 'ar-001' | 'as-IN' | 'as-001' | 'hy-AM' | 'hy-001' | 'az-AZ' | 'az-001' | 'eu-ES' | 'eu-001' | 'bs-BA' | 'bs-001' | 'bg' | 'bg-001' | 'bn-BD' | 'bn-IN' | 'bn-001' | 'my' | 'my-001' | 'yue-CN' | 'ca' | 'ca-001' | 'zh-CN' | 'zh-HK' | 'zh-TW' | 'zh-001' | 'hr' | 'hr-001' | 'cs' | 'cs-001' | 'da' | 'da-001' | 'nl-NL' | 'nl-001' | 'nl-BE' | 'ka-GE' | 'ka-001' | 'en-AU' | 'en-CA' | 'en-GB' | 'en-HK' | 'en-IE' | 'en-IN' | 'en-KE' | 'en-MX' | 'en-NG' | 'en-NZ' | 'en-PH' | 'en-US' | 'en-SG' | 'en-ZA' | 'en-TZ' | 'en-001' | 'et' | 'et-001' | 'fil' | 'fil-001' | 'fi' | 'fi-001' | 'fr-BE' | 'fr-CA' | 'fr-CH' | 'fr-FR' | 'fr-001' | 'gl' | 'gl-001' | 'de-AT' | 'de-DE' | 'de-CH' | 'de-001' | 'el' | 'el-001' | 'gu' | 'gu-001' | 'iw' | 'iw-001' | 'hi' | 'hi-001' | 'ht-HT' | 'hu' | 'hu-001' | 'is' | 'is-001' | 'id' | 'id-001' | 'ga' | 'ga-001' | 'it' | 'it-001' | 'ja' | 'ja-001' | 'jv' | 'jv-001' | 'kn' | 'kn-001' | 'kk-KZ' | 'kk-001' | 'km' | 'km-001' | 'ko' | 'ko-001' | 'lt' | 'lt-001' | 'lv' | 'lv-001' | 'lo-LA' | 'lo-001' | 'mi-NZ' | 'mk-MK' | 'mk-001' | 'ms' | 'ms-001' | 'ml' | 'ml-001' | 'mt' | 'mt-001' | 'mr' | 'mr-001' | 'mn-MN' | 'mn-001' | 'ne-NP' | 'ne-001' | 'nb' | 'nb-001' | 'or-IN' | 'or-001' | 'ps-AF' | 'ps-001' | 'fa' | 'fa-001' | 'pl' | 'pl-001' | 'pt-BR' | 'pt-PT' | 'pt-001' | 'pa-IN' | 'pa-001' | 'ro' | 'ro-001' | 'ru' | 'ru-001' | 'sr' | 'sr-001' | 'si-LK' | 'si-001' | 'sk' | 'sk-001' | 'sl' | 'sl-001' | 'so' | 'so-001' | 'es-AR' | 'es-BO' | 'es-CL' | 'es-CO' | 'es-CR' | 'es-CU' | 'es-DO' | 'es-EC' | 'es-SV' | 'es-GQ' | 'es-GT' | 'es-HN' | 'es-LA' | 'es-MX' | 'es-NI' | 'es-PA' | 'es-PY' | 'es-PE' | 'es-PR' | 'es-ES' | 'es-US' | 'es-UY' | 'es-VE' | 'es-001' | 'su' | 'su-001' | 'sv' | 'sv-001' | 'sw-KE' | 'sw-TZ' | 'sw-001' | 'vi' | 'vi-001' | 'ta-IN' | 'ta-SG' | 'ta-LK' | 'ta-001' | 'te' | 'te-001' | 'tr' | 'tr-001' | 'th' | 'th-001' | 'uk' | 'uk-001' | 'ur-IN' | 'ur-PK' | 'ur-001' | 'uz' | 'uz-001' | 'cy' | 'cy-001' | 'wuu-CN' | 'zu' | 'zu-001' — Language code of the language the script audio was generated in. The scriptLanguage option must be used with `scriptAudio`. To control the language/voice of the scriptText, 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.
    - `scriptText` string — Script for text-to-voice can be entered in any of the [supported languages](https://docs.synthesia.io/reference/voices).
    - `soundSettings` InputSoundSettings
      - `soundtrackVolume` number, nullable
    - `transition` string, nullable
  - `soundtrack` 'corporate' | 'inspirational' | 'modern' | 'urban' — soundtrack option is supported for backward compatibility. You should use the templates functionality for rich videos.
  - `soundSettings` ParentSoundSettings
    - `defaultSoundtrackVolume` number
    - `soundtracks` ParentSoundtrackRegion[]
      - `soundtrack` string, required
      - `slideRange` string, required
      - `fadeInSeconds` number
      - `fadeOutSeconds` number
  - `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.
  - `title` string — Title of the video to be shown on the share page.
  - `visibility` 'private' | 'public' — 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.

## Response `200`

OK.

- VideoResponse
  - `callbackId` string — 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..
  - `createdAt` integer — UNIX timestamp representing the time video was created.
  - `ctaSettings` CtaSettings
    - `label` string, required — Label for a call-to-action button.
    - `url` string, required — URL to navigate to, when the call-to-action button is clicked.
  - `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, uuid
  - `lastUpdatedAt` integer
  - `status` 'complete' | 'deleted' | 'error' | 'in_progress' | 'rejected' | 'approved'
  - `thumbnail` VideoThumbnailTypesResponse
    - `image` string, nullable
    - `gif` string, nullable
  - `title` string — Title of the video to be shown on the share page.
  - `visibility` 'private' | 'public' — 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.

## Other responses

- `400` — Bad Request.
- `403` — Forbidden - Wrong API key.
- `default` — Unexpected Server error.

---

[API](https://skmtc.net/synthesia/apis/synthesia-api.md) · [All operations](https://skmtc.net/synthesia/apis/synthesia-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/synthesia/synthesia-api/revisions/f0f34ae0591d/schema)