---
title: "Generate Video"
method: POST
path: "/v2/videos"
tags: ["Videos"]
---

# Generate Video

`POST /v2/videos`

This endpoint generates a new video using a face and either a script or an audio file.

## Request body

- union
  - object
    - `replica_id` string, required — The Face ID to render in the video (same resource as `face_id` on `/v2/faces`; this endpoint still accepts `replica_id`).
    - `video_name` string — A name for the video.
    - `background_url` string — A link to a website. This will be used as the background for the video. The website must be publicly accessible and properly formed.
    - `background_source_url` string — A direct link to a video that is publicly accessible via a storage location such as an S3 bucket. This will be used as the background for the video. The video must be publicly accessible.
    - `callback_url` string — A url that will receive a callback on completion of video generation or on error.
    - `fast` boolean — If set to true, the video will be generated using a barebones fast rendering process. This will result in a faster generation of the video but some features will be disabled. Features such as background generation, thumbnail images, and streaming urls are not supported when using this fast rendering process.
    - `transparent_background` boolean — If set to true, the generated video will be a `.webm` video with a transparent background. Please note that this feature only works if the `fast` parameter is set to `true`.
    - `watermark_image_url` string — A direct link to a image that is publicly accessible via a storage location such as an S3 bucket. This will be used as the watermark on the video. Currently, it support `png` & `jpeg` formats only. Ensure the image is publicly accessible.
    - `properties` object
      - `background_scroll` boolean — If `background_url` is provided, this option may be configured. If set to `true`, the background video will scroll down through the website. If set to `false`, the background video will display the top of the website. The default is `true`.
      - `background_scroll_type` string — If `background_url` is provided and `background_scroll` is set to `true`, this option may be configured. This parameter defines the scroll pattern if `background_scroll` is set to `true`. There are two options: `human`, `smooth`. The `human` scroll type is the default type and mimics a human scrolling through the webpage, briefly stopping at certain intervals to give a natural appearance. The `smooth` scroll type scroll in a uniform manner all the way down the website without stopping. The default is `human`.
      - `background_scroll_depth` string — If `background_url` is provided and `background_scroll` is set to `true`, this option may be configured. This parameter defines how far down the webpage the background video will scroll. There are two options: `middle`, `bottom`. The `middle` depth option will stop scrolling once the middle of the webpage has been hit. The `bottom` will scroll the webpage all the way to the bottom of the page. The default is `middle`.
      - `background_scroll_return` string — If `background_url` is provided and `background_scroll` is set to `true`, this option may be configured. This parameter defines the scrolling behavior once the webpage has been scrolled to the depth specified by the `background_scroll_depth` parameter. There are two options: `return`, `halt`. The `return` option will scroll back up once the webpage has reached `background_scroll_depth`. The `halt` option will pause the background video at the location specified in `background_scroll_depth`. The default is `return`.
      - `start_with_wave` boolean — If set to true, the video will start with a wave animation. This is only supported for select stock faces. The default is `true`.
    - `script` string, required — A text script that will be used to generate the audio in the video.
  - object
    - `replica_id` string, required — The Face ID to render in the video (same resource as `face_id` on `/v2/faces`; this endpoint still accepts `replica_id`).
    - `video_name` string — A name for the video.
    - `background_url` string — A link to a website. This will be used as the background for the video. The website must be publicly accessible and properly formed.
    - `background_source_url` string — A direct link to a video that is publicly accessible via a storage location such as an S3 bucket. This will be used as the background for the video. The video must be publicly accessible.
    - `callback_url` string — A url that will receive a callback on completion of video generation or on error.
    - `fast` boolean — If set to true, the video will be generated using a barebones fast rendering process. This will result in a faster generation of the video but some features will be disabled. Features such as background generation, thumbnail images, and streaming urls are not supported when using this fast rendering process.
    - `transparent_background` boolean — If set to true, the generated video will be a `.webm` video with a transparent background. Please note that this feature only works if the `fast` parameter is set to `true`.
    - `watermark_image_url` string — A direct link to a image that is publicly accessible via a storage location such as an S3 bucket. This will be used as the watermark on the video. Currently, it support `png` & `jpeg` formats only. Ensure the image is publicly accessible.
    - `properties` object
      - `background_scroll` boolean — If `background_url` is provided, this option may be configured. If set to `true`, the background video will scroll down through the website. If set to `false`, the background video will display the top of the website. The default is `true`.
      - `background_scroll_type` string — If `background_url` is provided and `background_scroll` is set to `true`, this option may be configured. This parameter defines the scroll pattern if `background_scroll` is set to `true`. There are two options: `human`, `smooth`. The `human` scroll type is the default type and mimics a human scrolling through the webpage, briefly stopping at certain intervals to give a natural appearance. The `smooth` scroll type scroll in a uniform manner all the way down the website without stopping. The default is `human`.
      - `background_scroll_depth` string — If `background_url` is provided and `background_scroll` is set to `true`, this option may be configured. This parameter defines how far down the webpage the background video will scroll. There are two options: `middle`, `bottom`. The `middle` depth option will stop scrolling once the middle of the webpage has been hit. The `bottom` will scroll the webpage all the way to the bottom of the page. The default is `middle`.
      - `background_scroll_return` string — If `background_url` is provided and `background_scroll` is set to `true`, this option may be configured. This parameter defines the scrolling behavior once the webpage has been scrolled to the depth specified by the `background_scroll_depth` parameter. There are two options: `return`, `halt`. The `return` option will scroll back up once the webpage has reached `background_scroll_depth`. The `halt` option will pause the background video at the location specified in `background_scroll_depth`. The default is `return`.
      - `start_with_wave` boolean — If set to true, the video will start with a wave animation. This is only supported for select stock faces. The default is `true`.
    - `audio_url` string, required — A download link to a .wav or .mp3 file that is publicly accessible via a storage location such as an S3 bucket. This audio file will be used as the audio for the generated video.

## Response `200`

- object
  - `video_id` string — A unique identifier for the video.
  - `video_name` string — The name of the video.
  - `status` string — The status of the video. Possible values: queued, generating, ready, deleted, error.
  - `hosted_url` string — A direct link to view your video once generation has completed, hosted by Tavus.
  - `created_at` string — The date and time the video was created.

## Other responses

- `400` — Bad Request
- `401` — UNAUTHORIZED

---

[API](https://skmtc.dev/tavus/apis/tavus-developer-api-collection.md) · [All operations](https://skmtc.dev/tavus/apis/tavus-developer-api-collection/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tavus/tavus-developer-api-collection/revisions/c878e2f6508d/schema)