# Tavus ## Docs - [Authentication](https://docs.tavus.io/api-reference/authentication.md): Learn how to generate and use your Tavus API key to authenticate requests. - [Create Conversation](https://docs.tavus.io/api-reference/conversations/create-conversation.md): This endpoint starts a real-time video conversation with your AI replica, powered by a persona that allows it to see, hear, and respond like a human. **Core Components:** - Replica - Choice of audio/visual appearance - Persona - Define the replica's behavior and capabilities The response includes a `conversation_url` that you can use to join the call or embed it on your website. [Learn how to embed it here](/sections/integrations/embedding-cvi). If you provide a `callback_url`, you’ll receive webhooks with updates about the conversation status. [Learn more about Callback here](/sections/webhooks-and-callbacks). - [Delete Conversation](https://docs.tavus.io/api-reference/conversations/delete-conversation.md): This endpoint deletes a single conversation by its unique identifier. - [End Conversation](https://docs.tavus.io/api-reference/conversations/end-conversation.md): This endpoint ends a single conversation by its unique identifier. - [Get Conversation](https://docs.tavus.io/api-reference/conversations/get-conversation.md): This endpoint returns a single conversation by its unique identifier. - [List Conversations](https://docs.tavus.io/api-reference/conversations/get-conversations.md): This endpoint returns a list of all Conversations created by the account associated with the API Key in use. - [Create Document](https://docs.tavus.io/api-reference/documents/create-document.md): Upload documents to your knowledge base for personas to reference during conversations - [Delete Document](https://docs.tavus.io/api-reference/documents/delete-document.md): Delete a specific document - [Get Document](https://docs.tavus.io/api-reference/documents/get-document.md): Retrieve a specific document by ID - [List Documents](https://docs.tavus.io/api-reference/documents/get-documents.md): Retrieve a list of documents with optional filtering and pagination - [Update Document](https://docs.tavus.io/api-reference/documents/patch-document.md): Update a specific document's metadata - [Create Guardrails](https://docs.tavus.io/api-reference/guardrails/create-guardrails.md): This endpoint creates a new set of guardrails for a persona. Guardrails provide strict behavioral boundaries and guidelines that will be rigorously followed throughout conversations. - [Delete Guardrails](https://docs.tavus.io/api-reference/guardrails/delete-guardrails.md): This endpoint deletes a single set of guardrails by its unique identifier. - [Get Guardrails (One Set)](https://docs.tavus.io/api-reference/guardrails/get-guardrails.md): This endpoint returns a single set of guardrails by its unique identifier. - [Get Guardrails (All Sets)](https://docs.tavus.io/api-reference/guardrails/get-guardrails-list.md): This endpoint returns a list of all sets of guardrails. - [Patch Guardrails](https://docs.tavus.io/api-reference/guardrails/patch-guardrails.md): This endpoint allows you to update specific fields of guardrails using JSON Patch operations. **Note:** The `path` field is a JSON Pointer string that references a location within the target document where the operation is performed. For example: ```json [ { "op": "replace", "path": "/data/0/guardrails_prompt", "value": "Your updated prompt"}, { "op": "add", "path": "/data/0/callback_url", "value": "https://your-server.com/webhook" } ] ``` - [Create Objectives](https://docs.tavus.io/api-reference/objectives/create-objectives.md): This endpoint creates a new objective for a persona. Objectives provide goal-oriented instructions that help guide conversations toward specific achievements and desired outcomes. - [Delete Objective](https://docs.tavus.io/api-reference/objectives/delete-objectives.md): This endpoint deletes a single objective by its unique identifier. - [Get Objective](https://docs.tavus.io/api-reference/objectives/get-objectives.md): This endpoint returns a single objective by its unique identifier. - [Get Objectives](https://docs.tavus.io/api-reference/objectives/get-objectives-list.md): This endpoint returns a list of all objectives. - [Patch Objective](https://docs.tavus.io/api-reference/objectives/patch-objectives.md): This endpoint allows you to update specific fields of an objective using JSON Patch operations. **Note:** The `path` field is a JSON Pointer string that references a location within the target document where the operation is performed. For example: ```json [ { "op": "replace", "path": "/data/0/objective_name", "value": "updated_objective_name" }, { "op": "replace", "path": "/data/0/objective_prompt", "value": "Updated prompt for the objective" }, { "op": "replace", "path": "/data/0/confirmation_mode", "value": "manual" }, { "op": "add", "path": "/data/0/output_variables", "value": ["new_variable"] }, { "op": "replace", "path": "/data/0/modality", "value": "visual" }, { "op": "remove", "path": "/data/0/callback_url" } ] ``` - [Overview](https://docs.tavus.io/api-reference/overview.md): Discover the Tavus API — build a real-time, human-like multimodal video conversation with a replica. - [Create Persona](https://docs.tavus.io/api-reference/personas/create-persona.md): This endpoint creates and customizes a digital replica's behavior and capabilities for Conversational Video Interface (CVI). **Core Components:** - Replica - Choice of audio/visual appearance - Context - Customizable contextual information, for use by LLM - System Prompt - Customizable system prompt, for use by LLM - Layers - Perception - Multimodal vision and understanding settings (Raven) - STT - Transcription and turn taking settings (Sparrow) - LLM - Language model settings - TTS - Text-to-Speech settings - [Delete Persona](https://docs.tavus.io/api-reference/personas/delete-persona.md): This endpoint deletes a single persona by its unique identifier. - [Get Persona](https://docs.tavus.io/api-reference/personas/get-persona.md): This endpoint returns a single persona by its unique identifier. - [List Personas](https://docs.tavus.io/api-reference/personas/get-personas.md): This endpoint returns a list of all Personas created by the account associated with the API Key in use. - [Patch Persona](https://docs.tavus.io/api-reference/personas/patch-persona.md): This endpoint updates a persona using a JSON Patch payload (RFC 6902). You can modify **any field within the persona** using supported operations like `add`, `remove`, `replace`, `copy`, `move`, and `test`. For example: ```json [ { "op": "replace", "path": "/persona_name", "value": "Wellness Advisor" }, { "op": "replace", "path": "/default_replica_id", "value": "r79e1c033f" }, { "op": "replace", "path": "/context", "value": "Here are a few times that you have helped an individual make a breakthrough in..." }, { "op": "replace", "path": "/layers/llm/model", "value": "tavus-gpt-4o" }, { "op": "replace", "path": "/layers/tts/tts_engine", "value": "cartesia" }, { "op": "add", "path": "/layers/tts/tts_emotion_control", "value": "true" }, { "op": "remove", "path": "/layers/stt/hotwords" }, { "op": "replace", "path": "/layers/perception/perception_tool_prompt", "value": "Use tools when identity documents are clearly shown." } ] ``` - [Create Replica](https://docs.tavus.io/api-reference/phoenix-replica-model/create-replica.md): This endpoint creates a new replica using the latest `phoenix-3` model, which can be used in real-time conversations. To ensure high-quality replica creation, follow the steps in the [Replica Training](/sections/replica/replica-training) guide. - [Delete Replica](https://docs.tavus.io/api-reference/phoenix-replica-model/delete-replica.md): This endpoint deletes a Replica by its unique ID. Deleted Replicas cannot be used in a conversation. - [Get Replica](https://docs.tavus.io/api-reference/phoenix-replica-model/get-replica.md): 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. - [List Replicas](https://docs.tavus.io/api-reference/phoenix-replica-model/get-replicas.md): This endpoint returns a list of all Replicas created by the account associated with the API Key in use. In the response, a root level `data` key will contain the list of Replicas. - [Rename Replica](https://docs.tavus.io/api-reference/phoenix-replica-model/patch-replica-name.md): This endpoint renames a single Replica by its unique identifier. - [Generate Speech](https://docs.tavus.io/api-reference/speech/create-speech.md): This endpoint generates an audio file based on a script with a provided Replica. - [Delete Speech](https://docs.tavus.io/api-reference/speech/delete-speech.md): This endpoint deletes a single speech by its unique identifier. - [Get Speech](https://docs.tavus.io/api-reference/speech/get-speech.md): This endpoint returns a single speech by its unique identifier. - [List Speeches](https://docs.tavus.io/api-reference/speech/get-speech-list.md): This endpoint returns a list of all Speeches created by the account associated with the API Key in use. - [Rename Speech](https://docs.tavus.io/api-reference/speech/patch-speech-name.md): This endpoint renames a single speech by its unique identifier. - [Generate Video](https://docs.tavus.io/api-reference/video-request/create-video.md): 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, `.wav` and `.mp3` 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/quickstart). To learn more about writing an effective script for your video, see [Scripting prompting](/sections/troubleshooting#script-length). - [Delete Video](https://docs.tavus.io/api-reference/video-request/delete-video.md): This endpoint deletes a single video by its unique identifier. - [Get Video](https://docs.tavus.io/api-reference/video-request/get-video.md): 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. - [List Videos](https://docs.tavus.io/api-reference/video-request/get-videos.md): This endpoint returns a list of all Videos created by the account associated with the API Key in use. - [Rename Video](https://docs.tavus.io/api-reference/video-request/patch-video-name.md): This endpoint renames a single video by its unique identifier. - [Changelog](https://docs.tavus.io/sections/changelog/changelog.md) - [Blocks](https://docs.tavus.io/sections/conversational-video-interface/component-library/blocks.md): High-level component compositions that combine multiple UI elements into complete interface layouts - [Components](https://docs.tavus.io/sections/conversational-video-interface/component-library/components.md): Learn about our pre-built React components to accelerate integrating the Tavus Conversational Video Interface (CVI) into your application. - [Hooks](https://docs.tavus.io/sections/conversational-video-interface/component-library/hooks.md): See what hooks Tavus supports for managing video calls, media controls, participant management, and conversation events. - [Overview](https://docs.tavus.io/sections/conversational-video-interface/component-library/overview.md): Learn how our Tavus Conversational Video Interface (CVI) Component Library can help you go live in minutes. - [Audio-Only Conversation](https://docs.tavus.io/sections/conversational-video-interface/conversation/customizations/audio-only.md): Start a conversation in audio-only mode, perfect for voice-only or low-bandwidth environments. - [Background Customizations](https://docs.tavus.io/sections/conversational-video-interface/conversation/customizations/background-customizations.md): Apply a green screen or custom background for a personalized visual experience. - [Call Duration and Timeout](https://docs.tavus.io/sections/conversational-video-interface/conversation/customizations/call-duration-and-timeout.md): Configure call duration and timeout behavior to manage how and when a conversation ends. - [Closed Captions](https://docs.tavus.io/sections/conversational-video-interface/conversation/customizations/closed-captions.md): Enable closed captions for accessibility or live transcription during conversations. - [Overview](https://docs.tavus.io/sections/conversational-video-interface/conversation/overview.md): Learn how to customize identity and advanced settings for a conversation to suit your needs. - [AI Interviewer](https://docs.tavus.io/sections/conversational-video-interface/conversation/usecases/ai-interviewer.md): Engage with the AI Interviewer persona to run structured, conversational interview simulations. - [Customer Service Agent](https://docs.tavus.io/sections/conversational-video-interface/conversation/usecases/customer-service.md): Engage in real-time customer support conversations that adapt to user emotions and behavior. - [Health Care Consultant](https://docs.tavus.io/sections/conversational-video-interface/conversation/usecases/health-care.md): Engage with the health care consultant persona for basic health concerns. - [History Teacher](https://docs.tavus.io/sections/conversational-video-interface/conversation/usecases/history-teacher.md): Engage in historical discussions with our History Teacher persona. - [Sales Coach](https://docs.tavus.io/sections/conversational-video-interface/conversation/usecases/sales-coach.md): Engage with the Sales Coach persona to simulate real-time sales conversations. - [Tavus Researcher](https://docs.tavus.io/sections/conversational-video-interface/conversation/usecases/tavus-researcher.md): Engage with the Tavus Researcher persona to learn more about Tavus - [FAQs](https://docs.tavus.io/sections/conversational-video-interface/faq.md): Frequently asked questions about Tavus's Conversational Video Interface. - [Interactions Protocol](https://docs.tavus.io/sections/conversational-video-interface/interactions-protocols/overview.md): Control conversations with a Replica using the defined protocol by sending and listening to interaction events. - [Knowledge Base](https://docs.tavus.io/sections/conversational-video-interface/knowledge-base.md): Upload documents to your knowledge base for personas to reference during conversations. - [Language Support](https://docs.tavus.io/sections/conversational-video-interface/language-support.md): Customize the conversation language using full language names supported by Tavus TTS engines. - [Memories](https://docs.tavus.io/sections/conversational-video-interface/memories.md): Memories let personas remember information across conversations, allowing participants to have personalized, flowing conversations across multiple sessions. - [Overview](https://docs.tavus.io/sections/conversational-video-interface/overview-cvi.md): CVI enables real-time, human-like video interactions through configurable lifelike replicas. - [Guardrails](https://docs.tavus.io/sections/conversational-video-interface/persona/guardrails.md): Guardrails provide your persona with strict behavioral guidelines that will be rigorously followed throughout every conversation. - [Large Language Model (LLM)](https://docs.tavus.io/sections/conversational-video-interface/persona/llm.md): Learn how to use Tavus-optimized LLMs or integrate your own custom LLM. - [Tool Calling for LLM](https://docs.tavus.io/sections/conversational-video-interface/persona/llm-tool.md): Set up tool calling to trigger functions from user speech using Tavus-hosted or custom LLMs. - [Objectives](https://docs.tavus.io/sections/conversational-video-interface/persona/objectives.md): Objectives are goal-oriented instructions to define the desired outcomes and flow of your conversations. - [Overview](https://docs.tavus.io/sections/conversational-video-interface/persona/overview.md): Define how your persona behaves, responds, and speaks by configuring layers and modes. - [Perception](https://docs.tavus.io/sections/conversational-video-interface/persona/perception.md): Learn how to configure the perception layer with Raven to enable the real-time visual understanding. - [Tool Calling for Perception](https://docs.tavus.io/sections/conversational-video-interface/persona/perception-tool.md): Configure tool calling with `raven-0` to trigger functions from visual input. - [Stock Personas](https://docs.tavus.io/sections/conversational-video-interface/persona/stock-personas.md): Tavus offers pre-built personas to help you get started quickly. - [Speech-to-Text (STT)](https://docs.tavus.io/sections/conversational-video-interface/persona/stt.md): Learn how to configure the STT layer to enable smart turn detection and enhance conversational flow. - [Text-to-Speech (TTS)](https://docs.tavus.io/sections/conversational-video-interface/persona/tts.md): Discover how to integrate custom voices from third-party TTS engines for multilingual or localized speech output. - [Conversation Recordings](https://docs.tavus.io/sections/conversational-video-interface/quickstart/conversation-recordings.md): Enable conversation recording and store it in your S3 bucket for on-demand access. - [Customize Conversation UI](https://docs.tavus.io/sections/conversational-video-interface/quickstart/customize-conversation-ui.md): Experience a conversation in a custom Daily UI — styled to match your preference. - [Use the Full Pipeline](https://docs.tavus.io/sections/conversational-video-interface/quickstart/use-the-full-pipeline.md): Create your first persona using the full pipeline and start a conversation in seconds. - [Errors and Status Details](https://docs.tavus.io/sections/errors-and-status-details.md): Identify errors and status details encountered when using the Tavus platform. - [Append Conversational Context Interaction](https://docs.tavus.io/sections/event-schemas/conversation-append-context.md): This is an event developers may broadcast to Tavus. By broadcasting this event, you are able to append additional context to the existing `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 the initial `conversational_context`. Learn more about the `conversational_context`: [Create Conversation](/api-reference/conversations/create-conversation) - [Echo Interaction](https://docs.tavus.io/sections/event-schemas/conversation-echo.md): 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). - [Interrupt Interaction](https://docs.tavus.io/sections/event-schemas/conversation-interrupt.md): 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). - [Overwrite Conversational Context Interaction](https://docs.tavus.io/sections/event-schemas/conversation-overwrite-context.md): 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 configuring the `conversational_context`. - [Perception Analysis Event](https://docs.tavus.io/sections/event-schemas/conversation-perception-analysis.md): This is an event broadcasted by Tavus. A perception analysis event is fired after ending a conversation, when the replica has finished summarizing what was visually observed throughout the call. This is a feature that is only available when the persona has `raven-0` specified in the [perception layer](/sections/conversational-video-interface/persona/perception#end-of-call-perception-analysis). - [Perception Tool Call Event](https://docs.tavus.io/sections/event-schemas/conversation-perception-tool-call.md): This is an event broadcasted by Tavus. A perception tool call event is broadcasted by Tavus when a perception tool is triggered based on visual context. The event will contain the tool name, arguments, and encoded frames that triggered said tool call. Perception tool calls can be used to trigger automated actions in response to visual cues detected by the Raven perception system. For more details on perception tool calls, please take a look [here](/sections/conversational-video-interface/persona/perception-tool). - [Replica Interrupted Event](https://docs.tavus.io/sections/event-schemas/conversation-replica-interrupted.md): This is an event broadcasted by Tavus. An utterance event is broadcasted by Tavus when the replica is interrupted by the user while it is speaking. - [Replica Started/Stopped Speaking Event](https://docs.tavus.io/sections/event-schemas/conversation-replica-started-stopped-speaking.md): This is an event broadcasted by Tavus. A `replica.started_speaking/stopped_speaking event` is broadcasted by Tavus at specific times: `conversation.replica.started_speaking` means the replica has just started speaking. `conversation.replica.stopped_speaking` means the replica has just stopped speaking. When the `replica.stopped_speaking` event is sent, a `duration` field will be included in the event's `properties` object, indicating how long the replica was speaking for in seconds. This value may also be null. These events are intended to act as triggers for actions within your application. For instance, you may want to start a video or show a slide at times related to when the replica started or stopped speaking. The `inference_id` can be used to correlate other events and tie things like `conversation.utterance or tool_call` together. - [Text Respond Interaction](https://docs.tavus.io/sections/event-schemas/conversation-respond.md): 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. - [Sensitivity Interaction](https://docs.tavus.io/sections/event-schemas/conversation-sensitivity.md): This is an event developers may broadcast to Tavus. By broadcasting this event, you are able to update the VAD (Voice Activity Detection) sensitivity of the replica in two dimensions. - `participant_pause_sensitivity` - `participant_interrupt_sensitivity` The supported values are `low`, `medium`, and `high`. [Learn more about configuring the `sensitivity`](/sections/conversational-video-interface/persona/stt). - [Tool Call Event](https://docs.tavus.io/sections/event-schemas/conversation-toolcall.md): This is an event broadcasted by Tavus. A tool call event denotes when an LLM tool call should be made on the client side. The event will contain the name and arguments of the function that should be called. Tool call events can be used to call external APIs or databases. > **Note**: it is the client's responsibility to take action on these tool calls, as Tavus will not execute code server-side. For more details on LLM tool calls, please take a look [here](/sections/conversational-video-interface/persona/llm-tool). - [User Started/Stopped Speaking Event](https://docs.tavus.io/sections/event-schemas/conversation-user-started-stopped-speaking.md): This is an event broadcasted by Tavus. A `user.started_speaking/stopped_speaking event` is broadcasted by Tavus at specific times: `conversation.user.started_speaking` means the user has just started speaking. `conversation.user.stopped_speaking` means the user has just stopped speaking. These events are intended to act as triggers for actions within your application. For instance, you may want to take some user facing action, or backend process at times related to when the user started or stopped speaking. The `inference_id` can be used to correlate other events and tie things like `conversation.utterance` or `tool_call` together. Keep in mind that with `speculative_inference`, the `inference_id` will frequently change while the user is speaking so that the `user.started_speaking inference_id` will not usually match the `conversation.utterance inference_id`. - [Utterance Event](https://docs.tavus.io/sections/event-schemas/conversation-utterance.md): This is an event broadcasted by Tavus. An utterance contains the content of the what was spoken and an indication of who spoke it (i.e. the user or replica). Each utterance event includes all of the words spoken by the user or replica measured from when the person started speaking to when they finished 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. To track when how long an utterance lasts, please refer to duration in "[User Started/Stopped Speaking](/sections/event-schemas/conversation-user-started-stopped-speaking)" and "[Replica Started/Stopped Speaking](/sections/event-schemas/conversation-replica-started-stopped-speaking)" events. - [Example Projects](https://docs.tavus.io/sections/example-projects.md) - [Embed Conversational Video Interface](https://docs.tavus.io/sections/integrations/embedding-cvi.md): Learn how to embed Tavus's Conversational Video Interface (CVI) into your site or app. - [LiveKit Agent](https://docs.tavus.io/sections/integrations/livekit.md): Integrate a Tavus Replica into LiveKit as the conversational video avatar. - [Pipecat](https://docs.tavus.io/sections/integrations/pipecat.md): Integrate a Tavus Replica into your Pipecat application as a participant or a video feed for the bot. - [Introduction](https://docs.tavus.io/sections/introduction.md): Leverage Tavus tools and guides to give your AI Agent real-time human-like perception and presence, bringing the human layer to AI. - [Models](https://docs.tavus.io/sections/models.md) - [Overview](https://docs.tavus.io/sections/replica/overview.md): Learn about Personal, Non-Human and Stock Replicas, and how to create your own. - [Quickstart](https://docs.tavus.io/sections/replica/quickstart.md): Create high-quality Personal or Non-human Replicas for use in conversations. - [Replica Training](https://docs.tavus.io/sections/replica/replica-training.md): Guide to recording a high-quality training video for generating a high-quality Replica using the Phoenix model. - [Stock Replicas](https://docs.tavus.io/sections/replica/stock-replicas.md): Browse ready-to-use digital presenters from Tavus for fast, high quality video creation. - [Troubleshooting](https://docs.tavus.io/sections/troubleshooting.md): Find solutions to common problems and get back on track quickly with our troubleshooting guides. - [Background Customizations](https://docs.tavus.io/sections/video/background-customizations.md): Customize AI video backgrounds with transparency, scrolling websites, or custom video sources. - [Overview](https://docs.tavus.io/sections/video/overview.md): Learn how to generate high-quality AI videos using Replicas. - [Quickstart](https://docs.tavus.io/sections/video/quickstart.md): Learn how to quickly generate high-quality videos using your personalized replica. - [Webhooks and Callbacks](https://docs.tavus.io/sections/webhooks-and-callbacks.md): Set up a webhook server to generate a callback URL that receives event notifications from Tavus API.