API Reference

Community

Status

Tavus

Get Started

Login

Account Help

Get Support

This is an event broadcasted by Tavus.

A `tool_call` event is broadcasted by Tavus when an LLM tool call should be made. The event will contain the name and arguments of the function that should be called.

Tool call events can be used to make calls to external APIs or databases.


Tool Call Event

get_current_weather

Take a look at our Docs and API Reference to learn how to use Tavus!

Introduction

Overview of Tavus' Replica offerings- Stock Replicas and Personal Replicas, all powered by the Phoenix AI model. Get tips on how to create the perfect replica, and how to get a high quality output.

Overview

Explore Tavus' collection of ready-to-use stock replicas for effortless video creation.

Stock Replicas

Learn how to create a high-quality personal replica with just a few minutes of training data.

Personal Replicas

Language Support

Best Practices & Examples

Learn how to generate high-quality videos using Stock or Personal Replicas

Find out how to look at all the Stock Replicas as well as your Personal Replicas

Replica Selection

Learn how to create a high-quality script

Scripting

What is CVI? (Overview)

Layers and Modes Overview

This guide will walk you through the steps to quickly test out the API and start a conversation.

Quick Start

Creating a Replica

Creating a Conversation

Creating a Persona

Interactions Protocol Overview

This is an event developers may broadcast to Tavus.

By broadcasting this event, you are able to tell the replica what to exactly say. Anything that is passed in the `text` field will be spoken by the replica.

This is commonly used in combination with the [Interrupt Interaction](/sections/event-schemas/conversation-interrupt).


Echo Interaction

This is an event developers may broadcast to Tavus.

By broadcasting this event, you are able to send text that the replica will to respond to. The text you provide in the event will essentially be treated as the user transcript, and will be responded to as if the user had uttered those phrases during conversation.


Text Respond Interaction

This is an event developers may broadcast to Tavus.

By broadcasting this event, you are able to externally send interruptions for the replica to stop talking. This is commonly used in combination with [Text Echo Interactions](/sections/event-schemas/conversation-echo).


Interrupt Interaction

This is an event developers may broadcast to Tavus.

By broadcasting this event, you are able to overwrite the `conversational_context` that the replica uses to generate responses. 

If `conversational_context` was not provided during conversation creation, the replica will start using the `context` you provide in this event as `conversational_context`.

Learn more about the `conversational_context`: [Create Conversation](/api-reference/conversations/create-conversation)


Overwrite Conversational Context interaction

This is an event broadcasted by Tavus.

An `utterance event` is broadcasted by Tavus after either the replica or the user finishes speaking. The event will contain the content of the utterance that was just spoken as well as an indication of who spoke it.

An `utterance` includes all of the words spoken by the user or replica measured from when the person started speaking to when they finshed speaking. This could include multiple sentences or phrases.

Utterance events can be used to keep track of what the user or the replica has said.


Utterance Event

You can integrate an OpenAI-compatible LLM to replace our existing options (`tavus-llama`, `tavus-gpt-4o`, `tavus-gpt-4o-mini`).

Custom LLM Onboarding

You can integrate a variety of third-party TTS providers (cartesia, elevenlabs, playht).

Custom TTS Onboarding

You can set up a custom S3 bucket, enable recordings in rooms, and get notified when recordings are ready to be shared.

Record and Instantly Share Conversations

Stock Personas

Server to Server Architecture

Frequently asked questions about Tavus's Conversational Video Interface

Pipecat Integration

Training Video Size

Consent Statement

Script Length

This guide includes an overview of errors and status details you might see from the API

API Errors and Status Details

This guide includes an overview of different callback formats you might see from the API.

API Callbacks

Changelog

This endpoint creates a new Replica that can be used to generate personalized videos. 

The only required body parameter is `train_video_url`. This url must be a download link such as a presigned S3 url. Please ensure you pass in a video that meets the [requirements](/sections/troubleshooting/training-video-size) for training.

Replica training will fail without the following consent statement being present at the beginning of the video:
> I, [FULL NAME], am currently speaking and consent Tavus to create an AI clone of me by using the audio and video samples I provide. I understand that this AI clone can be used to create videos that look and sound like me.

Learn more about the consent statement [here](/sections/troubleshooting/consent-statement).

Learn more about training a personal Replica [here](/sections/replicas/personal-replicas).


Create Replica

This endpoint returns a single Replica by its unique identifier. 

Included in the response body is a `training_progress` string that represents the progress of the Replica training. If there are any errors during training, the `status` will be `error` and the `error_message` will be populated.


Get Replica

This endpoint returns a list of all replicas that have been created by the API Key in use. In the response, a root level `data` key will contain the list of Replicas.


List Replicas

This endpoint deletes a single Replica by its unique identifier. Once deleted, this Replica can not be used to generate videos.


Delete Replica

This endpoint renames a single Replica by its unique identifier. 


Rename Replica

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

The only required body parameters are `replica_id` and either `script` or `audio_file`. 

The `replica_id` is a unique identifier for the Replica that will be used to generate the video. The `script` is the text that will be spoken by the Replica in the video. If you would like to generate a video using an audio file instead of a script, you can provide `audio_url` instead of `script`. Currently, only `.wav` files are supported for audio file input.

If a `background_url` is provided, Tavus will record a video of the website and use it as the background for the video. If a `background_source_url` is provided, where the URL points to a download link such as a presigned S3 URL, Tavus will use the video as the background for the video. If neither are provided, the video will consist of a full screen Replica.

To learn more about generating videos with Replicas, see [here](/sections/video-generation/overview).

To learn more about writing an effective script for your video, see [Scripting prompting](/sections/video-generation/scripting-prompting).


Generate Video

This endpoint returns a single video by its unique identifier. 

The response body will contain a `status` string that represents the status of the video. If the video is ready, the response body will also contain a `download_url`, `stream_url`, and `hosted_url` that can be used to download, stream, and view the video respectively.


Get Video

This endpoint returns a list of all videos that have been generated by the API Key in use. 


List Videos

This endpoint deletes a single video by its unique identifier.


Delete Video

This endpoint renames a single video by its unique identifier.


Rename Video

With the Tavus Conversational Video Interface (CVI) you are able to create a `conversation` with a replica in real time.

### Conversations
A `conversation` is a video call with a replica. 

After creating a `conversation`, a `conversation_url` will be returned in the response. The `conversation_url` can be used to join the conversation directly or can be embedded in a website. To embed the `conversation_url` in a website, you can find [instructions here](https://www.daily.co/products/prebuilt-video-call-app/quickstart/).

Once a conversation is created, the replica will automatically join the call and will start participating.

By providing a `callback_url`, you can receive webhooks with updates regarding the conversation state.

[Learn about recording conversations here](/sections/conversational-video-interface/recording-rooms).


Create Conversation

This endpoint returns a single conversation by its unique identifier. 


Get Conversation

This endpoint returns a list of all conversations that have been generated by the API Key in use.


List Conversations

This endpoint ends a single conversation by its unique identifier.


End Conversation

This endpoint deletes a single conversation by its unique identifier.


Delete Conversation

This endpoint creates a new persona that can be used by replicas in conversations. 

With a persona, you are able to craft the personalities of your replica across conversations.

#### LLM
With the `llm` layer, you can leverage your own OpenAI compatible LLM or you can use one a Tavus provided model.
- **tavus-gpt-4o:** The smartest option for complex interactions.
- **tavus-gpt-4o-mini:** A hybrid model that balances performance and intelligence.
- **tavus-llama:** The **default** choice if no LLM layer is provided. This is the fastest model, offering the best user-to-user (U2U) experience. It’s on-premise, making it incredibly performant. 

[Get Started with Your Own LLM](/sections/conversational-video-interface/custom-llm-onboarding.mdx)

#### TTS
With Tavus' default TTS engine, you get the faster utterance-to-utterance speed, but you can always bring your own if you have voices already trained with:
- **Cartesia**
- **Elevenlabs**
- **Playht**

[Get Started with Your Own TTS](/sections/conversational-video-interface/custom-llm-onboarding.mdx)


Create Persona

This endpoint returns a single persona by its unique identifier. 


Get Persona

This endpoint returns a list of all personas that have been created by the API Key in use.


List Personas

This replaces the existing persona context with the provided context. 


Update Persona Context

This endpoint deletes a single persona by its unique identifier.


Delete Persona

This endpoint generates an audio file based on a script with a provided Replica.


Generate Speech

This endpoint returns a single speech by its unique identifier.


Get Speech

This endpoint returns a list of all speeches that have been generated by the API Key in use.


Replicas

Video Generation

Conversational Video Interface

Integrations

Troubleshooting

Changelog

Tool Call Event