Tavus Videos API
The Videos API from Tavus — 3 operation(s) for videos.
OpenAPI Specification
openapi: 3.0.3
info:
title: Tavus Developer API Collection Conversations Videos API
version: 1.0.0
contact: {}
servers:
- url: https://tavusapi.com
security:
- apiKey: []
tags:
- name: Videos
paths:
/v2/videos:
get:
tags:
- Videos
summary: List Videos
description: 'This endpoint returns a list of all Videos created by the account associated with the API Key in use.
'
operationId: listVideos
parameters:
- in: query
name: limit
schema:
type: integer
description: The number of videos to return per page. Default is 10.
- in: query
name: page
schema:
type: integer
description: The page number to return (0-indexed). Default is 0 (first page).
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: Videos for the current page; use `total_count` for the full count under the applied filters.
items:
type: object
properties:
video_id:
type: string
description: A unique identifier for the video.
example: 783537ef5
video_name:
type: string
description: A name for the video.
example: My First Video
status:
type: string
description: 'The status of the video. Possible values: queued, generating, ready, deleted, error.'
example: generating
data:
type: object
properties:
script:
type: string
description: The script that was initially used to generate the video.
example: Hello from Tavus! Enjoy your new replica
download_url:
type: string
description: A link to download the video.
example: ''
hosted_url:
type: string
description: A link to view the video.
stream_url:
type: string
description: A link to stream the video.
example: ''
status_details:
type: string
description: A detailed status of the video.
example: ''
background_url:
type: string
description: A link to a website. This will be used as the background for the video. The website must be publicly accessible and properly formed.
example: ''
background_source_url:
type: string
description: 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.
example: ''
still_image_thumbnail_url:
type: string
description: A link to a still image that is a thumbnail of the video.
example: ''
gif_thumbnail_url:
type: string
description: A link to a gif that is a thumbnail of the video.
example: ''
error_details:
type: string
description: If the video has an error, this will contain the error message.
example: ''
total_count:
type: integer
description: The total number of videos given the filters provided.
'401':
description: UNAUTHORIZED
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid access token
security:
- apiKey: []
post:
tags:
- Videos
summary: Generate Video
description: 'This endpoint generates a new video using a Replica and either a script or an audio file.
'
operationId: generateVideo
requestBody:
description: 'The only required body parameters are `replica_id` and either `script` or `audio_url`.
If a `background_url` is provided, Tavus records the website and uses it as the background. If a `background_source_url` is provided (for example a presigned S3 URL to a video), that video is used as the background. If neither is provided, the video is full-screen replica only.
To learn more about generating videos with Replicas, see [here](/sections/video/quickstart).
To learn more about writing an effective script for your video, see [Scripting prompting](/sections/troubleshooting#script-length).
'
content:
application/json:
schema:
type: object
properties:
replica_id:
type: string
description: A unique identifier for the replica that will be used to generate the video.
example: r90bbd427f71
video_name:
type: string
description: A name for the video.
example: My First Video
background_url:
type: string
description: A link to a website. This will be used as the background for the video. The website must be publicly accessible and properly formed.
example: https://yourwebsite.com/
background_source_url:
type: string
description: 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.
example: https://my-example-bucket.s3.us-east-1.amazonaws.com/your-background-video.mp4
callback_url:
type: string
description: A url that will receive a callback on completion of video generation or on error.
example: https://yourwebsite.com/webhook
fast:
type: boolean
description: 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.
example: false
transparent_background:
type: boolean
description: '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`.
'
example: false
watermark_image_url:
type: string
description: 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.
example: https://s3.amazonaws.com/watermark.png
properties:
type: object
properties:
background_scroll:
type: boolean
description: "If `background_url` is provided, this option may be configured.\n\nIf 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. \n\nThe default is `true`.\n"
example: true
background_scroll_type:
type: string
description: "If `background_url` is provided and `background_scroll` is set to `true`, this option may be configured.\n\nThis parameter defines the scroll pattern if `background_scroll` is set to `true`. \n\nThere are two options: `human`, `smooth`. \n\nThe `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.\n\nThe default is `human`.\n"
background_scroll_depth:
type: string
description: "If `background_url` is provided and `background_scroll` is set to `true`, this option may be configured.\n\n This parameter defines how far down the webpage the background video will scroll.\n \n There are two options: `middle`, `bottom`.\n \n 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.\n \n The default is `middle`.\n"
background_scroll_return:
type: string
description: '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:
type: boolean
description: 'If set to true, the video will start with a wave animation. This is only supported for select stock replicas.
The default is `true`.
'
example: true
required:
- replica_id
oneOf:
- title: Generate from Text
type: object
properties:
script:
type: string
description: A text script that will be used to generate the audio in the video.
example: Hello from Tavus! Enjoy your new replica
required:
- script
- title: Generate from Audio File
type: object
properties:
audio_url:
type: string
description: 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.
required:
- audio_url
examples:
Generate Video:
value:
background_url: https://yourwebsite.com/
replica_id: r90bbd427f71
script: Hi, this is my first video.
video_name: My First Video
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
video_id:
type: string
example: abcd123
description: A unique identifier for the video.
video_name:
type: string
example: Sample Video
description: The name of the video.
status:
type: string
example: queued
description: 'The status of the video. Possible values: queued, generating, ready, deleted, error.'
hosted_url:
type: string
example: https://tavus.video/abcd123
description: A direct link to view your video once generation has completed, hosted by Tavus.
created_at:
type: string
example: Mon, 14 Jul 2025 09:14:24 GMT
description: The date and time the video was created.
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: Invalid replica_id
'401':
description: UNAUTHORIZED
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid access token
security:
- apiKey: []
/v2/videos/{video_id}:
get:
tags:
- Videos
summary: Get Video
description: 'This endpoint returns a single video by its unique identifier.
'
operationId: getVideo
parameters:
- in: path
name: video_id
required: true
schema:
type: string
description: A unique identifier for the video.
- in: query
name: verbose
schema:
type: boolean
description: If set to true, the response will include additional video data such as the thumbnail image and gif links.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
video_id:
type: string
example: ''
description: A unique identifier for the video.
video_name:
type: string
description: The name of the video.
status:
type: string
example: ready
description: 'Lifecycle status; possible values: `queued`, `generating`, `ready`, `deleted`, `error`. When `ready`, `download_url`, `stream_url`, and `hosted_url` are populated for download, stream, and viewing respectively.'
data:
type: object
properties:
script:
type: string
description: The script that was initially used to generate the video.
download_url:
type: string
description: A direct link to download your generated video (populated when `status` is `ready`).
stream_url:
type: string
description: A direct link to stream your generated video (populated when `status` is `ready`).
hosted_url:
type: string
description: A direct link to view your generated video, hosted by Tavus (populated when `status` is `ready`).
status_details:
type: string
description: A detailed status of the video.
created_at:
type: string
description: The date and time the video was created.
updated_at:
type: string
description: The date and time of when the video was last updated.
still_image_thumbnail_url:
type: string
description: Included if the `verbose` query parameter is set to true. A link to an image thumbnail of the video.
gif_thumbnail_url:
type: string
description: Included if the `verbose` query parameter is set to true. A link to a gif thumbnail of the video.
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: Invalid video_id
'401':
description: UNAUTHORIZED
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid access token
security:
- apiKey: []
delete:
tags:
- Videos
summary: Delete Video
description: 'This endpoint deletes a single video by its unique identifier.
'
operationId: deleteVideo
parameters:
- name: video_id
in: path
required: true
description: The unique identifier of the video generation.
schema:
type: string
example: 8a4f94e736
- name: hard
in: query
schema:
type: boolean
example: false
description: 'If set to true, the video and associated assets (such as thumbnail images) will be hard deleted. CAUTION: This action is irrevocable.'
responses:
'200':
description: ''
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: Invalid video_id
'401':
description: UNAUTHORIZED
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid access token
security:
- apiKey: []
/v2/videos/{video_id}/name:
parameters:
- name: video_id
in: path
required: true
description: The unique identifier of the video generation.
schema:
type: string
example: 8a4f94e736
patch:
tags:
- Videos
summary: Rename Video
description: 'This endpoint renames a single video by its unique identifier.
'
operationId: renameVideo
requestBody:
content:
application/json:
schema:
type: object
properties:
video_name:
type: string
example: Sales
required:
- video_name
examples:
Rename Video:
value:
video_name: Sales
responses:
'200':
description: OK
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: Invalid video_id
'401':
description: UNAUTHORIZED
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid access token
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key