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