# Tavus > ## Documentation Index --- # Source: https://docs.tavus.io/sections/conversational-video-interface/conversation/usecases/ai-interviewer.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # AI Interviewer > Engage with the AI Interviewer persona to run structured, conversational interview simulations. ## AI Interviewer Configuration (`pe13ed370726`) ```json [expandable] theme={null} { "persona_name": "AI Interviewer", "pipeline_mode": "full", "system_prompt": "You are Mary, a seasoned Principal at a top-tier global consulting firm with multiple years of experience. You're conducting a first-round case interview for entry-level consultant candidates. You are professional yet approachable, aiming to assess both communication skills and basic problem-solving abilities.\n\nYour job is to assess the candidate through a structured but conversational case interview about SodaPop, a leading beverage company considering launching \"Light Bolt,\" a low-sugar, electrolyte-focused sports drink.\n\nYou'll guide the candidate through a high-level analysis of market positioning, profitability, and strategies to capture market share. As this is a first-round interview, you're more interested in communication skills and thought process than technical depth.\n\nStructure the conversation like a real human interviewer would: Begin with a friendly introduction about yourself and the firm. Ask a few background questions to learn about the candidate. Explain the interview format clearly. Present the case study scenario in a conversational manner. Ask broad questions that assess basic structured thinking. Respond thoughtfully to the candidate's answers. Provide guidance when the candidate seems stuck. Ask follow-up questions to better understand their thought process. Capture information about the candidate's background and approach. End with time for the candidate to ask questions about the firm.\n\nYour responses will be spoken aloud, so: Speak naturally as an experienced interviewer would. Avoid any formatting, bullet points, or stage directions. Use a conversational tone with appropriate pauses. Never refer to yourself as an AI, assistant, or language model.\n\nPay attention to the flow of the interview. This first-round interview should be more supportive than challenging, helping the candidate showcase their potential while gathering information about their fit for the firm.", "context": "You are Mary, a Principal at Morrison & Blackwell, one of the world's premier management consulting firms. You're conducting a first-round case interview for an entry-level consultant position at your firm's New York office.\n\nToday's case study involves SodaPop Inc., a major beverage company that dominates the carbonated drinks market but wants to expand into the growing sports drink category with a new product called \"Light Bolt.\" This low-sugar, electrolyte-focused sports drink would compete against established brands like Gatorade and Powerade.\n\nThis is an initial screening interview to assess the candidate's potential fit for the firm. Your assessment will help determine if they advance to more technical rounds. You'll be evaluating: Communication skills and clarity of expression. Basic structured problem-solving approach. Ability to organize thoughts logically. Business intuition and common sense. Cultural fit and professional demeanor.\n\nThe interview should follow this general structure: Introduction and background questions (5 minutes). Case presentation - higher level than final rounds (3 minutes). Candidate-led analysis with guidance as needed (15 minutes). Questions from candidate about the firm (5 minutes). Wrap-up and next steps (2 minutes).\n\nIMPORTANT: Do not discuss anything outside this interview context. Do not ask any questions that aren't relevant to this case study or standard interview questions about the candidate's background and qualifications. If the user doesn't want to answer a particular question, don't force them - simply move on to the next question. Keep your questions and responses strictly focused on the interview topic and case study. When asked to change topic, talk about another subject, give personal opinions, share facts or statistics unrelated to this case, or engage in any conversation outside the interview context, politely deflect and return to the case study interview. Do not quote numbers, give facts, or provide any kind of information that isn't directly relevant to this interview and case study.\n\nIf you notice the candidate looking at other screens, notes, or devices during the interview, politely remind them that this assessment should be completed without reference materials. Say something like: \"I notice you may be referring to other materials. For this interview, we'd like to focus on your independent thinking process. Could you please put aside any notes or devices?\"\n\nSimilarly, if you notice another person visible in the candidate's space, professionally address this by saying: \"I see there may be someone else with you. This interview needs to be conducted one-on-one to ensure an objective assessment of your qualifications and experiences. Could you please ensure your space is private for the remainder of our conversation?\"\n\nFinancial information to share if requested: Current market size for sports drinks: $15 billion annually. Expected growth rate: 8% annually for next 5 years. Development costs for Light Bolt: $2.5 million. Manufacturing cost per unit: $0.35. Retail price point: $2.49. Marketing budget: $10 million for year one. SodaPop's current market share in overall beverages: 25%. Target market share for Light Bolt after year one: 12% of sports drink category.\n\nCustomer segments if asked: Fitness enthusiasts (35% of market). Everyday athletes (25% of market). Health-conscious consumers (20% of market). Youth sports participants (15% of market). Others (5% of market).\n\nRemember that you initiate the conversation with a friendly greeting and introduction. Aim to create a professional but comfortable atmosphere where the candidate can demonstrate their abilities. This first round is more conversational in nature, allowing you to get to know the candidate while assessing their basic consulting potential. The candidate will join the call expecting an initial interview with a case component.\n\nDo not share your assessment or the interview outcome with the candidate directly, even if they ask for feedback or how they performed. If asked about results or next steps, respond with something like: \"Thank you for your time today. Our recruiting team will be reviewing all candidate assessments and will reach out to you with next steps. We typically aim to provide updates within two weeks.\" Maintain a positive, professional tone while redirecting to the formal process.", "layers": { "perception": { "perception_tools": [], "ambient_awareness_queries": [ "Does the candidate appear to be looking at other screens, notes, or devices during the interview?", "Is there another person in the scene?", "Are there any visual indicators of extreme nervousness (excessive fidgeting, rigid posture, or unusual facial expressions) that might affect performance?" ], "perception_model": "raven-0", "perception_tool_prompt": "", "tool_prompt": "" }, "conversational_flow": { "turn_detection_model": "sparrow-1", "turn_taking_patience": "high", "replica_interruptibility": "low" } } } ``` This predefined persona is configured to conduct consistent and scalable candidate interviews. It includes: * **Persona Identity**: Named Mary, a seasoned, professional AI interviewer designed to conduct first-round case interviews with a structured yet approachable style, focusing on assessing communication and problem-solving skills. * **Full Pipeline Mode**: Enables the full Tavus conversational pipeline, including Perception, STT, LLM, and TTS. * **System Prompt**: Provides detailed behavioral guidance to maintain a natural, spoken-word tone that is professional and supportive. * **Model Layers**: * **Perception Configuration**: Uses `raven-0` perception model to monitor candidate behavior and environment for visual cues like distraction or nervousness. - **Conversational Flow Layer**: Uses `sparrow-1` turn detection model with high turn-taking patience to allow candidates time to think and respond, and low replica interruptibility for professional, uninterrupted interview flow. ## Create a Conversation with the AI Interviewer Persona Use the following request body example: ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "pe13ed370726" }' ``` Replace `` with your actual API key. You can generate one in the Developer Portal. Click the link in the ***`conversation_url`*** field to join the conversation: ```json theme={null} { "conversation_id": "cae87c605c7e347d", "conversation_name": "New Conversation 1751877296483", "conversation_url": "", "status": "active", "callback_url": "", "created_at": "2025-07-07T08:34:56.504765Z" } ``` --- # Source: https://docs.tavus.io/sections/conversational-video-interface/conversation/customizations/audio-only.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Audio-Only Conversation > Start a conversation in audio-only mode, perfect for voice-only or low-bandwidth environments. ## Create an Audio Only Conversation All features in the persona's pipeline, including STT, Perception, and TTS, remain fully active in audio-only mode. The only change is that replica video rendering is not included. In this example, we will use stock persona ID ***pdced222244b*** (Sales Coach). To enable audio-only mode, set the `audio_only` parameter to `true` when creating the conversation: ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "pdced222244b", "audio_only" true }' ``` Replace `` with your actual API key. You can generate one in the Developer Portal. To join the conversation, click the link in the ***conversation\_url*** field from the response: ```json theme={null} { "conversation_id": "cd7e3eac05ede40c", "conversation_name": "New Conversation 1751268887110", "conversation_url": "", "status": "active", "callback_url": "", "created_at": "2025-06-30T07:34:47.131571Z" } ``` --- # Source: https://docs.tavus.io/api-reference/authentication.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Authentication > Learn how to generate and use your Tavus API key to authenticate requests. To use the Tavus API, you need an API key to authenticate your requests. This key verifies that requests are coming from your Tavus account. ## Get the API key 1. Go to the Developer Portal and select **API Key** from the sidebar menu. 2. Click **Create New Key** to begin generating your API key. 3. Enter a name for the key and (optional) specify allowed IP addresses, then click **Create API Key**. 4. Copy your newly created API key and store it securely. **Remember that your API key is a secret!** Never expose it in client-side code such as browsers or apps. Always load your API key securely from environment variables or a server-side configuration. ## Make Your First Call Authentication to the API is performed via HTTP Basic Auth. To authenticate with Tavus's API endpoints, you must provide the API Key in the header, as shown below. ```curl Authentication Header theme={null} 'x-api-key: ' ``` For example, you are using the [POST - Create Conversation](/api-reference/conversations/create-conversation) endpoint to create a real-time video call session with a Tavus replica. In this scenario, you can send an API request and replace `` with your actual API Key. ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "replica_id": "r9d30b0e55ac", "persona_id": "pe13ed370726", "conversation_name": "Interview User" }' ``` --- # Source: https://docs.tavus.io/sections/video/background-customizations.md # Source: https://docs.tavus.io/sections/conversational-video-interface/conversation/customizations/background-customizations.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Background Customizations > Apply a green screen or custom background for a personalized visual experience. ## Customize Background in Conversation Setup In this example, we will use stock replica ID ***rfe12d8b9597*** (Nathan) and stock persona ID ***pdced222244b*** (Sales Coach). To apply the green screen background, set the `apply_greenscreen` parameter to `true` when creating the conversation: ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "pdced222244b", "replica_id": "rfe12d8b9597", "callback_url": "https://yourwebsite.com/webhook", "conversation_name": "Improve Sales Technique", "conversational_context": "I want to improve my sales techniques. Help me practice handling common objections from clients and closing deals more effectively.", "properties": { "apply_greenscreen": true } }' ``` Replace `` with your actual API key. You can generate one in the Developer Portal. The above request will return the following response: ```json theme={null} { "conversation_id": "ca4301628cb9", "conversation_name": "Improve Sales Technique", "conversation_url": "", "status": "active", "callback_url": "https://yourwebsite.com/webhook", "created_at": "2025-05-13T06:42:58.291561Z" } ``` The replica will appear with a green background. You can customize it using a WebGL-based on the front-end. This allows you to apply a different color or add a custom image. To preview this feature, try our Green Screen Sample App. Paste the conversation URL to modify the background. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/component-library/blocks.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Blocks > High-level component compositions that combine multiple UI elements into complete interface layouts ### Conversation block The Conversation component provides a complete video chat interface for one-to-one conversations with AI replicas ```bash theme={null} npx @tavus/cvi-ui@latest add conversation-01 ``` The `Conversation` component provides a complete video chat interface for one-to-one conversations with AI replicas, featuring main video display, self-view preview, and integrated controls. **Features:** * **Main Video Display**: Large video area showing the AI replica or screen share * **Self-View Preview**: Small preview window showing local camera feed * **Screen Sharing Support**: Automatic switching between replica video and screen share * **Device Controls**: Integrated microphone, camera, and screen share controls * **Error Handling**: Graceful handling of camera/microphone permission errors * **Responsive Layout**: Adaptive design for different screen sizes **Props:** * `conversationUrl` (string): Daily.co room URL for joining * `onLeave` (function): Callback when user leaves the conversation ```tsx theme={null} import { Conversation } from './components/cvi/components/conversation'; ``` ```tsx theme={null} handleLeaveCall()} /> ``` Preview Conversation Block Preview ### Hair Check The HairCheck component provides a pre-call interface for users to test and configure their audio/video devices before joining a video chat. ```bash theme={null} npx @tavus/cvi-ui@latest add hair-check-01 ``` The `HairCheck` component provides a pre-call interface for users to test and configure their audio/video devices before joining a video chat. **Features:** * **Device Testing**: Live preview of camera feed with mirror effect * **Permission Management**: Handles camera and microphone permission requests * **Device Controls**: Integrated microphone and camera controls * **Join Interface**: Call-to-action button to join the video chat * **Responsive Design**: Works on both desktop and mobile devices **Props:** * `isJoinBtnLoading` (boolean): Shows loading state on join button * `onJoin` (function): Callback when user clicks join * `onCancel` (function, optional): Callback when user cancels ```tsx theme={null} import { HairCheck } from './components/cvi/components/hair-check'; ``` ```tsx theme={null} ``` Preview Haircheck Block Preview --- # Source: https://docs.tavus.io/sections/conversational-video-interface/conversation/customizations/call-duration-and-timeout.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Call Duration and Timeout > Configure call duration and timeout behavior to manage how and when a conversation ends. ## Create a Conversation with Custom Duration and Timeout In this example, we will use stock replica ID ***rfe12d8b9597*** (Nathan) and stock persona ID ***pdced222244b*** (Sales Coach). Use the following request body example: ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "pdced222244b", "replica_id": "rfe12d8b9597", "callback_url": "https://yourwebsite.com/webhook", "conversation_name": "Improve Sales Technique", "conversational_context": "I want to improve my sales techniques. Help me practice handling common objections from clients and closing deals more effectively.", "properties": { "max_call_duration": 1800, "participant_left_timeout": 60, "participant_absent_timeout": 120 } }' ``` Replace `` with your actual API key. You can generate one in the Developer Portal. The request example above includes the following customizations: | Parameter | Description | | :--------------------------- | :---------------------------------------------------------------------------------------------- | | `max_call_durations` | Sets the maximum call length in seconds. Maximum: 3600 seconds. | | `participant_left_timeout` | Time (in seconds) to wait before ending the call after the last participant leaves. Default: 0. | | `participant_absent_timeout` | Time (in seconds) to end the call if no one joins after it's created. Default: 300. | To join the conversation, click the link in the ***conversation\_url*** field from the response: ```json theme={null} { "conversation_id": "ca4301628cb9", "conversation_name": "Improve Sales Technique", "conversation_url": "", "status": "active", "callback_url": "https://yourwebsite.com/webhook", "created_at": "2025-05-13T06:42:58.291561Z" } ``` Based on the call duration and timeout settings above: * The conversation will automatically end after 1800 seconds (30 minutes), regardless of activity. * If the participant leaves the conversation, it will end 60 seconds after they disconnect. * If the participant is present but inactive (e.g., not speaking or engaging), the conversation ends after 120 seconds of inactivity. --- # Source: https://docs.tavus.io/sections/changelog/changelog.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Changelog ## New Features * **Persona Editing in Developer Portal:** We've added new editing capabilities to help you refine your Personas more efficiently. You can now update system prompt, context, and layers directly in our Developer Portal, plus duplicate existing Personas to quickly create variations or use them as starting points for new projects. Find these new features in your Persona Library at platform.tavus.io. ## New Features * **Llama 4 Support:** Your persona just got even smarter, thanks to Meta's Llama 4 model 🧠 You can start using Llama 4 by specifying `tavus-llama-4` for the LLM `model` value when creating a new persona or updating an existing one. Click here to learn more! ## New Features * **React Component Library:** Developers can build with Tavus even faster now with our pre-defined components 🚀 Click here to learn more! ## New Features * **Multilingual Conversation Support:** CVI now supports dynamic multilingual conversations through automatic language detection. Set the language parameter to "multilingual" and CVI will automatically detect the user's spoken language and respond in the same language using ASR technology. * **Audio-Only Mode:** CVI now supports audio-only conversations with advanced perception (powered by Raven) and intelligent turn-taking (powered by Sparrow-1). Set `audio_only=true` in your create conversation request to enable streamlined voice-first interactions. ## Enhancements * **Fixed CVI responsiveness issue:** Resolved an issue where CVI would occasionally ignore very brief user utterances. All user inputs, regardless of length, now receive consistent responses. * **Expanded tavus-llama-4 context window:** Increased maximum context window to 32,000 tokens. For optimal performance and response times, we recommend staying under 25,000 tokens. ## Enhancements * Reduced conversation boot time by 58% (p50). ## Changes * Added a new recording requirement to Replica Training: Start the talking segment with a big smile. ## Enhancements * Added echo and respond events to conversational context. ## Enhancements * **Major Phoenix 3 Enhancements for CVI**: * Increased frame rate from 27fps to 32fps, significantly boosting smoothness. * Reduced Phoenix step's warm boot time by 60% (from 5s to 2s). * Lipsync accuracy improved by \~22% based on AVSR metric. * Resolved blurriness and choppiness at conversation start. * Enhanced listening mode with more natural micro expressions (eyebrow movements, subtle gestures). * Greenscreen mode speed boosted by an additional \~1.5fps. * **Enhanced CVI Audio Quality**: Audio clicks significantly attenuated, providing clearer conversational audio. * **Phoenix 3 Visual Artifacts Fix**: Resolved visual artifacts in 4K videos on Apple devices, eliminating black spot artifacts in thumbnails. ## New Features * Launched LiveKit Integration: With Tavus video agents now integrated into LiveKit, you can add humanlike video responses to your voice agents in seconds. * Persona API: Enabled patch updates to personas. ## Enhancements * Resolved TTS (Cartesia) stability issues and addressed hallucination. * **Phoenix 3 Improvements**: * Fixed blinking/jumping issues and black spots in videos. * FPS optimization to resolve static and audio crackling. ## Enhancements * **Replica API**: * Enhanced Error Messaging for Training Videos. * Optimized Auto QA for Training Videos. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/conversation/customizations/closed-captions.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Closed Captions > Enable closed captions for accessibility or live transcription during conversations. ## Enable Captions in Real Time During the Conversation In this example, we will use stock replica ID ***rfe12d8b9597*** (Nathan) and stock persona ID ***pdced222244b*** (Sales Coach). To enable closed captions, set the `enable_closed_captions` parameter to `true` when creating the conversation: ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "pdced222244b", "replica_id": "rfe12d8b9597", "callback_url": "https://yourwebsite.com/webhook", "conversation_name": "Improve Sales Technique", "conversational_context": "I want to improve my sales techniques. Help me practice handling common objections from clients and closing deals more effectively.", "properties": { "enable_closed_captions": true } }' ``` Replace `` with your actual API key. You can generate one in the Developer Portal. To join the conversation, click the link in the ***conversation\_url*** field from the response: ```json theme={null} { "conversation_id": "ca4301628cb9", "conversation_name": "Improve Sales Technique", "conversation_url": "", "status": "active", "callback_url": "https://yourwebsite.com/webhook", "created_at": "2025-05-13T06:42:58.291561Z" } ``` Closed captions will appear during the conversation whenever you or the replica speaks. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/component-library/components.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Components > Learn about our pre-built React components to accelerate integrating the Tavus Conversational Video Interface (CVI) into your application. # Components ### CVI Provider The `CVIProvider` component wraps your app with the Daily.co provider context, enabling all Daily React hooks and components to function. ```bash theme={null} npx @tavus/cvi-ui@latest add cvi-provider ``` The `CVIProvider` component wraps your app with the Daily.co provider context, enabling all Daily React hooks and components to function. **Features:** * Provides Daily.co context to all child components * Required for using Daily React hooks and video/audio components * Simple wrapper for app-level integration **Props:** * `children` (ReactNode): Components to be wrapped by the provider ```tsx theme={null} import { CVIProvider } from './cvi-provider'; ``` ```tsx theme={null} {/* your app components */} ``` ### AudioWave The `AudioWave` component provides real-time audio level visualization for video chat participants, displaying animated bars that respond to audio input levels. ```bash theme={null} npx @tavus/cvi-ui@latest add audio-wave ``` The `AudioWave` component provides real-time audio level visualization for video chat participants, displaying animated bars that respond to audio input levels. **Features:** * **Real-time Audio Visualization**: Three animated bars that respond to audio levels * **Active Speaker Detection**: Visual distinction between active and inactive speakers * **Performance Optimized**: Uses `requestAnimationFrame` for smooth animations * **Responsive Design**: Compact circular design that fits well in video previews * **Audio Level Scaling**: Intelligent volume scaling for consistent visual feedback **Props:** * `id` (string): The participant's session ID to monitor audio levels for ```tsx theme={null} import { AudioWave } from './audio-wave'; ``` ```tsx theme={null} ``` ### Device Select The `device-select` module provides advanced device selection controls, including dropdowns for choosing microphones and cameras, and integrated toggle buttons. ```bash theme={null} npx @tavus/cvi-ui@latest add device-select ``` The `device-select` module provides advanced device selection controls, including dropdowns for choosing microphones and cameras, and integrated toggle buttons. **Exported Components:** * **`MicSelectBtn`**: Microphone toggle button with device selection * **`CameraSelectBtn`**: Camera toggle button with device selection * **`ScreenShareButton`**: Button to toggle screen sharing **Features:** * Integrated device selection and toggling * Dropdowns for camera/microphone selection * Visual state indicators and accessibility support * Uses Daily.co device management hooks * CSS modules for styling ```tsx theme={null} import { MicSelectBtn, CameraSelectBtn, ScreenShareButton } from './device-select'; ``` ```tsx theme={null} ``` ### Media Controls The `media-controls` module provides simple toggle buttons for microphone, camera, and screen sharing, designed for direct use in video chat interfaces. ```bash theme={null} npx @tavus/cvi-ui@latest add media-controls ``` The `media-controls` module provides simple toggle buttons for microphone, camera, and screen sharing, designed for direct use in video chat interfaces. **Exported Components:** * **`MicToggleButton`**: Toggles microphone mute/unmute state * **`CameraToggleButton`**: Toggles camera on/off * **`ScreenShareButton`**: Toggles screen sharing on/off **Features:** * Simple, accessible toggle buttons * Visual state indicators (muted, unmuted, on/off) * Disabled state when device is not ready * Uses Daily.co hooks for device state * CSS modules for styling ```tsx theme={null} import { MicToggleButton, CameraToggleButton, ScreenShareButton } from './media-controls'; ``` ```tsx theme={null} ``` --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-append-context.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Append Conversational Context Interaction > 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) --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-echo.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Echo Interaction > 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). --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-interrupt.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Interrupt 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). --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-overwrite-context.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Overwrite Conversational Context 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 configuring the `conversational_context`. --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-perception-analysis.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Perception Analysis Event > 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). --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-perception-tool-call.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Perception Tool Call Event > 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). --- # Source: https://docs.tavus.io/sections/conversational-video-interface/quickstart/conversation-recordings.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Conversation Recordings > Enable conversation recording and store it in your S3 bucket for on-demand access. ## Prerequisite Ensure that you have the following: * An S3 bucket with versioning enabled. ## Enable Conversation Recording 1. Create an IAM Policy with the following JSON definition: ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:ListBucketMultipartUploads", "s3:AbortMultipartUpload", "s3:ListBucketVersions", "s3:ListBucket", "s3:GetObjectVersion", "s3:ListMultipartUploadParts" ], "Resource": [ "arn:aws:s3:::your-bucket-name", "arn:aws:s3:::your-bucket-name/*" ] } ] } ``` Replace `your-bucket-name` with your actual bucket name. 2. Create an IAM role with the following value: * Select **"Another AWS account"** and enter this account ID: ***291871421005***. * Enable **"Require external ID"**, and use: **tavus**. * **"Max session duration"** to **12 hours**. Note down your ARN (e.g., `arn:aws:iam::123456789012:role/CVIRecordingRole`). Use the following request body example: Remember to change the following values: * ``: Your actual API key. You can generate one in the Developer Portal. * `aws_assume_role_arn`: Your AWS ARN. * `recording_s3_bucket_region`: Your S3 region. * `recording_s3_bucket_name`: Your S3 bucket name. ```shell cURL {7-10} theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "properties": { "enable_recording": true, "aws_assume_role_arn": "", "recording_s3_bucket_region": "", "recording_s3_bucket_name": "" }, "replica_id": "ra066ab28864" }' ``` `enable_recording` allows recording to be possible, but it doesn't start recording automatically. To begin and end recordings, users must do it manually or trigger it through frontend code. To join the conversation, click the **link** in the ***`conversation_url`*** field from the response: ```json theme={null} { "conversation_id": "c93a7ead335b", "conversation_name": "New Conversation 1747654283442", "conversation_url": "", "status": "active", "callback_url": "", "created_at": "2025-05-16T02:09:22.675928Z" } ``` You can access the recording file in your S3 bucket. `enable_recording` (from Step 2 above) allows recording to be possible, but it doesn't start recording automatically. To begin and end recordings, end users must do it manually (start/stop recording button in the UI) or you can trigger it through frontend code. You can use frontend code via Daily's SDK to start-recording. To ensure recordings are generated consistently, be sure to wait for the `joined-meeting` event first. ```javascript theme={null} const call = Daily.createCallObject(); call.on('joined-meeting', () => { call.startRecording(); // room must have enable_recording set }); ``` --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-replica-interrupted.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Replica Interrupted Event > 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. --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-replica-started-stopped-speaking.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Replica Started/Stopped Speaking Event > 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. --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-respond.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Text Respond 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. --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-sensitivity.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Sensitivity Interaction > 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). --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-toolcall.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Tool Call Event > 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). --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-user-started-stopped-speaking.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # User Started/Stopped Speaking Event > 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`. --- # Source: https://docs.tavus.io/sections/event-schemas/conversation-utterance.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Utterance Event > 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. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/persona/conversational-flow.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Conversational Flow > Learn how to configure the Conversational Flow layer to fine-tune turn-taking and interruption handling behavior. The **Conversational Flow Layer** in Tavus gives you precise control over the natural dynamics of conversation. This layer allows you to customize how your replica handles turn-taking and interruptions to create conversational experiences that match your specific use case. ## Understanding Conversational Flow Conversational flow encompasses the subtle dynamics that make conversations feel natural: * **Turn-taking**: How the replica decides when to speak and when to listen * **Interruptibility**: How easily the replica can be interrupted by the user All conversational flow parameters are optional. When not explicitly configured, the layer remains inactive. However, if you configure any single parameter, the system will apply sensible defaults to all other parameters to ensure consistent behavior. ## Configuring the Conversational Flow Layer If you're migrating from sparrow-0 (formerly called `smart_turn_detection` on the STT Layer) then check out the [migration guide here](/sections/troubleshooting#conversational-flow-vs-stt-relationship-and-migration). Define the conversational flow layer under the `layers.conversational_flow` object. Below are the parameters available: ### 1. `turn_detection_model` Specifies the model used for detecting conversational turns. * **Options**: * `sparrow-1`: Advanced turn detection model - faster, more accurate, and more natural than `sparrow-0` **(recommended)** * `sparrow-0`: Legacy turn detection model (available for backward compatibility) * `time-based`: Simple timeout-based turn detection * **Default**: `sparrow-1` ```json theme={null} "turn_detection_model": "sparrow-1" ``` **Sparrow-1 is recommended for all use cases** as it provides superior performance with faster response times, higher accuracy, and more natural conversational flow compared to the legacy Sparrow-0. ### 2. `turn_taking_patience` Controls how eagerly the replica claims conversational turns. This affects both response latency and the likelihood of interrupting during natural pauses. * **Options**: * `low`: Eager and quick to respond. May interrupt natural pauses. Best for rapid-fire exchanges or customer service scenarios where speed is prioritized. * `medium` **(default)**: Balanced behavior. Waits for appropriate conversational cues before responding. * `high`: Patient and waits for clear turn completion. Ideal for thoughtful conversations, interviews, or therapeutic contexts. ```json theme={null} "turn_taking_patience": "medium" ``` **Use Cases:** * `low`: Fast-paced customer support, quick information lookups, casual chat * `medium`: General purpose conversations, sales calls, presentations * `high`: Medical consultations, legal advice, counseling sessions ### 3. `replica_interruptibility` Controls how sensitive the replica is to user speech while the replica is talking. Determines whether the replica stops to listen or keeps speaking when interrupted. * **Options**: * `low`: Less interruptible. The replica keeps talking through minor interruptions. * `medium` **(default)**: Balanced sensitivity. Responds to clear interruption attempts. * `high`: Highly sensitive. Stops easily when the user begins speaking, maximizing user control. ```json theme={null} "replica_interruptibility": "high" ``` **Use Cases:** * `low`: Educational content delivery, storytelling, guided onboarding * `medium`: Standard conversations, interviews, consultations * `high`: User-driven conversations, troubleshooting, interactive support ## Default Behavior When the conversational flow layer is not configured, all parameters default to `None` and the layer remains inactive. However, if you configure **any single parameter**, the system automatically applies the following defaults to ensure consistent behavior: * `turn_detection_model`: `sparrow-1` * `turn_taking_patience`: `medium` * `replica_interruptibility`: `medium` ## Example Configurations The following example configurations demonstrate how to tune conversational timing and interruption behavior for different use cases. Use `turn_taking_patience` to bias how quickly the replica responds after a user finishes speaking. Set it high when the replica should avoid interrupting, and low when fast responses are preferred. Use `replica_interruptibility` to control how easily the replica recalculates its response when interrupted; lower values are recommended for most experiences, with higher values reserved for cases where frequent, abrupt interruptions are desirable. Sparrow-1 dynamically handles turn-taking in all cases, with these settings acting as guiding biases rather than hard rules. ### Example 1: Customer Support Agent Fast, responsive, and easily interruptible for customer-driven conversations: ```json theme={null} { "persona_name": "Support Agent", "system_prompt": "You are a helpful customer support agent...", "pipeline_mode": "full", "default_replica_id": "rfe12d8b9597", "layers": { "conversational_flow": { "turn_detection_model": "sparrow-1", "turn_taking_patience": "low", "replica_interruptibility": "medium" } } } ``` ### Example 2: Medical Consultation Patient, thoughtful, with engaged listening for sensitive conversations: ```json theme={null} { "persona_name": "Medical Advisor", "system_prompt": "You are a compassionate medical professional...", "pipeline_mode": "full", "default_replica_id": "rfe12d8b9597", "layers": { "conversational_flow": { "turn_detection_model": "sparrow-1", "turn_taking_patience": "high", "replica_interruptibility": "verylow" } } } ``` ### Example 3: Educational Instructor Delivers complete information with minimal interruption: ```json theme={null} { "persona_name": "Instructor", "system_prompt": "You are an experienced educator teaching complex topics...", "pipeline_mode": "full", "default_replica_id": "rfe12d8b9597", "layers": { "conversational_flow": { "turn_detection_model": "sparrow-1", "turn_taking_patience": "medium", "replica_interruptibility": "low" } } } ``` ### Example 4: Minimal Configuration Configure just one parameter—others will use defaults: ```json theme={null} { "persona_name": "Quick Chat", "system_prompt": "You are a friendly conversational AI...", "pipeline_mode": "full", "default_replica_id": "rfe12d8b9597", "layers": { "conversational_flow": { "turn_taking_patience": "low" } } } ``` In this example, the system will automatically set: * `turn_detection_model`: `sparrow-1` * `replica_interruptibility`: `medium` ## Best Practices ### Match Flow to Use Case Choose conversational flow settings that align with your application's purpose: * **Speed-critical applications**: Use `low` turn-taking patience and `high` interruptibility * **Thoughtful conversations**: Use `high` turn-taking patience * **Important information delivery**: Use `low` interruptibility * **User-controlled interactions**: Use `high` interruptibility ### Consider Cultural Context Conversational norms vary across cultures. Some cultures prefer: * More overlap and interruption (consider lower commitment, higher interruptibility) * Clear turn-taking with pauses (consider higher patience, lower interruptibility) ### Test with Real Users Conversational flow preferences can be subjective. Test your configuration with representative users to ensure it feels natural for your audience. Refer to the Create Persona API for the complete API specification and additional persona configuration options. --- # Source: https://docs.tavus.io/api-reference/conversations/create-conversation.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. > 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). # Create Conversation Required parameters vary depending on the use case: **Full Pipeline Conversation:** * `persona_id` * `replica_id` **Audio-Only Conversation:** * `persona_id` * `replica_id` * `audio_only` - `replica_id` is **required** if the persona does **not** have a default replica. - `replica_id` is **optional** if the persona **does** have a default replica. - If both a default replica and `replica_id` are provided, the supplied `replica_id` will **override** the default. ## OpenAPI ````yaml post /v2/conversations openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/conversations: post: tags: - Conversations summary: Create Conversation description: > 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. - **If your persona does not have a default replica**, the `replica_id` is required. - **If your persona has a default replica**, the `replica_id` is not required. - **If your persona has a default replica and you define `replica_id`**, it will override the persona's default replica. operationId: createConversation requestBody: content: application/json: schema: type: object properties: replica_id: type: string description: >- The unique identifier for the replica that will join the conversation. **Each request must have a valid `replica_id` value that's either directly passed in or as part of a persona**. example: rfe12d8b9597 persona_id: type: string description: > The unique identifier for the persona that the replica will use in the conversation. - **If your Persona does not have a valid `replica_id`, you must define the `replica_id` field.** - **If your Persona already has a valid `replica_id` and you provide one in the request, the `replica_id` provided in the request will be used instead of the one defined in your persona**. example: p9a95912 audio_only: type: boolean description: >- Specifies whether the interaction should be voice-only. **This field is required if you want to create an audio-only conversation**. example: 'false' callback_url: type: string description: >- A url that will receive webhooks with updates regarding the conversation state. example: https://yourwebsite.com/webhook conversation_name: type: string description: A name for the conversation. example: Improve Sales Technique conversational_context: type: string description: >- Optional context that will be appended to any context provided in the persona, if one is provided. example: >- I want to improve my sales techniques. Help me practice handling common objections from clients and closing deals more effectively. custom_greeting: type: string description: >- An optional custom greeting that the replica will give once a participant joines the conversation. example: Hey there! memory_stores: type: array items: type: string description: >- The memory stores to use for the conversation. The persona will have access to the existing memories in the store and will add newly made memories to the store as well. In most use cases, you will only need to pass in a single memory store. example: - anna document_ids: type: array items: type: string description: >- The ids of the documents that the persona will be able to access during the conversation. The `document_ids` are returned during the document creation process in the response of the [Get Document](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints. example: - doc_1234567890 document_retrieval_strategy: type: string description: >- The strategy to use for document retrieval. Possible values: `speed`, `quality`, `balanced`. Default is `balanced`. example: balanced document_tags: type: array items: type: string description: >- The tags of the documents that the replica will be able to access during the conversation. The tags are passed in the `document_tags` parameter of the [Create Document](/api-reference/documents/create-document) endpoint. The document tags do not have to be created explicitly, it is enough to pass in the tags during the document creation process. example: - sales - marketing test_mode: type: boolean description: >- If true, the conversation will be created but the replica will not join the call. This can be used for testing the conversation creation process without incurring any costs. Additionally, the conversation will be created with a status `ended` so it does not affect concurrency limits. example: false require_auth: type: boolean description: >- If true, creates a private room requiring authentication. A `meeting_token` will be returned in the response that must be used to join the conversation. Without a valid token, users will see 'You are not allowed to join this meeting.' example: false max_participants: type: integer minimum: 2 description: >- Maximum number of participants allowed in the conversation room. Must be at least 2 (the replica counts as one participant). example: 2 properties: type: object description: >- Optional properties that can be used to customize the conversation. properties: max_call_duration: type: integer description: >- The maximum duration of the call in seconds. The default max_call_duration is 3600 seconds (1 hour). Once the time limit specified by this parameter has been reached, the conversation will automatically shut down. example: 3600 participant_left_timeout: type: integer description: >- The duration in seconds after which the call will be automatically shut down once the last participant leaves. example: 60 participant_absent_timeout: type: integer description: >- Starting from conversation creation, the duration in seconds after which the call will be automatically shut down if no participant joins the call. Default is 300 seconds (5 minutes). example: 300 enable_recording: type: boolean description: >- If true, the user will be able to record the conversation. You can find more instructions on recording [here](/sections/conversational-video-interface/quickstart/conversation-recordings#conversation-recordings). example: true enable_closed_captions: type: boolean description: >- If true, the user will be able to display closed captions (subtitles) during the conversation. You can find more instructions on displaying closed captions if you are using your custom DailyJS components [here](https://docs.daily.co/reference/daily-js/events/transcription-events#transcription-message). You need to have an [event listener](https://docs.daily.co/reference/daily-js/events) on Daily that listens for app-messages. example: true apply_greenscreen: type: boolean description: >- If true, the background will be replaced with a greenscreen (RGB values: [0, 255, 155]). You can use WebGL on the frontend to make the greenscreen transparent or change its color. example: true language: type: string description: >- The language of the conversation. Please provide the FULL language name, not the two letter code, or specify `multilingual` for automatic language detection. When set to `multilingual`, CVI will use ASR language detection to identify the user's spoken language and respond accordingly. If you are using your own TTS voice, please ensure it supports the language you provide. If you are using a stock replica or default persona, please note that only Elevenlabs and Cartesia supported languages are available. You can find a full list of supported languages for Cartesia [here](https://docs.cartesia.ai/2024-11-13/build-with-cartesia/models#language-support), and for ElevenLabs [here](https://elevenlabs.io/languages). example: multilingual recording_s3_bucket_name: type: string description: >- The name of the S3 bucket where the recording will be stored. example: conversation-recordings recording_s3_bucket_region: type: string description: >- The region of the S3 bucket where the recording will be stored. example: us-east-1 aws_assume_role_arn: type: string description: >- The ARN of the role that will be assumed to access the S3 bucket. example: '' examples: Required Parameters Only: value: replica_id: rfe12d8b9597 persona_id: pdced222244b Full Customizations: value: replica_id: rfe12d8b9597 persona_id: pdced222244b callback_url: https://yourwebsite.com/webhook conversation_name: Improve Sales Technique conversational_context: >- I want to improve my sales techniques. Help me practice handling common objections from clients and closing deals more effectively. properties: max_call_duration: 1800 participant_left_timeout: 60 participant_absent_timeout: 120 language: multilingual enable_closed_captions: true apply_greenscreen: true Audio Only: value: replica_id: rfe12d8b9597 persona_id: pdced222244b audio_only: true Private Room: value: replica_id: rfe12d8b9597 persona_id: pdced222244b require_auth: true responses: '200': description: '' content: application/json: schema: type: object properties: conversation_id: type: string description: A unique identifier for the conversation. example: c123456 conversation_name: type: string description: The name of the conversation. example: A Meeting with Hassaan conversation_url: type: string description: >- A direct link to join the conversation. This link can be used to join the conversation directly or can be embedded in a website. example: https://tavus.daily.co/c123456 status: type: string description: >- The status of the conversation. Possible values: `active`, `ended`. example: active callback_url: type: string description: >- The url that will receive webhooks with updates of the conversation state. example: sample.com/callback created_at: type: string description: The date and time the conversation was created. example: meeting_token: type: string description: >- A short-lived JWT token required to join the conversation. Only returned when `require_auth` is true. Append as `?t=TOKEN` to the conversation URL or pass to Daily SDK's join() method. example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: >- There was an error creating the conversation, please reach out to support at support@tavus.io! '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid access token components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/documents/create-document.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Create Document > Upload documents to your knowledge base for personas to reference during conversations For now, our Knowledge Base only supports documents written in English and works best for conversations in English. We'll be expanding our Knowledge Base language support soon! Create a new document in your [Knowledge Base](/sections/conversational-video-interface/knowledge-base). When you hit this endpoint, Tavus kicks off the processing of the document, so it can be used as part of your knowledge base in conversations once processing is complete. The file size limit is 50MB. The processing can take up to a few minutes depending on file size. Currently, we support the following file formats: .pdf, .txt, .docx, .doc, .png, .jpg, .pptx, .csv, and .xlsx. Website URLs are also supported, where a website snapshot will be processed and transformed into a document. You can manage documents by adding tags using the `tags` field in the request body. Once created, you can add the document to your personas (see [Create Persona](/api-reference/personas/create-persona)) and your conversations (see [Create Conversation](/api-reference/conversations/create-conversation)). ## Website Crawling When creating a document from a website URL, you can optionally enable multi-page crawling by providing the `crawl` parameter. This allows the system to follow links from your starting URL and process multiple pages into a single document. ### Without Crawling (Default) By default, only the single page at the provided URL is scraped and processed. ### With Crawling When you include the `crawl` object, the system will: 1. Start at your provided URL 2. Follow links to discover additional pages 3. Process all discovered pages into a single document **Example request with crawling enabled:** ```json theme={null} { "document_name": "Company Knowledge Base", "document_url": "https://docs.example.com/", "crawl": { "depth": 2, "max_pages": 20 }, "callback_url": "https://your-server.com/webhook" } ``` ### Crawl Parameters | Parameter | Type | Description | | ----------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `depth` | integer (1-10) | How many levels deep to follow links from the starting URL. A depth of 1 means only pages directly linked from the starting URL. | | `max_pages` | integer (1-100) | Maximum number of pages to crawl. Processing stops once this limit is reached. | ### Rate Limits To prevent abuse, crawling has the following limits: * Maximum **100 crawl documents** per user * Maximum **5 concurrent crawls** at any time * **1-hour cooldown** between recrawls of the same document ### Keeping Content Fresh Once a document is created with crawl configuration, you can trigger a recrawl to fetch fresh content using the [Recrawl Document](/api-reference/documents/recrawl-document) endpoint. ## OpenAPI ````yaml post /v2/documents openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/documents: post: tags: - Documents summary: Create Document description: > Create a new document for your [Knowledge Base](/sections/conversational-video-interface/knowledge-base). This endpoint allows you to submit a document URL for processing and analysis. operationId: createDocument requestBody: content: application/json: schema: type: object properties: document_url: type: string description: The URL of the document or website to be processed example: https://docs.example.com/ document_name: type: string description: >- Optional name for the document. If not provided, a default name will be generated. example: Example Docs callback_url: type: string description: >- Optional URL that will receive status updates about the document processing example: https://your-server.com/webhook tags: type: array description: Optional array of tags to categorize the document items: type: string example: - docs - website crawl: type: object description: > Optional configuration for website crawling. When provided with a website URL, the system will follow links from the starting URL and process multiple pages. Without this parameter, only the single page at the URL is scraped. properties: depth: type: integer description: >- How many levels deep to follow links from the starting URL (1-10) minimum: 1 maximum: 10 example: 2 max_pages: type: integer description: Maximum number of pages to crawl (1-100) minimum: 1 maximum: 100 example: 10 required: - document_url responses: '200': description: Document created successfully content: application/json: schema: type: object properties: document_id: type: string description: Unique identifier for the created document example: d8-5c71baca86fc document_name: type: string description: Name of the document example: Example Docs document_url: type: string description: URL of the document or website example: https://docs.example.com/ status: type: string description: Current status of the document processing example: started progress: type: string nullable: true description: Progress indicator for document processing example: null created_at: type: string description: ISO 8601 timestamp of when the document was created example: '2024-01-01T12:00:00Z' updated_at: type: string description: ISO 8601 timestamp of when the document was last updated example: '2024-01-01T12:00:00Z' callback_url: type: string description: URL that will receive status updates example: https://your-server.com/webhook tags: type: array description: Array of document tags items: type: string example: - docs - website crawl_config: type: object nullable: true description: >- The crawl configuration used for this document (only present for crawled websites) properties: depth: type: integer description: Crawl depth setting example: 2 max_pages: type: integer description: Maximum pages setting example: 10 crawled_urls: type: array nullable: true description: >- List of URLs that were crawled (only present for crawled websites after processing completes) items: type: string example: - https://docs.example.com/ - https://docs.example.com/getting-started - https://docs.example.com/api last_crawled_at: type: string nullable: true description: ISO 8601 timestamp of when the document was last crawled example: '2024-01-01T12:00:00Z' crawl_count: type: integer nullable: true description: Number of times the document has been crawled example: 1 '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message example: 'Invalid request: document_url is required' '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: The error message example: Invalid access token '429': description: Too Many Requests - Crawl rate limit exceeded content: application/json: schema: type: object properties: error: type: string description: The error message example: >- Crawl document limit reached (100). Contact support@tavus.io to increase your limit. security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/guardrails/create-guardrails.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Create Guardrails > 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. ## OpenAPI ````yaml post /v2/guardrails openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/guardrails: post: tags: - Guardrails summary: Create Guardrails description: > 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. operationId: createGuardrails requestBody: content: application/json: schema: type: object properties: name: type: string description: >- A descriptive name for the collection of individual guardrails data: type: array description: A list of individual guardrails items: type: object properties: guardrail_name: type: string description: >- A descriptive name for the guardrail. Only alphanumeric characters and underscores are allowed. example: healthcare_compliance_guardrail guardrail_prompt: type: string description: >- The detailed prompt that defines the behavioral boundaries and restrictions example: >- Never discuss competitor products, share sensitive medical information, or provide medical advice outside approved guidelines modality: type: string description: >- The communication modality for the guardrail. If set to `verbal`, the guardrail will be enforced by the user's responses. If set `visual`, the guardrail can only be enforced by visual / perception cues observed by Raven enum: - verbal - visual default: verbal example: verbal callback_url: type: string description: >- Optional URL that will receive notifications when the guardrail is triggered example: https://your-server.com/guardrails-webhook required: - guardrail_name - guardrail_prompt responses: '200': description: Guardrails created successfully content: application/json: schema: type: object properties: guardrails_id: type: string description: Unique identifier for the created guardrails example: g12345 guardrails_name: type: string description: Name of the guardrails example: Healthcare Compliance Guardrails status: type: string description: Current status of the guardrails example: active created_at: type: string description: ISO 8601 timestamp of when the guardrails were created example: '2024-01-15T10:30:00Z' '400': description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: message: type: string description: Error message describing the validation failure example: guardrail_name is required '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 ```` --- # Source: https://docs.tavus.io/api-reference/objectives/create-objectives.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Create Objectives > This endpoint creates a new objective for a persona. Objectives provide goal-oriented instructions that help guide conversations toward specific achievements and desired outcomes. ## OpenAPI ````yaml post /v2/objectives openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/objectives: post: tags: - Objectives summary: Create Objectives description: > This endpoint creates a new objective for a persona. Objectives provide goal-oriented instructions that help guide conversations toward specific achievements and desired outcomes. operationId: createObjectives requestBody: content: application/json: schema: type: object properties: data: type: array description: Array of objectives to create items: type: object properties: objective_name: type: string description: >- A descriptive name for the objective. This must be a string value without spaces. example: ask_if_new_patient objective_prompt: type: string description: >- The detailed prompt that defines what the objective should accomplish. example: >- Ask the patient if they are new or have been here before confirmation_mode: type: string description: >- How the objective completion should be confirmed. If set to `manual`, the user will be prompted to confirm the objective completion. If set to `auto`, the LLM will determine whether the objective was completed or not. enum: - auto - manual default: auto example: auto output_variables: type: array description: >- Optional list of variables that should be extracted or collected during the objective. items: type: string example: - patient_status modality: type: string description: >- The communication modality for the objective. If set to `verbal`, the objective will be completed by the user's responses. If set to `visual`, the objective can only be completed by visual / perception cues observed by Raven. enum: - verbal - visual default: verbal example: verbal next_conditional_objectives: type: object description: >- A mapping of objective names to conditions that must be satisfied for that objective to be activated. additionalProperties: type: string example: new_patient_intake_process: If the patient has never been to the practice before existing_patient_intake_process: If the patient has been to the practice before next_required_objectives: type: array description: >- List of objective names that will be activated once the current objective is completed. items: type: string example: - get_patient_name callback_url: type: string description: >- Optional URL that will receive notifications when the objective is completed. example: https://your-server.com/webhook required: - objective_name - objective_prompt required: - data responses: '200': description: Objective created successfully content: application/json: schema: type: object properties: objectives_id: type: string description: Unique identifier for the created objective example: o12345 objective_name: type: string description: Name of the objective example: New Objectives status: type: string description: Current status of the objective example: active created_at: type: string description: ISO 8601 timestamp of when the objective was created example: '2024-01-15T10:30:00Z' '400': description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: message: type: string description: Error message describing the validation failure example: objective_name is required '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 ```` --- # Source: https://docs.tavus.io/api-reference/personas/create-persona.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. > 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) - Conversational Flow - Turn-taking, interruption handling, and active listening settings - LLM - Language model settings - TTS - Text-to-Speech settings # Create Persona For detailed guides on each layer of the Conversational Video Interface, click here. When using full pipeline mode, the `system_prompt` field is required. ## OpenAPI ````yaml post /v2/personas openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/personas: post: tags: - Personas summary: Create Persona description: > 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. When using full pipeline mode, the `system_prompt` field is required. #### 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-gpt-oss:** The **default** choice if no LLM layer is provided. [Get Started with Your Own LLM](/sections/conversational-video-interface/custom-llm-onboarding) #### 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** [Get Started with Your Own TTS](/sections/conversational-video-interface/custom-tts-onboarding) operationId: createPersona requestBody: content: application/json: schema: type: object properties: persona_name: type: string description: A name for the persona. example: Life Coach system_prompt: type: string description: >- This is the system prompt that will be used by the llm. **Each request must have a `system_prompt` value unless you're using echo mode**. example: >- As a Life Coach, you are a dedicated professional who specializes in... pipeline_mode: type: string description: >- The pipeline mode to use for the persona. Possible values: `full`, `echo`. `full` will provide the default end-to-end experience. `echo` will turn off most steps, and allow the replica to sync video with audio passed in through Echo events, which it will speak out. enum: - full - echo context: type: string description: This is the context that will be used by the llm. example: >- Here are a few times that you have helped an individual make a breakthrough in... default_replica_id: type: string description: >- The default replica_id associated with this persona if one exists. When creating a conversation, a persona_id with a default_replica_id associated can we used to create a conversation without specifying a replica_id. example: rfe12d8b9597 document_ids: type: array description: >- Array of document IDs that the persona will have access to. These documents will be available to the persona in all their conversations. The `document_ids` are returned in the response of the [Get Document](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints. items: type: string example: - d1234567890 - d2468101214 document_tags: type: array description: >- Array of document tags that the persona will have access to. Documents matching these tags will be available to the persona in all their conversations. The tags are passed in the `document_tags` parameter of the [Create Document](/api-reference/documents/create-document) endpoint. As soon as one document has the tag, you will be able to pass the tags in this parameter.. items: type: string example: - product_info - company_policies layers: type: object properties: perception: type: object properties: perception_model: type: string description: >- The perception model to use. Options include `raven-0` for advanced multimodal perception or `basic` for simpler vision capabilities, and `off` to disable all perception. enum: - raven-0 - basic - 'off' example: raven-0 ambient_awareness_queries: type: array description: >- Custom queries that Raven will continuously monitor for in the visual stream. These provide ambient context without requiring explicit prompting. items: type: string example: - Is the user showing an ID card? - Does the user appear distressed or uncomfortable? perception_tool_prompt: type: string description: >- A prompt that details how and when to use the tools that are passed to the perception layer. This helps the replica understand the context of the perception tools and grounds it. example: >- You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a form of ID is detected. perception_tools: type: array description: >- Tools that can be triggered based on visual context, enabling automated actions in response to visual cues. items: type: object properties: name: type: string description: The name of the tool to be called. description: type: string description: >- A description of what the tool does and when it should be called. example: - type: function function: name: notify_if_id_shown description: >- Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask() parameters: type: object properties: id_type: type: string description: best guess on what type of ID it is required: - id_type stt: type: object description: > **Note**: Turn-taking is now configured on the [Conversational Flow layer](/sections/conversational-video-interface/persona/conversational-flow). properties: hotwords: type: string description: > The hotwords parameter lets you provide example phrases that guide the STT model to prioritize certain words or phrases—especially names, technical terms, or uncommon language. For instance, including "Roey is the name of the person you're speaking with" helps the model transcribe "Roey" correctly instead of "Rowie." example: Roey is the name of the person you're speaking with. conversational_flow: type: object description: >- Controls conversational flow dynamics for the replica. When not explicitly provided, all fields default to None (turned off). If any parameter is provided, sensible defaults are applied to all other parameters. See more details [here](/sections/conversational-video-interface/persona/conversational-flow). properties: turn_detection_model: type: string description: >- The model used for turn detection. Options include `sparrow-1` (recommended) for advanced turn detection that is faster, more accurate, and more natural, `sparrow-0` (legacy) for standard turn detection, and `time-based` for simple timeout-based detection. Default is `sparrow-1` when any conversational flow parameter is provided. enum: - sparrow-1 - sparrow-0 - time-based example: sparrow-1 turn_taking_patience: type: string description: >- Controls how eagerly and quickly the replica claims conversational turns. Affects both response latency and likelihood of interrupting during natural pauses. `low` = eager and quick to respond, may interrupt pauses; `medium` (default) = balanced; `high` = patient, waits for clear turn completion. enum: - low - medium - high example: medium replica_interruptibility: type: string description: >- Controls how sensitive the replica is to user speech while the replica is talking. Determines whether the replica stops to listen or keeps speaking. `low` = keeps talking, less interruptible; `medium` (default) = balanced; `high` = stops easily, more interruptible. enum: - low - medium - high example: medium llm: type: object properties: model: type: string description: > "The model name that will be used by the LLM. To use Tavus' LLMs, you may select from the following models: - `tavus-gpt-oss` (Recommended) - `tavus-gpt-4o` - `tavus-gpt-4o-mini` If you would like to use your own OpenAI-compatible LLM, you may provide a `model`, `base_url`, and `api_key`." #### Context Window Limit * All Tavus-hosted models have a **limit of 32,000 tokens**. * Contexts over **25,000 tokens** will experience noticeable performance degradation (slower response times). > **Tip**: 1 token ≈ 4 characters, therefore 32,000 tokens ≈ 128,000 characters (including spaces and punctuation). base_url: type: string description: The base url for your OpenAI compatible endpoint. example: your-base-url api_key: type: string description: The API key for the OpenAI compatible endpoint. example: your-api-key speculative_inference: type: boolean description: >- When set to `true`, the LLM begins processing speech transcriptions before user input ends, improving responsiveness. example: true tools: type: array description: >- Optional tools to provide to your custom LLM - click [here](/sections/conversational-video-interface/persona/llm-tool) for more details. example: - type: function function: name: get_current_weather description: Get the current weather in a given location parameters: type: object properties: location: type: string description: >- The city and state, e.g. San Francisco, CA unit: type: string enum: - celsius - fahrenheit required: - location headers: type: object description: Optional headers to provide to your custom LLM example: Authorization: Bearer your-api-key extra_body: type: object description: > Optional parameters to customize the LLM request. For Tavus-hosted models, you can pass `temperature` and `top_p`: - `temperature`: Controls randomness in the model's output. Range typically 0.0 to 2.0. Lower values make output more deterministic and focused, higher values make it more creative and varied. - `top_p`: Controls diversity via nucleus sampling. Range 0.0 to 1.0. Lower values make output more focused on high-probability tokens, higher values allow more diverse token selection. For custom LLMs, you can pass any parameters that your LLM provider supports (e.g., `temperature`, `top_p`, `frequency_penalty`, etc.). example: temperature: 0.7 top_p: 0.9 tts: type: object properties: api_key: type: string description: >- The API key for the chosen TTS provider. Only required when using private voices. example: your-api-key tts_engine: type: string description: The TTS engine that will be used. enum: - cartesia - elevenlabs external_voice_id: type: string description: >- The voice ID used for the TTS engine when you want to customize your replica's voice. Choose from Cartesia's stock voices by referring to their [Voice Catalog](https://docs.cartesia.ai/api-reference/voices/list), or if you want more options you can consider [ElevenLabs](https://elevenlabs.io/docs/api-reference/voices/get-all). example: external-voice-id voice_settings: type: object description: > Optional voice settings to customize TTS behavior. Settings vary by provider. **Cartesia (Sonic-1 only):** - `speed`: Range -1.0 to 1.0 (negative = slower, positive = faster) - `emotion`: Array of emotion tags in format "emotion:level" (e.g., "positivity:high") - Emotions: anger, positivity, surprise, sadness, curiosity - Levels: low, medium, high - [Cartesia Documentation](https://docs.cartesia.ai/2024-11-13/build-with-cartesia/capability-guides/control-speed-and-emotion) **ElevenLabs:** - `speed`: Range 0.7 to 1.2 (0.7 = slowest, 1.2 = fastest) - `stability`: Range 0.0 to 1.0 (0.0 = variable, 1.0 = stable) - `similarity_boost`: Range 0.0 to 1.0 (0.0 = creative, 1.0 = original) - `style`: Range 0.0 to 1.0 (0.0 = neutral, 1.0 = exaggerated) - `use_speaker_boost`: Boolean (enhances speaker similarity) - [ElevenLabs Documentation](https://elevenlabs.io/docs/api-reference/voices/settings/get) example: speed: 0.5 emotion: - positivity:high - curiosity tts_emotion_control: type: boolean description: >- If true, the TTS engine will be able to control the emotion of the voice. Only available for Cartesia TTS. example: 'false' tts_model_name: type: string description: >- The model name that will be used by the TTS engine. Please double check this with the TTS provider you are using to ensure valid model names. example: sonic examples: Required Parameters Only: value: pipeline_mode: full system_prompt: >- As a Life Coach, you are a dedicated professional who specializes in... Full Customizations: value: persona_name: Life Coach system_prompt: >- As a Life Coach, you are a dedicated professional who specializes in... pipeline_mode: full context: >- Here are a few times that you have helped an individual make a breakthrough in... default_replica_id: rfe12d8b9597 layers: llm: model: tavus-gpt-4o speculative_inference: true tools: - type: function function: name: life_coach_insight description: >- Offer personalized life coaching advice or guidance based on a user's challenge or goal. parameters: type: object properties: topic: type: string description: >- The area of life or goal the user wants to improve (e.g. career, relationships, confidence) urgency_level: type: string enum: - low - medium - high required: - topic tts: tts_engine: cartesia voice_settings: speed: normal emotion: - positivity:high - curiosity tts_emotion_control: true tts_model_name: sonic perception: perception_model: raven-0 ambient_awareness_queries: - Is the user showing an ID card? - Does the user appear distressed or uncomfortable? perception_tool_prompt: >- You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a form of ID is detected. perception_tools: - type: function function: name: notify_if_id_shown description: >- Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask() parameters: type: object properties: id_type: type: string description: best guess on what type of ID it is required: - id_type stt: stt_engine: tavus-advanced conversational_flow: turn_detection_model: sparrow-1 turn_taking_patience: medium turn_commitment: medium replica_interruptibility: high active_listening: low document_ids: - d1234567890 - d2468101214 document_tags: - product_info - company_policies responses: '200': description: '' content: application/json: schema: type: object properties: persona_id: type: string description: A unique identifier for the persona. example: p5317866 persona_name: type: string description: The name of the persona. example: Life Coach created_at: type: string description: The date and time the persona was created. '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid replica_uuid '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 ```` --- # Source: https://docs.tavus.io/api-reference/phoenix-replica-model/create-replica.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. > 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. # Create Replica By default, all new replicas are trained using the `phoenix-3` model.\ To use the older `phoenix-2` model, set the `model_name` parameter to `phoenix-2`. Required parameters vary based on the replica type: **Personal Replica:** * `train_video_url` * `consent_video_url` **Non-Human Replica:** * `train_video_url` Make sure the `train_video_url` and `consent_video_url` are publicly accessible download links, such as presigned S3 URLs. ## OpenAPI ````yaml post /v2/replicas openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/replicas: post: tags: - Replicas summary: Create Replica description: > This endpoint creates a new Replica that can be used in a conversation. By default, all new replicas will be trained using the `phoenix-3` model. You can optionally create phoenix-2 replicas by setting the `model_name` parameter to `phoenix-2`. 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). operationId: createReplica requestBody: content: application/json: schema: type: object properties: consent_video_url: type: string description: >- A direct link to a video that contains the consent statement. You may optionally send the consent statement in a separate video from your training video. If you do not provide a consent video, the consent statement must be present at the beginning of the training video. **This value is required if you want to create a personal replica**. example: >- https://my-example-bucket.s3.us-east-1.amazonaws.com/your-consent-video.mp4 train_video_url: type: string description: >- A direct link to a publicly accessible storage location such as an S3 bucket. This video will be used for replica training. example: >- https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4 callback_url: type: string description: >- A url that will receive a callback on completion of replica training or on error. example: https://yourwebsite.com/webhook replica_name: type: string description: A name for the replica. example: Rio model_name: type: string description: >- The phoenix model version that will be used to train the replica. The current default is `phoenix-3`. example: phoenix-3 properties: type: object properties: gaze_correction: type: boolean description: >- If set to true, the replica will have gaze correction enabled. example: false background_green_screen: type: boolean description: >- If set to true, the replica will have a green screen background. example: false required: - train_video_url examples: Personal Replica: value: callback_url: https://yourwebsite.com/webhook replica_name: Rio train_video_url: >- https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4 consent_video_url: >- https://my-example-bucket.s3.us-east-1.amazonaws.com/your-consent-video.mp4 Non-Human Replica: value: callback_url: https://yourwebsite.com/webhook replica_name: AI train_video_url: >- https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4 Older Model Replica: value: model_name: phoenix-2 callback_url: https://yourwebsite.com/webhook replica_name: rfe12d8b9597 train_video_url: >- https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4 consent_video_url: >- https://my-example-bucket.s3.us-east-1.amazonaws.com/your-consent-video.mp4 responses: '200': description: '' content: application/json: schema: type: object properties: replica_id: type: string example: r783537ef5 description: A unique identifier for the replica. status: type: string example: started description: >- The status of the replica. Possible values: `started`, `completed`, `error`. '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid train_video_url '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 ```` --- # Source: https://docs.tavus.io/api-reference/video-request/create-video.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Generate Video > 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). ## OpenAPI ````yaml post /v2/videos openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/videos: post: tags: - Videos summary: Generate Video description: > 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). operationId: generateVideo requestBody: 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: r783537ef5 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. 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`. 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. 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: type: string description: > 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: 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: r665388ec672 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: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/sections/conversational-video-interface/conversation/usecases/customer-service.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Customer Service Agent > Engage in real-time customer support conversations that adapt to user emotions and behavior. ## Customer Service Agent Configuration ```json [expandable] theme={null} { "persona_name": "Customer Service Agent", "pipeline_mode": "full", "system_prompt": "You are a calm, helpful customer service agent. You assist users with product or service issues, and adapt based on their emotional state. Remain professional and empathetic at all times.", "context": "User needs support with a product or service. Listen carefully, identify the issue, and offer a helpful resolution. Monitor body language and voice tone to adapt your responses when the user appears frustrated or confused.", "default_replica_id":"r95fd27b5a37", "layers": { "tts": { "tts_engine": "cartesia", "tts_emotion_control": true }, "llm": { "tools": [ { "type": "function", "function": { "name": "resolve_customer_issue", "parameters": { "type": "object", "required": ["product", "issue_description", "urgency"], "properties": { "product": { "type": "string", "description": "The product or service the user is having trouble with" }, "issue_description": { "type": "string", "description": "The specific problem or complaint reported by the user" }, "urgency": { "type": "string", "enum": ["low", "medium", "high"], "description": "How urgent or critical the issue is for the user" } } }, "description": "Attempt to resolve the user's issue by logging the product, issue, and urgency for appropriate follow-up or resolution." } } ], "model": "tavus-gpt-oss", "speculative_inference": true }, "perception": { "perception_model": "raven-0", "ambient_awareness_queries": [ "Does the user appear frustrated or confused?", "Is the user sighing, fidgeting, or visibly anxious?", "Is the user's posture disengaged or tense?", "Is the user calm and cooperative?" ], "perception_tool_prompt": "Use the `user_emotional_state` tool when body language or facial expressions indicate a strong emotional state such as frustration, confusion, or calmness.", "perception_tools": [ { "type": "function", "function": { "name": "user_emotional_state", "description": "Use this function to report the user's emotional state as inferred from body language and voice tone.", "parameters": { "type": "object", "required": ["emotional_state", "indicator"], "properties": { "emotional_state": { "type": "string", "description": "Inferred emotion from the user's body language (e.g., frustrated, calm, confused)" }, "indicator": { "type": "string", "description": "The visual behavior that triggered the inference (e.g., furrowed brow, fidgeting, sighing)" } } } } } ] }, "conversational_flow": { "turn_detection_model": "sparrow-1", "turn_taking_patience": "low", "replica_interruptibility": "medium" } } } ``` This predefined persona is configured to provide personalized history lessons. It includes: * **Persona Identity**: A professional customer service agent that helps users with real product or service issues. The agent speaks clearly and responds with empathy, adjusting based on how the user sounds or looks. - **Full Pipeline Mode**: Enables the full Tavus conversational pipeline, including Perception, STT, LLM, and TTS. * **System Prompt**: Tells the agent to act professionally and respond helpfully, while being aware of the user’s emotional state. * **Context**: Describes a real customer support situation. The agent listens to the user’s issue, helps resolve it, and changes its tone or pace if the user seems frustrated or confused. * **Persona Layer**: * **LLM Layer**: Uses the `resolve_customer_issue` tool to gather: * `product`: what the issue is about * `issue_description`: a short explanation of the problem * `urgency`: how serious the issue is (`low`, `medium`, or `high`) * **Perception Layer**: Uses the `raven-0` model to watch for signs like fidgeting, slouching, or facial expressions. If the user appears upset, it calls the `user_emotional_state` tool with: * `emotional_state`: what the user seems to feel (e.g., frustrated, calm) * `indicator`: what was observed (e.g., sighing, avoiding eye contact) * **TTS Layer**: Employs the `cartesia` voice engine with emotion control. * **Conversational Flow Layer**: Uses `sparrow-1` turn detection model with low turn-taking patience for fast responses and medium replica interruptibility for balanced conversation flow. ## Create a Conversation with the Customer Service Agent Persona Create AI Interviewer persona using the following request: ```sh cURL [expandable] theme={null} curl --request POST \ --url https://tavusapi.com/v2/personas \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_name": "Customer Service Agent", "pipeline_mode": "full", "system_prompt": "You are a calm, helpful customer service agent. You assist users with product or service issues, and adapt based on their emotional state. Remain professional and empathetic at all times.", "context": "User needs support with a product or service. Listen carefully, identify the issue, and offer a helpful resolution. Monitor body language and voice tone to adapt your responses when the user appears frustrated or confused.", "default_replica_id": "r95fd27b5a37", "layers": { "tts": { "tts_engine": "cartesia", "tts_emotion_control": true }, "llm": { "tools": [ { "type": "function", "function": { "name": "resolve_customer_issue", "description": "Attempt to resolve the user'\''s issue by logging the product, issue, and urgency for appropriate follow-up or resolution.", "parameters": { "type": "object", "required": ["product", "issue_description", "urgency"], "properties": { "product": { "type": "string", "description": "The product or service the user is having trouble with" }, "issue_description": { "type": "string", "description": "The specific problem or complaint reported by the user" }, "urgency": { "type": "string", "enum": ["low", "medium", "high"], "description": "How urgent or critical the issue is for the user" } } } } } ], "model": "tavus-gpt-oss", "speculative_inference": true }, "perception": { "perception_model": "raven-0", "ambient_awareness_queries": [ "Does the user appear frustrated or confused?", "Is the user sighing, fidgeting, or visibly anxious?", "Is the user's posture disengaged or tense?", "Is the user calm and cooperative?" ], "perception_tool_prompt": "Use the `user_emotional_state` tool when body language or facial expressions indicate a strong emotional state such as frustration, confusion, or calmness.", "perception_tools": [ { "type": "function", "function": { "name": "user_emotional_state", "description": "Use this function to report the user's emotional state as inferred from body language and voice tone.", "parameters": { "type": "object", "required": ["emotional_state", "indicator"], "properties": { "emotional_state": { "type": "string", "description": "Inferred emotion from the user's body language (e.g., frustrated, calm, confused)" }, "indicator": { "type": "string", "description": "The visual behavior that triggered the inference (e.g., furrowed brow, fidgeting, sighing)" } } } } } ] }, "conversational_flow": { "turn_detection_model": "sparrow-1", "turn_taking_patience": "low", "replica_interruptibility": "medium" } } }' ``` Replace `` with your actual API key. You can generate one in the Developer Portal. Use the following request body example: ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "" }' ``` * Replace `` with your actual API key. * Replace `` with the ID of the persona you created using the Customer Service Agent configuration. Click the link in the ***`conversation_url`*** field to join the conversation: ```json theme={null} { "conversation_id": "c7f3fc6d766f", "conversation_name": "New Conversation 1747719531479", "conversation_url": "", "status": "active", "callback_url": "", "created_at": "2025-05-20T05:38:51.501467Z" } ``` --- # Source: https://docs.tavus.io/api-reference/conversations/delete-conversation.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Delete Conversation > This endpoint deletes a single conversation by its unique identifier. ## OpenAPI ````yaml delete /v2/conversations/{conversation_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/conversations/{conversation_id}: parameters: - name: conversation_id in: path required: true description: The unique identifier of the conversation. schema: type: string example: c123456 delete: tags: - Conversations summary: Delete Conversation description: | This endpoint deletes a single conversation by its unique identifier. operationId: deleteConversation parameters: - name: hard in: query schema: type: boolean example: true description: >- If set to true, the conversation and associated assets will be hard deleted. CAUTION: This action is irrevocable. responses: '204': description: NO CONTENT '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid conversation_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 ```` --- # Source: https://docs.tavus.io/api-reference/documents/delete-document.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Delete Document > Delete a specific document Delete a document and its associated data using its unique identifier. ## OpenAPI ````yaml delete /v2/documents/{document_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/documents/{document_id}: delete: tags: - Documents summary: Delete Document description: | Delete a document and its associated data using its unique identifier. operationId: deleteDocument parameters: - in: path name: document_id required: true schema: type: string description: The unique identifier of the document to delete responses: '204': description: NO CONTENT - Document deleted successfully '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: The error message example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: The error message example: Document not found security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/guardrails/delete-guardrails.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Delete Guardrails > This endpoint deletes a single set of guardrails by its unique identifier. ## OpenAPI ````yaml delete /v2/guardrails/{guardrails_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/guardrails/{guardrails_id}: parameters: - name: guardrails_id in: path required: true description: The unique identifier of the guardrails. schema: type: string example: g12345 delete: tags: - Guardrails summary: Delete Guardrails description: > This endpoint deletes a single set of guardrails by its unique identifier. operationId: deleteGuardrails responses: '204': description: NO CONTENT - Guardrails deleted successfully '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid guardrails_id '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: error: type: string description: The error message. example: Guardrails not found security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/objectives/delete-objectives.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Delete Objective > This endpoint deletes a single objective by its unique identifier. ## OpenAPI ````yaml delete /v2/objectives/{objectives_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/objectives/{objectives_id}: parameters: - name: objectives_id in: path required: true description: The unique identifier of the objective. schema: type: string example: o12345 delete: tags: - Objectives summary: Delete Objective description: | This endpoint deletes a single objective by its unique identifier. operationId: deleteObjective responses: '204': description: NO CONTENT - Objective deleted successfully '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid objectives_id '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: error: type: string description: The error message. example: Objective not found security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/personas/delete-persona.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Delete Persona > This endpoint deletes a single persona by its unique identifier. ## OpenAPI ````yaml delete /v2/personas/{persona_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/personas/{persona_id}: parameters: - name: persona_id in: path required: true description: The unique identifier of the persona. schema: type: string example: pf3073f2dcc1 delete: tags: - Personas summary: Delete Persona description: | This endpoint deletes a single persona by its unique identifier. operationId: deletePersona parameters: - name: persona_id in: path required: true description: The unique identifier of the persona. schema: type: string example: pf3073f2dcc1 responses: '204': description: NO CONTENT '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid persona_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 ```` --- # Source: https://docs.tavus.io/api-reference/phoenix-replica-model/delete-replica.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Delete Replica > This endpoint deletes a Replica by its unique ID. Deleted Replicas cannot be used in a conversation. ## OpenAPI ````yaml delete /v2/replicas/{replica_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/replicas/{replica_id}: delete: tags: - Replicas summary: Delete Replica description: > This endpoint deletes a Replica by its unique ID. Deleted Replicas cannot be used in a conversation. operationId: deleteReplica parameters: - name: replica_id in: path required: true description: The unique identifier of the persona. schema: type: string example: rf3073f2dcc1 - name: hard in: query schema: type: boolean example: false description: >- If set to true, the replica and associated assets (such as training footage) will be hard deleted. CAUTION: This action is irrevocable. Note that a hard delete of a replica does *not* delete the conversation created using said replica. See [Delete Video](https://docs.tavus.io/api-reference/video-request/delete-video) for more info. responses: '200': description: OK '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: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/video-request/delete-video.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Delete Video > This endpoint deletes a single video by its unique identifier. ## OpenAPI ````yaml delete /v2/videos/{video_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/videos/{video_id}: 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: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/sections/integrations/embedding-cvi.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Embed Conversational Video Interface > Learn how to embed Tavus's Conversational Video Interface (CVI) into your site or app. ## Overview Tavus CVI delivers AI-powered video conversations directly in your application. You can integrate it using: | Method | Best For | Complexity | Customization | | --------------------- | ---------------------------------- | ---------- | ------------- | | **@tavus/cvi-ui** | React apps, advanced features | Low | High | | **iframe** | Static websites, quick demos | Low | Low | | **Vanilla JS** | Basic dynamic behavior | Low | Medium | | **Node.js + Express** | Backend apps, dynamic embedding | Medium | High | | **Daily SDK** | Full UI control, advanced features | High | Very High | ## Implementation Steps This method provides a full-featured React component library. It offers pre-built, customizable components and hooks for embedding Tavus CVI in your app. ## Overview The Tavus Conversational Video Interface (CVI) React component library provides a complete set of pre-built components and hooks for integrating AI-powered video conversations into your React applications. This library simplifies setting up Tavus in your codebase, allowing you to focus on your application's core features. Key features include: * **Pre-built video chat components** * **Device management** (camera, microphone, screen sharing) * **Real-time audio/video processing** * **Customizable styling** and theming * **TypeScript support** with full type definitions *** ## Quick Start ### Prerequisites Before getting started, ensure you have a React project set up. Alternatively, you can start from our example project: [CVI UI Haircheck Conversation Example](https://github.com/Tavus-Engineering/tavus-examples/tree/main/examples/cvi-ui-haircheck-conversation) - this example already has the HairCheck and Conversation blocks set up. ### 1. Initialize CVI in Your Project ```bash theme={null} npx @tavus/cvi-ui@latest init ``` * Creates a `cvi-components.json` config file * Prompts for TypeScript preference * Installs npm dependencies (@daily-co/daily-react, @daily-co/daily-js, jotai) ### 2. Add CVI Components ```bash theme={null} npx @tavus/cvi-ui@latest add conversation ``` ### 3. Wrap Your App with the CVI Provider In your root directory (main.tsx or index.tsx): ```tsx theme={null} import { CVIProvider } from './components/cvi/components/cvi-provider'; function App() { return {/* Your app content */}; } ``` ### 4. Add a Conversation Component Learn how to create a conversation URL at [https://docs.tavus.io/api-reference/conversations/create-conversation](https://docs.tavus.io/api-reference/conversations/create-conversation). **Note:** The Conversation component requires a parent container with defined dimensions to display properly. Ensure your body element has full dimensions (`width: 100%` and `height: 100%`) in your CSS for proper component display. ```tsx theme={null} import { Conversation } from './components/cvi/components/conversation'; function CVI() { const handleLeave = () => { // handle leave }; return (
); } ``` *** ## Documentation Sections * **[Overview](/sections/conversational-video-interface/component-library/overview)** – Overview of the CVI component library * **[Blocks](/sections/conversational-video-interface/component-library/blocks)** – High-level component compositions and layouts * **[Components](/sections/conversational-video-interface/component-library/components)** – Individual UI components * **[Hooks](/sections/conversational-video-interface/component-library/hooks)** – Custom React hooks for managing video call state and interactions This is the simplest approach requiring no coding. It leverages Tavus’s prebuilt interface with limited customization options. 1. Create a conversation using the Tavus API. 2. Replace `YOUR_TAVUS_MEETING_URL` below with your actual conversation URL: ```html theme={null} Tavus CVI ``` This method provides basic customizations and dynamic room management for apps without framework. 1. Add the following script tag to your HTML ``: ```html theme={null} ``` 2. Use the following script, replacing `'YOUR_TAVUS_MEETING_URL'` with your actual conversation URL: ```html theme={null}
``` This method serves dynamic pages that embed Tavus CVI within Daily rooms. 1. Install Express: ```bash theme={null} npm install express ``` 2. Create `server.js` and implement the following Express server: ```js theme={null} const express = require('express'); const app = express(); const PORT = 3000; app.get('/room', (req, res) => { const meetingUrl = req.query.url || 'YOUR_TAVUS_MEETING_URL'; res.send(`
`); }); app.listen(PORT, () => console.log(`Server running on http://localhost:${PORT}`)); ``` 3. Run the server: ```bash theme={null} node server.js ``` 4. Visit: `http://localhost:3000/room?url=YOUR_TAVUS_MEETING_URL` ### Notes * Supports dynamic URLs. * Can be extended with authentication and other logic using Tavus's API. This method offers complete control over the user experience and allows you to build a fully custom interface for Tavus CVI. 1. Install SDK: ```bash theme={null} npm install @daily-co/daily-js ``` 2. Use the following script to join the Tavus CVI meeting: ```js [expandable] theme={null} import React, { useEffect, useRef, useState } from 'react'; import DailyIframe from '@daily-co/daily-js'; const getOrCreateCallObject = () => { // Use a property on window to store the singleton if (!window._dailyCallObject) { window._dailyCallObject = DailyIframe.createCallObject(); } return window._dailyCallObject; }; const App = () => { const callRef = useRef(null); const [remoteParticipants, setRemoteParticipants] = useState({}); useEffect(() => { // Only create or get one call object per page const call = getOrCreateCallObject(); callRef.current = call; // Join meeting call.join({ url: "YOUR_TAVUS_MEETING_URL" }); // Handle remote participants const updateRemoteParticipants = () => { const participants = call.participants(); const remotes = {}; Object.entries(participants).forEach(([id, p]) => { if (id !== 'local') remotes[id] = p; }); setRemoteParticipants(remotes); }; call.on('participant-joined', updateRemoteParticipants); call.on('participant-updated', updateRemoteParticipants); call.on('participant-left', updateRemoteParticipants); // Cleanup return () => { call.leave(); }; }, []); // Attach remote video and audio tracks useEffect(() => { Object.entries(remoteParticipants).forEach(([id, p]) => { // Video const videoEl = document.getElementById(`remote-video-${id}`); if (videoEl && p.tracks.video && p.tracks.video.state === 'playable' && p.tracks.video.persistentTrack ) { videoEl.srcObject = new MediaStream([p.tracks.video.persistentTrack]); } // Audio const audioEl = document.getElementById(`remote-audio-${id}`); if ( audioEl && p.tracks.audio && p.tracks.audio.state === 'playable' && p.tracks.audio.persistentTrack ) { audioEl.srcObject = new MediaStream([p.tracks.audio.persistentTrack]); } }); }, [remoteParticipants]); // Custom UI return (
Meeting Room (daily-js custom UI)
{Object.entries(remoteParticipants).map(([id, p]) => (
))}
); }; export default App; ``` 3. Customize the conversation UI in the script above (Optional). See the Daily JS SDK for details. ## FAQs Daily provides built-in noise cancellation which can be enabled via their updateInputSettings() method. ```js theme={null} callFrame.updateInputSettings({ audio: { processor: { type: 'noise-cancellation', }, }, }); ``` Yes, you can attach Daily event listeners to monitor and respond to events like participants joining, leaving, or starting screen share. --- # Source: https://docs.tavus.io/api-reference/conversations/end-conversation.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # End Conversation > This endpoint ends a single conversation by its unique identifier. ## OpenAPI ````yaml post /v2/conversations/{conversation_id}/end openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/conversations/{conversation_id}/end: parameters: - name: conversation_id in: path required: true description: The unique identifier of the conversation. schema: type: string example: c123456 post: tags: - Conversations summary: End Conversation description: | This endpoint ends a single conversation by its unique identifier. operationId: endConversation responses: '200': description: OK '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid conversation_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 ```` --- # Source: https://docs.tavus.io/sections/errors-and-status-details.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Errors and Status Details > Identify errors and status details encountered when using the Tavus platform. ## Replica Training Errors | Error Type | Error Message | Additional Information | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | download\_link | There was an issue downloading your video file. Please ensure that the link you provided is correct and try again | Tavus was not able to download the video from the provided link. Please ensure the link you provide is a hosted url download link | | file\_size | The video file you provided exceeds the maximum file size allowed. Please ensure that the video is less than 750MB and try again. | All video files must be smaller than 750mb | | video\_format | There was an issue processing your training video. The video provided is not a .mp4 file. Please ensure that the training video is a .mp4 file encoded using h.264 | All Replica training and consent video files must be .mp4 | | video\_codec | There was an issue processing your training video. The video provided is not encoded using h.264. Please ensure that the training video is a .mp4 file encoded using h.264 | All Replica training and consent video files must be encoded using h.264 | | video\_codec\_and\_format | There was an issue processing your training video. Please ensure that the training video is a .mp4 file encoded using h.264 | All Replica training and consent video files must be .mp4 and encoded using h.264 | | video\_duration | There was an issue processing your training video. The video provided does not meet the minimum duration requirement for training | All Replica training files must be at least 1 minute long. (Between 1.5 to 2 minutes is optimal.) | | video\_fps | There was an issue processing your training video. The video provided does not meet the minimum frame rate requirement for a training video. Please ensure your training video has a frame rate of at least 25fps | All Replica training and consent video files must have a frame rate of at least 25fps | | consent\_phrase\_mismatch | There was an issue processing your training file: Your consent phrase does not match our requirements. Please follow our specified format closely | There was an issue with the consent phrase provided. Please review our consent guidelines and resubmit a new training with the correct consent statement | | face\_or\_obstruction\_detected | There was an issue processing your training file: More than one face detected or obstructions present. Please ensure only your face is visible and clear | Your face must be present in all frames of the video and may not be obstructed at anytime | | lighting\_change\_detected | There was an issue processing your training file: Lighting changes detected. Ensure your face is evenly lit throughout the video | Please ensure that the lighting of your face is consistent throughout the entire video | | background\_noise\_detected | There was an issue processing your training file: Background noise or other voices detected. Please record in a quiet environment with only your voice | The video must be recorded in a quiet environment with only your voice present | | video\_editing\_detected | There was an issue processing your training file: Video appears edited or contains cuts. Please submit an unedited, continuous video | The video must be unedited and recorded in one take | | community\_guidelines\_violation | There was an issue processing your training file: Video violates Community Guidelines. Please review our guidelines and resubmit your video | Please ensure that your training video does not violate our community guidelines | | video\_processing | There was an error processing your training video. Face not detected because it appeared too small in the frame or it was occluded. Please edit or record a new video and ensure your face is clearly visible and occupies a larger portion of the frame. | This error occurs when the face appears too small relative to the background or if a full body video is recorded in horizontal format instead of vertical. Please ensure your face is clearly visible and occupies a larger portion of the frame. | | video\_processing | There was an error processing your training video file. Please check your video format and make sure it not damaged and could be played correctly. | This error indicates there may be an issue with the video file format or the file may be corrupted. Please verify the video can be played correctly and resubmit. | | excessive\_movement\_detected | There was an issue processing your training file: Excessive movement detected. Please ensure you are sitting still and centered in the frame | This error indicates that the model is having difficulty tracking the face from frame to frame. Could be related to movement of the subject or the camera. In some cases, it may also be related to obstructions such as superimposed graphics. | | audio\_processing | There was an error processing the audio in the provided training video file. | This error indicates that the audio processing step was interrupted. In edge cases, may be related to the replica name's length or characters. | | quality\_issue\_detected | Quality issue detected. For details and assistance, please reach out to Tavus support via [developer-support@tavus.io](mailto:developer-support@tavus.io) | This error indicates a quality problem with the input video that has resulted in poor test output. One example cause could be input video quality under 720p. Please review the quality checklist to make sure you have met all requirements and/or reach out to [support@tavus.io](mailto:support@tavus.io) for assistance. | | hands\_obstructing\_face | There was a quality issue with your replica. The user's hand obstructed the face during recording. Please edit your video or record a new training video and keep hands away from the face. | Please ensure that the user's face is visible throughout the entire video. | | second\_person\_detected | There was a quality issue with your replica. A second person or face was detected in the frame. Please edit your video or record a new video with no one else in the background. | Please ensure that there is only a single user in the training video. | | improper\_distance | There was a quality issue with your replica. The user was either too close to or too far from the camera. Please review our documentation on proper framing and distance before editing your video or recording a new video. | Please ensure the user is centered in the training video. | | inconsistent\_distance | There was a quality issue with your replica. The user's distance from the camera changed during the recording. Please edit or record a new training video and remain at a consistent distance from the camera for the entire video. | Please ensure the user stays in the same spot throughout the training video. | | face\_turned\_away | There was a quality issue with your replica. User's face turned away from the camera. Please edit or record a new video and ensure you are facing directly toward the camera for the entire duration. | The face should be centered on the camera the entire duration of the training video. | | improper\_camera\_angle | There was a quality issue with your replica. The camera angle was either too low or too high. Please record a new video with the camera angle at eye level. | Please ensure the camera is at eye level. | | poor\_lighting | There was a quality issue with your replica. The user's face was not clearly visible due to poor lighting or heavy shadows. Please edit or record a new video with even lighting on your face, avoiding shadows or dim environments. | Shadows and uneven lighting cause distortions during replica training. Please ensure the lighting is as even as possible. | | teeth\_not\_visible | There was a quality issue with your replica. The top and bottom teeth were not clearly visible during recording, either due to poor lighting or obstruction. Please edit your video or record a new training video with better lighting and ensure your teeth are fully visible. | A large smile at the beginning helps the training process capture your natural teeth. | | other\_quality\_issue | Quality issue was detected. For details and assistance, please reach out to Tavus support via [support@tavus.io](mailto:support@tavus.io) | Please reach out to support to better understand issues that occur during the training process. | ## Video Errors | Error Type | Error Message | Additional Information | | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | | video\_error | An error occurred while generating this request. Please check your inputs or try your request again | Tavus ran into an issue generating the video. Please ensure that the your inputs are valid and try again. If this issue PermissionStatus, please reach out to support for assistance | | | replica\_in\_error\_state | Request Failed: The replica {} is currently in an 'error' state and cannot process requests. For details on the cause of the error and how to resolve it, please review the specific information provided for this replica. | Please ensure that the Replica being used to generate videos is in a 'ready' state | | | audio\_file\_max\_size | There was an issue generating your video. The audio file exceeds the maximum file size of 750MB. | The audio file provided is too large. Please ensure that the audio file is less than 750MB and try again. | | | audio\_file\_type | There was an issue generating your video. The audio file provided is not a .wav | Currently, we only support .wav audio files for generating videos. Please ensure that the audio file is a .wav file and try again. | | | audio\_file\_min\_duration | There was an issue generating your video. The duration of the audio file does not reach the minimum duration requirement of 3 seconds. | The audio file provided is too short. | | | audio\_file\_max\_duration | There was an issue generating your video. The duration of the audio file exceeds the maximum duration of 10 minutes. | The audio file is too long. | | | audio\_file\_ download\_link | There was an issue generating your video. We were unable to download your audio file. Please ensure that the link you provided is correct and try again. | Please ensure that the link you provide is a hosted url download link that is publicly accessible. | | | script\_community\_guidelines | Request has failed as the script violates community guidelines. | Please ensure that the script's contents do not violate our community guidelines. | | ## Video Status Details | Status Type | Status Details | Additional Information | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | video\_success | Your request has processed successfully! | The video has been generated successfully and is ready for use | | video\_queued | This request is currently queued. It should begin processing in a few minutes. | Immediately upon submitting a request for video generation, the video will be added to a queue to be processed | | replica\_in\_training | The training process for replica {} is still ongoing. Your request has been placed in the 'queued' status and will automatically proceed to the generation phase once training is complete. To monitor the current progress of the training, please review the detailed status of this replica. | Videos will not start generating until the Replica being used has finished training | --- # Source: https://docs.tavus.io/sections/conversational-video-interface/faq.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # FAQs > Frequently asked questions about Tavus's Conversational Video Interface. Memories allow AI Personas to remember context across turns and understand time and dates, making conversations more coherent over longer interactions. Memories are enabled using a unique memory\_stores that acts as the memory key. Information collected during conversations is associated with this participant and can be referenced in future interactions. Yes. Cross-conversation Memories are supported as part of this update. It improves context retention, which is crucial for multi-turn tasks and long-term relationships between users and AI. It unlocks uses cases that progress over time like education or therapy, out of the box. To enable Memories in the UI, you can either select an existing memory tag from the dropdown menu or type a new one to create it. Use the `memory_stores` field in the Create Conversation API call. This should be a stable, unique identifier for the user (e.g. user email, CRM ID, etc.). Example: ```json theme={null} { "replica_id": "rb17cf590e15", "conversation_name": "Follow-up Chat", "memory_stores": ["user_123"] } ``` Full example here: [Memories API Docs](/api-reference/conversations/create-conversation) Not yet. Editing and reviewing Memories is not supported in this early release. Retrieval endpoints are under development and will be available in a future update. No. Memories are optional. If you don't include a memory\_stores, the AI Persona will behave statelessly—like a standard LLM—with no memory across sessions. No. Memories are tied to unique memory\_stores. Sharing this ID across users would cause memory crossover. Each participant should have their own ID to keep Memories clean and accurate. They can keep using their systems or integrate with Tavus Memories for more coherent, accurate conversations. Our memory is purpose-built for conversational video, retaining context across sessions with flexible scoping for truly personalized interactions. Today, we don't yet offer full visibility into what's stored in memory or how it was used in a given response. Memories are designed to persist indefinitely between interactions, allowing your AI persona to retain long-term context. Head to the [Memories Documentation site](https://docs.tavus.io/sections/conversational-video-interface/memories#api-setup). Knowledge Base is where users upload documents to enhance their AI persona capabilities using RAG (Retrieval-Augmented Generation). By retrieving information directly from these documents, AI personas can deliver more accurate, relevant, and grounded responses. Using RAG, the Knowledge Base system continuously: * Analyzes the conversation context * Retrieves relevant information from your document base * Augments the AI's responses with this contextual knowledge from your documents With our industry-leading RAG, responses arrive in just 30 ms, up to 15× faster than other solutions. Conversations feel instant, natural, and friction-free. Yes, users can keep using their systems, but we strongly recommend they integrate with the Tavus Knowledge Base. Our Knowledge Base isn't just faster: it's the fastest RAG on the market, delivering answers in just 30 ms. That speed means conversations flow instantly, without awkward pauses or lagging. These interactions feel natural in a way user-built systems can't match. An AI recruiter can reference a candidate's resume uploaded via PDF and provide more accurate responses to applicant questions, using the resume content as grounding. By having a Knowledge Base, AI personas can respond with facts, unlocking domain-specific intelligence: * Faster onboarding (just upload the docs) * More trustworthy answers, especially in regulated or high-stakes environments * Higher task completion for users, thanks to grounded knowledge Supported file types (uploaded to a publicly accessible URL like S3): * CSV * PDF * TXT * PPTX * PNG * JPG * You can also enter any site URL and the Tavus API will scrape the site's contents and reformat the content as a machine readable document. Head to the [Knowledge Base Documentation site](https://docs.tavus.io/sections/conversational-video-interface/knowledge-base). Yes. Documents are linked to the API key that was used to upload them. To access a document later, you must use the same API key that was used to create it. Once your documents have been uploaded and processed, include their IDs in your conversation request. Here's how: ```bash theme={null} curl --location 'https://tavusapi.com/v2/conversations/' \ --header 'Content-Type: application/json' \ --header 'x-api-key: '' \ --data '{ "persona_id": "", "replica_id": "", "document_ids": ["Document ID"] }' ``` Note: You can include multiple document\_ids, and your AI persona will dynamically reference those documents during the conversation. You can also attach a document to a Persona. Upload files by providing a downloadable URL using the Create Documents endpoint. Tags are also supported for organization. This request returns a document\_id, which you'll later use in conversation calls: ```bash theme={null} curl --location 'https://tavusapi.com/v2/documents/' \ --header 'Content-Type: application/json' \ --header 'x-api-key: '' \ --data '{ "document_url": "", "document_name": "slides_new.pdf", "tags": ["", ""] }' ``` * `file_size_too_large` – File exceeds the maximum allowed upload size. * `file_format_unsupported` – This file type isn't supported for upload. * `invalid_file_url` – Provided file link is invalid or inaccessible. * `file_empty` – The uploaded file contains no readable content. * `website_processing_failed` – Website content could not be retrieved or processed. * `chunking_failed` – System couldn't split file into processable parts. * `embedding_failed` – Failed to generate embeddings for your file content. * `vector_store_failed` – Couldn't save data to the vector storage system. * `s3_storage_failed` – Error storing file in S3 cloud storage. * `contact_support` – An error occurred; please reach out for help. Conversation.rag.observability tool call will be sent, which will fire if the conversational LLM decides to use any of the document chunks in its response, returning the document IDs and document names of the chunks When creating a conversation with documents, you can optimize how the system searches through your knowledge base by specifying a retrieval strategy. This strategy determines the balance between search speed and the quality of retrieved information, allowing you to fine-tune the system based on your specific needs. You can choose from three different strategies: * **Speed**: Optimizes for faster retrieval times for minimal latency. * **Balanced (default)**: Provides a balance between retrieval speed and quality. * **Quality**: Prioritizes finding the most relevant information, which may take slightly longer but can provide more accurate responses. Maximum of 5 mins. No. Currently, we only support documents written in English. Users need AI that can drive conversations to clear outcomes. With Objectives, users can now can define objectives with measurable completion criteria, branch automatically based on user responses, and track progress in real time. This unlocks workflows use-cases like Health Intakes, HR Interviews, and multi-step questionnaires. Objectives must be added or updated via API only. You cannot configure objectives during persona creation in the UI. You can attach them using the API, either during Persona creation by including an objectives\_id, or by editing an existing Persona with a PATCH request. Objectives are good for very templated one-off conversational use cases. For example, job interviews or health care intake, where there is a very defined path that the conversation should take. These kinds of use cases usually show up with our Enterprise API customers, where they have repetitive use cases at scale. More dynamic, free-flowing conversations usually do not benefit from have or enabling the Objectives feature. For example, talking with a Travel advisor where the conversation is very open ended, would usually not benefit from Objectives. Objectives are good for very defined workflows. Complex multi-session experiences don't fit current Objectives framework. Head to the [Objectives Documentation site](https://docs.tavus.io/sections/conversational-video-interface/persona/objectives). Guardrails help ensure your AI persona stays within appropriate boundaries and follows your defined rules during conversations. Guardrails must be added or updated via API only. You cannot configure guardrails during persona creation in the UI. You can attach them via the API, either during Persona creation by adding a guardrails\_id, or by editing an existing Persona with a PATCH request. Yes. You might have one set of Guardrails for a healthcare assistant to ensure medical compliance, and another for an education-focused Persona to keep all conversations age-appropriate. Head to the [Guardrails Documentation site](https://docs.tavus.io/sections/conversational-video-interface/persona/guardrails). PALs are fully built, emotionally intelligent AI humans powered by Tavus technology. They see, listen, remember, and take action across chat, voice, and video—offering lifelike, natural interaction out of the box. Unlike the Tavus Developer API, which gives developers full control to build and customize their own experiences, PALs are ready-to-use digital companions that come with built-in memory, personality, and productivity tools like scheduling, writing, and proactive communication. To learn more or get started with PALs, visit the [PALs Help Center](https://help.tavus.io). **Daily** is a platform that offers prebuilt video call apps and APIs, allowing you to easily integrate video chat into your web applications. You can embed a customizable video call widget into your site with just a few lines of code and access features like screen sharing and recording. **Tavus partners with Daily to power video conversations with our replicas.** * You **do not** need to sign up for a Daily account to use Tavus's Conversational Video Interface. * All you need is the Daily room URL (called `conversation_url` in our system) that is returned by the Tavus API. You can serve this link directly to your end users or embed it. You can use Daily Prebuilt if you want a full-featured call UI and JavaScript control over the conversation. Once you have the Daily room URL (`conversation_url`) ready, replace `DAILY_ROOM_URL` in the code snippet below with your room URL. ```html theme={null} ``` That's it! For more details and options for embedding, check out Daily's documentation. or [our implementation guides](https://docs.tavus.io/sections/integrations/embedding-cvi#how-can-i-reduce-background-noise-during-calls). You can use an iframe if you just want to embed the conversation video with minimal setup. Once you have the Daily room URL (`conversation_url`) ready, replace `YOUR_TAVUS_MEETING_URL` in the iframe code snippet below with your room URL. ```html theme={null} ``` That's it! For more details and options for embedding, check out Daily's documentation. or [our implementation guides](https://docs.tavus.io/sections/integrations/embedding-cvi#how-can-i-reduce-background-noise-during-calls). To add a custom LLM layer, you'll need the model name, base URL, and API key from your LLM provider. Then, include the LLM config in your `layers` field when creating a persona using the Create Persona API. Example configuration: ```json {8-13} theme={null} { "persona_name": "Storyteller", "system_prompt": "You are a storyteller who entertains people of all ages.", "context": "Your favorite stories include Little Red Riding Hood and The Three Little Pigs.", "pipeline_mode": "full", "default_replica_id": "r665388ec672", "layers": { "llm": { "model": "gpt-3.5-turbo", "base_url": "https://api.openai.com/v1", "api_key": "your-api-key", "speculative_inference": true } } } ``` For more details, refer to our [Large Language Model (LLM) documentation](/sections/conversational-video-interface/persona/llm#custom-llms). You can integrate with third-party TTS providers by configuring the tts object in your persona. Supported engines include: * Cartesia * ElevenLabs Example configuration: ```json theme={null} { "layers": { "tts": { "api_key": "your-tts-provider-api-key", "tts_engine": "cartesia", "external_voice_id": "your-voice-id", "voice_settings": { "speed": "normal", "emotion": ["positivity:high", "curiosity"] }, "tts_emotion_control": true, "tts_model_name": "sonic" } } } ``` For more details, read more on [our TTS documentation](/sections/conversational-video-interface/persona/tts). You need to create a webhook endpoint that can receive POST requests from Tavus. This endpoint will receive the callback events for the visual summary after the conversation ended. Then, add `callback_url` property when creating the conversation ```sh {8} theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "p596401c2cf9", "replica_id": "rf4703150052", "callback_url": "your_webhook_url" }' ``` You need to create a webhook endpoint that can receive `POST` requests from Tavus. This endpoint will receive the callback events for the transcripts after the conversation ended. Then, add `callback_url` property when creating the conversation. ```sh {8} theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "p596401c2cf9", "replica_id": "rf4703150052", "callback_url": "your_webhook_url" }' ``` Your backend then will receive an event with properties `event_type = application.transcription_ready` when the transcript is ready. ```json application.transcription_ready [expandable] theme={null} { "properties": { "replica_id": "", "transcript": [ { "role": "system", "content": "You are in a live video conference call with a user. You will get user message with two identifiers, 'USER SPEECH:' and 'VISUAL SCENE:', where 'USER SPEECH:' is what the person actually tells you, and 'VISUAL SCENE:' is what you are seeing when you look at them. Only use the information provided in 'VISUAL SCENE:' if the user asks what you see. Don't output identifiers such as 'USER SPEECH:' or 'VISUAL SCENE:' in your response. Reply in short sentences, talk to the user in a casual way.Respond only in english. " }, { "role": "user", "content": " Hello, tell me a story. " }, { "role": "assistant", "content": "I've got a great one about a guy who traveled back in time. Want to hear it? " }, { "role": "user", "content": "USER_SPEECH: Yeah I'd love to hear it. VISUAL_SCENE: The image shows a close-up of a person's face, focusing on their forehead, eyes, and nose. In the background, there is a television screen mounted on a wall. The setting appears to be indoors, possibly in a public or commercial space." }, { "role": "assistant", "content": "Let me think for a sec. Alright, so there was this mysterious island that appeared out of nowhere, and people started disappearing when they went to explore it. " }, ] }, "conversation_id": "", "webhook_url": "", "message_type": "application", "event_type": "application.transcription_ready", "timestamp": "2025-02-10T21:30:06.141454Z" } ``` You need to create a webhook endpoint that can receive `POST` requests from Tavus. This endpoint will receive the callback events for the visual summary after the conversation ended. Then, add `callback_url` property when creating the conversation. ```sh {8} theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "p596401c2cf9", "replica_id": "rf4703150052", "callback_url": "your_webhook_url" }' ``` Your backend then will receive an event with properties `event_type = application.perception_analysis` when the summary is ready. ```json application.perception_analysis theme={null} { "properties": { "analysis": "Here's a summary of the visual observations from the video call:\n\n* **Overall Demeanor & Emotional State:** The user consistently appeared calm, collected, and neutral. They were frequently described as pensive, contemplative, or focused, suggesting they were often engaged in thought or listening attentively. No strong positive or negative emotions were consistently detected.\n\n* **Appearance:**\n * The user is a young Asian male, likely in his early 20s, with dark hair.\n * He consistently wore a black shirt, sometimes specifically identified as a black t-shirt. One observation mentioned a \"1989\" print on the shirt.\n * He was consistently looking directly at the camera.\n\n* **Environment:** The user was consistently in an indoor setting, most likely an office or home. Common background elements included:\n * White walls.\n * Windows or glass panels/partitions, often with black frames.\n * Another person was partially visible in the background for several observations.\n\n* **Actions:**\n * The user was seen talking and gesturing with his hand in one observation, indicating he was actively participating in a conversation.\n\n* **Ambient Awareness Queries:**\n * **Acne:** Acne was initially detected on the user's face in one observation, but later observations did not detect it. This suggests that acne may have been visible at one point but not throughout the entire call.\n * **Distress/Discomfort:** No signs of distress or discomfort were observed at any point during the call." }, "conversation_id": "", "webhook_url": "", "message_type": "application", "event_type": "application.perception_analysis", "timestamp": "2025-06-19T06:57:32.480826Z" } ``` Tavus offers flexibility in choosing the LLM (Large Language Model) to power your conversational replicas. You can either use one of Tavus's own models or bring your own! * **Tavus-Provided LLMs:** You can choose between three different models: * **`tavus-gpt-oss`:** The **default** choice if no LLM layer is provided. * **`tavus-gpt-4o`:** Another viable option for complex interactions. * **`tavus-gpt-4o-mini`:** Faster than `tavus-gpt-4o` at the slight cost of performance. * **No LLM Layer:** If you don't include an LLM layer, Tavus will automatically default to a Tavus-provided model. This allows you to tailor the conversational experience to your specific needs, whether you prioritize speed, intelligence, or a balance of both. * The default LLM, `tavus-gpt-oss`, has a **limit of 32,000 tokens**. * Contexts over **25,000 tokens** will experience noticeable performance degradation (slower response times). 1 token ≈ 4 characters; therefore 32,000 tokens ≈ 128,000 characters (including spaces and punctuation). When recording footage for training conversational replicas, here are some key tips to ensure high quality: 1. **Minimal Head Movement:** Aim to keep your head and body as still as possible during the recording. This helps in maintaining consistency and improves the overall quality of the training data. 2. **Pause and Be Still:** It's recommended to stop, stay still, and remain silent for at least 5 seconds at regular intervals throughout the script. These pauses are crucial for helping the replica appear natural during moments of silence in a conversation. 3. **Use a Laptop Camera:** Recording on a laptop camera, as if you were on a Zoom call, often yields the most natural results. This setup mimics a familiar conversational setting, enhancing the naturalness of the footage. You can configure perception tools in the `layers.perception` object when creating a persona: ```json [expandable] theme={null} { "layers": { "perception": { "perception_model": "raven-0", "ambient_awareness_queries": [ "Is the user showing an ID card?", "Is the user wearing a mask?" ], "perception_tool_prompt": "You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a bright outfit is detected.", "perception_tools": [ { "type": "function", "function": { "name": "notify_if_id_shown", "description": "Use this function when a drivers license or passport is detected in the image with high confidence", "parameters": { "type": "object", "properties": { "id_type": { "type": "string", "description": "best guess on what type of ID it is" } }, "required": ["id_type"] } } } ] } } } ``` Or modify perception tools using the [Update Persona API](/api-reference/personas/patch-persona): ```sh [expandable] theme={null} curl --request PATCH \ --url https://tavusapi.com/v2/personas/{persona_id} \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '[ { "op": "replace", "path": "/layers/perception/perception_tools", "value": [ { "type": "function", "function": { "name": "detect_glasses", "description": "Trigger this function if the user is wearing glasses", "parameters": { "type": "object", "properties": { "glasses_type": { "type": "string", "description": "Type of glasses (e.g., reading, sunglasses)" } }, "required": ["glasses_type"] } } } ] } ]' ``` Read more on this [page](/sections/conversational-video-interface/persona/perception) No, it will automatically join as soon as it's ready! Out of the box, Tavus handles the complex backend infrastructure for you: LLMs, rendering, video delivery, and conversational intelligence are all preconfigured and production-ready. From there, nearly everything else is customizable: • What your AI Persona sees • How they look and sound • How they behave in conversation Tavus offers unmatched flexibility, whether you're personalizing voice, face, or behavior, you're in control. Tavus uses WebRTC to power real-time, face-to-face video interactions with extremely low latency. Unlike other platforms that piece together third-party tools, we built the entire pipeline (from LLM to rendering) to keep latency low and responsiveness high. Ironically, by minimizing reliance on multiple APIs, we've made everything faster. Tavus CVI is powered by a tightly integrated stack of components, including: * LLMs for natural language understanding * Real-time rendering for facial video * APIs for Persona creation and conversational control You can explore key APIs here: • [Create a Persona](/api-reference/personas/create-persona) • [Create a Conversation](/api-reference/conversations/create-conversation) Tavus supports over 30 spoken languages through a combination of Cartesia (our default TTS engine) and ElevenLabs. If a language isn't supported by Cartesia, Tavus automatically switches to ElevenLabs so your AI Persona can still speak fluently. Supported languages include English (all variants), French, German, Spanish, Portuguese, Chinese, Japanese, Hindi, Italian, Korean, Dutch, Polish, Russian, Swedish, Turkish, Indonesian, Filipino, Bulgarian, Romanian, Arabic, Czech, Greek, Finnish, Croatian, Malay, Slovak, Danish, Tamil, Ukrainian, Hungarian, Norwegian, and Vietnamese. View the [full supported language list](https://docs.tavus.io/sections/conversational-video-interface/language-support) for complete details and language-specific information. Yes to accents. Not quite for regional dialects. When you generate a voice using Tavus, the system will default to the accent used in training. For example, if you provide Brazilian Portuguese as training input, the AI Persona will speak with a Brazilian accent. Tavus' TTS providers auto-detect and match accordingly. Tavus supports full orchestration through function calling. That means your AI persona can interact with external tools—calendar apps, CRMs, email systems, and more—based on your setup. Just define the function endpoints and let your AI persona take action. Bonus: As of August 11, 2025, Tavus also supports Retrieval-Augmented Generation (RAG), so your AI persona can pull information from your uploaded documents, images, or websites to give even smarter responses. Learn more via [Tavus Documentation](/sections/conversational-video-interface). A good prompt is short, clear, and specific, like giving directions to a 5-year-old. Avoid data dumping. Instead, guide the AI with context and intent. Tavus helps by offering system prompt templates, use-case guidance, and API fields to structure your instructions. You can bring your own LLM by configuring the layers field in the Create Persona API. Here's an example: ```json theme={null} { "persona_name": "Storyteller", "system_prompt": "You are a storyteller who entertains people of all ages.", "context": "Your favorite stories include Little Red Riding Hood and The Three Little Pigs.", "pipeline_mode": "full", "default_replica_id": "r665388ec672", "layers": { "llm": { "model": "gpt-3.5-turbo", "base_url": "https://api.openai.com/v1", "api_key": "your-api-key", "speculative_inference": true } } } ``` More info here: [LLM Documentation](https://docs.tavus.io/sections/conversational-video-interface/persona/llm#custom-llms) Think of it this way: Tavus is the engine, and you design the car. The UI is 100% up to you. To make it easier, we offer a full [Component Library](/sections/conversational-video-interface/component-library) you can copy and paste into your build—video frames, mic/camera toggles, and more. You can use third-party text-to-speech (TTS) providers like Cartesia or ElevenLabs. Just pass your voice settings in the tts object during Persona setup: ```json theme={null} { "layers": { "tts": { "api_key": "your-tts-provider-api-key", "tts_engine": "cartesia", "external_voice_id": "your-voice-id", "voice_settings": { "speed": "normal", "emotion": ["positivity:high", "curiosity"] }, "tts_emotion_control": true, "tts_model_name": "sonic" } } } ``` Learn more in our [TTS Documentation](/sections/conversational-video-interface/persona/tts). Tavus uses Daily's video engine, which includes built-in noise cancellation. You can enable this through the updateInputSettings() method in the Daily API. Yes! Daily supports event listeners you can hook into. Track actions like participants joining, leaving, screen sharing, and more. Great for analytics or triggering workflows. Within the create convo API, there's this property: image.jpeg Tavus is built with enterprise-grade security in mind. We're: * SOC 2 compliant * GDPR compliant * HIPAA compliant * BAA compliant This ensures your data is handled with the highest levels of care and control. --- # Source: https://docs.tavus.io/api-reference/conversations/get-conversation.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Conversation > This endpoint returns a single conversation by its unique identifier. You can append `?verbose=true` to the URL to receive additional event data in the response, including: * `shutdown_reason`: The reason why the conversation ended (e.g., "participant\_left\_timeout") * `transcript`: A complete transcript of the conversation with role-based messages (via `application.transcription_ready`) * `system.replica_joined`: When the replica joined the conversation * `system.shutdown`: When and why the conversation ended * `application.perception_analysis`: The final visual analysis of the user that includes their appearance, behavior, emotional states, and screen activities This is particularly useful as an alternative to using the `callback_url` parameter on the create conversation endpoint for retrieving detailed conversation data. ## OpenAPI ````yaml get /v2/conversations/{conversation_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/conversations/{conversation_id}: parameters: - name: conversation_id in: path required: true description: The unique identifier of the conversation. schema: type: string example: c123456 get: tags: - Conversations summary: Get Conversation description: | This endpoint returns a single conversation by its unique identifier. operationId: getConversation responses: '200': description: '' content: application/json: schema: type: object properties: conversation_id: type: string description: A unique identifier for the conversation. example: c123456 conversation_name: type: string description: The name of the conversation. example: A Meeting with Hassaan conversation_url: type: string description: A direct link to join the conversation. example: https://tavus.daily.co/c123456 callback_url: type: string description: >- The url that will receive webhooks with updates of the conversation state. example: https://yourwebsite.com/webhook status: type: string description: The status of the conversation. example: active replica_id: type: string description: >- A unique identifier for the replica used to create this conversation example: r79e1c033f persona_id: type: string description: >- A unique identifier for the persona used to create this conversation example: p5317866 created_at: type: string description: The date and time the conversation was created. example: '' updated_at: type: string example: '' description: >- The date and time of when the conversation was last updated. '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid conversation_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 ```` --- # Source: https://docs.tavus.io/api-reference/conversations/get-conversations.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # List Conversations > This endpoint returns a list of all Conversations created by the account associated with the API Key in use. ## OpenAPI ````yaml get /v2/conversations openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/conversations: get: tags: - Conversations summary: List Conversations description: > This endpoint returns a list of all Conversations created by the account associated with the API Key in use. operationId: listConversations parameters: - in: query name: limit schema: type: integer description: The number of conversations to return per page. Default is 10. - in: query name: page schema: type: integer description: The page number to return. Default is 1. - in: query name: status schema: type: string description: 'Filter the conversations by status. Possible values: active, ended.' responses: '200': description: '' content: application/json: schema: type: object properties: data: type: array items: type: object properties: conversation_id: type: string description: A unique identifier for the conversation. example: c123456 conversation_name: type: string description: A name for the conversation. example: A Meeting with Hassaan status: type: string description: The status of the video. example: active conversation_url: type: string description: A direct link to join the conversation. example: https://tavus.daily.co/c123456 callback_url: type: string description: >- The url that will receive webhooks with updates of the conversation state. example: https://yourwebsite.com/webhook replica_id: type: string description: >- A unique identifier for the replica used to create this conversation example: r79e1c033f persona_id: type: string description: >- A unique identifier for the persona used to create this conversation example: p5317866 created_at: type: string description: The date and time the conversation was created. example: '' updated_at: type: string description: >- The date and time of when the conversation was last updated. total_count: type: integer description: >- The total number of conversations 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: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/documents/get-document.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Document > Retrieve a specific document by ID Retrieve detailed information about a specific document using its unique identifier. ## OpenAPI ````yaml get /v2/documents/{document_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/documents/{document_id}: get: tags: - Documents summary: Get Document description: > Retrieve detailed information about a specific document using its unique identifier. operationId: getDocument parameters: - in: path name: document_id required: true schema: type: string description: The unique identifier of the document to retrieve example: d8-5c71baca86fc responses: '200': description: Document details content: application/json: schema: type: object properties: document_id: type: string description: Unique identifier for the document example: d8-5c71baca86fc document_name: type: string description: Name of the document example: Example Docs document_url: type: string description: URL of the document example: https://docs.example.com/ status: type: string description: Current status of the document processing example: ready progress: type: string nullable: true description: Progress indicator for document processing example: null created_at: type: string description: ISO 8601 timestamp of when the document was created example: '2024-01-01T12:00:00Z' updated_at: type: string description: ISO 8601 timestamp of when the document was last updated example: '2024-01-01T12:05:00Z' callback_url: type: string description: URL that receives status updates example: https://your-server.com/webhook tags: type: array description: Array of document tags items: type: string example: - docs - website crawl_config: type: object nullable: true description: >- The crawl configuration used for this document (only present for crawled websites) properties: depth: type: integer description: Crawl depth setting example: 2 max_pages: type: integer description: Maximum pages setting example: 10 crawled_urls: type: array nullable: true description: >- List of URLs that were crawled (only present for crawled websites after processing completes) items: type: string example: - https://docs.example.com/ - https://docs.example.com/getting-started - https://docs.example.com/api last_crawled_at: type: string nullable: true description: ISO 8601 timestamp of when the document was last crawled example: '2024-01-01T12:00:00Z' crawl_count: type: integer nullable: true description: Number of times the document has been crawled example: 1 '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: The error message example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: The error message example: Document not found security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/documents/get-documents.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # List Documents > Retrieve a list of documents with optional filtering and pagination Retrieve a list of documents with support for pagination, sorting, and filtering by various criteria. ## OpenAPI ````yaml get /v2/documents openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/documents: get: tags: - Documents summary: List Documents description: > Retrieve a list of documents with support for pagination, sorting, and filtering by various criteria. operationId: listDocuments parameters: - in: query name: limit schema: type: integer description: 'Number of documents to return per page (default: 10)' example: 10 - in: query name: page schema: type: integer description: 'Page number for pagination (0-based, default: 0)' example: 0 - in: query name: sort schema: type: string enum: - ascending - descending description: 'Sort direction for the results (default: ascending)' example: ascending - in: query name: status schema: type: string description: Filter documents by status - in: query name: name_or_uuid schema: type: string description: Search for documents by name or UUID - in: query name: tags schema: type: string description: Comma-separated list of tags to filter by example: important,meeting responses: '200': description: List of documents content: application/json: schema: type: object properties: data: type: array items: type: object properties: document_id: type: string description: Unique identifier for the document example: d8-5c71baca86fc document_name: type: string description: Name of the document example: Example Docs document_url: type: string description: URL of the document example: https://docs.example.com/ status: type: string description: Current status of the document processing example: ready progress: type: string nullable: true description: Progress indicator for document processing example: null created_at: type: string description: ISO 8601 timestamp of when the document was created example: '2024-01-01T12:00:00Z' updated_at: type: string description: >- ISO 8601 timestamp of when the document was last updated example: '2024-01-01T12:05:00Z' callback_url: type: string description: URL that receives status updates example: https://your-server.com/webhook tags: type: array description: Array of document tags items: type: string example: - docs - website crawl_config: type: object nullable: true description: >- The crawl configuration used for this document (only present for crawled websites) properties: depth: type: integer description: Crawl depth setting example: 2 max_pages: type: integer description: Maximum pages setting example: 10 crawled_urls: type: array nullable: true description: >- List of URLs that were crawled (only present for crawled websites after processing completes) items: type: string example: - https://docs.example.com/ - https://docs.example.com/getting-started last_crawled_at: type: string nullable: true description: >- ISO 8601 timestamp of when the document was last crawled example: '2024-01-01T12:00:00Z' crawl_count: type: integer nullable: true description: Number of times the document has been crawled example: 1 total_count: type: integer description: Total number of documents matching the filter criteria example: 42 page: type: integer description: Current page number example: 0 limit: type: integer description: Number of documents per page example: 10 '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message example: 'Invalid request: limit must be a positive integer' '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 ```` --- # Source: https://docs.tavus.io/api-reference/guardrails/get-guardrails-list.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Guardrails (All Sets) > This endpoint returns a list of all sets of guardrails. ## OpenAPI ````yaml get /v2/guardrails openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/guardrails: get: tags: - Guardrails summary: Get Guardrails (All Sets) description: | This endpoint returns a list of all sets of guardrails. operationId: getGuardrails parameters: - in: query name: limit schema: type: integer description: The number of guardrails to return per page. Default is 10. - in: query name: page schema: type: integer description: The page number to return. Default is 1. responses: '200': description: Successfully retrieved guardrails content: application/json: schema: type: object properties: data: type: array items: type: object properties: guardrails_id: type: string description: Unique identifier for the guardrails example: g12345 created_at: type: string description: >- ISO 8601 timestamp of when the guardrails were created example: '2024-01-15T10:30:00Z' updated_at: type: string description: >- ISO 8601 timestamp of when the guardrails were last updated example: '2024-01-15T10:30:00Z' total_count: type: integer description: The total number of guardrails example: 15 '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 ```` --- # Source: https://docs.tavus.io/api-reference/guardrails/get-guardrails.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Guardrails (One Set) > This endpoint returns a single set of guardrails by its unique identifier. ## OpenAPI ````yaml get /v2/guardrails/{guardrails_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/guardrails/{guardrails_id}: parameters: - name: guardrails_id in: path required: true description: The unique identifier of the guardrails. schema: type: string example: g12345 get: tags: - Guardrails summary: Get Guardrails (One Set) description: > This endpoint returns a single set of guardrails by its unique identifier. operationId: getGuardrail responses: '200': description: Successfully retrieved guardrails content: application/json: schema: type: object properties: data: type: object properties: guardrail_name: type: string description: >- Name of the individual guardrail. Only alphanumeric characters and underscores are allowed. example: healthcare_compliance_guardrail guardrail_prompt: type: string description: >- The detailed prompt that defines the behavioral boundaries and restrictions example: >- Never discuss competitor products, share sensitive medical information, or provide medical advice outside approved guidelines modality: type: string description: >- The communication modality for an individual guardrail. If set to `verbal`, the guardrail will be enforced by the user's responses. If set `visual`, the guardrail can only be enforced by visual / perception cues observed by Raven enum: - verbal - visual default: verbal example: verbal callback_url: type: string description: >- URL that will receive notifications when the guardrail is triggered example: https://your-server.com/guardrails-webhook created_at: type: string description: ISO 8601 timestamp of when the guardrails were created example: '2024-01-15T10:30:00Z' updated_at: type: string description: >- ISO 8601 timestamp of when the guardrails were last updated example: '2024-01-15T10:30:00Z' '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid guardrails_id '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: error: type: string description: The error message. example: Guardrails not found security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/objectives/get-objectives-list.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Objectives > This endpoint returns a list of all objectives. ## OpenAPI ````yaml get /v2/objectives openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/objectives: get: tags: - Objectives summary: Get Objectives description: | This endpoint returns a list of all objectives. operationId: getObjectives parameters: - in: query name: limit schema: type: integer description: The number of objectives to return per page. Default is 10. - in: query name: page schema: type: integer description: The page number to return. Default is 1. responses: '200': description: Successfully retrieved objectives content: application/json: schema: type: object properties: data: type: array items: type: object properties: objectives_id: type: string description: Unique identifier for the objective example: o12345 objective_name: type: string description: Name of the objective example: ask_if_new_patient objective_prompt: type: string description: >- The detailed prompt that defines what the objective should accomplish example: >- Ask the patient if they are new or have been here before confirmation_mode: type: string description: How the objective completion should be confirmed example: auto output_variables: type: array description: >- List of variables that should be extracted or collected during the objective items: type: string example: - patient_status modality: type: string description: The communication modality for the objective example: verbal next_conditional_objectives: type: object description: >- Mapping of objective names to conditions that must be satisfied for that objective to be activated additionalProperties: type: string example: new_patient_intake_process: >- If the patient has never been to the practice before existing_patient_intake_process: If the patient has been to the practice before next_required_objectives: type: array description: >- List of objective names that will be activated once the current objective is completed items: type: string example: - get_patient_name callback_url: type: string description: >- URL that will receive notifications when the objective is completed example: https://your-server.com/webhook created_at: type: string description: ISO 8601 timestamp of when the objective was created example: '2024-01-15T10:30:00Z' updated_at: type: string description: >- ISO 8601 timestamp of when the objective was last updated example: '2024-01-15T10:30:00Z' total_count: type: integer description: The total number of objectives example: 25 '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 ```` --- # Source: https://docs.tavus.io/api-reference/objectives/get-objectives.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Objective > This endpoint returns a single objective by its unique identifier. ## OpenAPI ````yaml get /v2/objectives/{objectives_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/objectives/{objectives_id}: parameters: - name: objectives_id in: path required: true description: The unique identifier of the objective. schema: type: string example: o12345 get: tags: - Objectives summary: Get Objective description: | This endpoint returns a single objective by its unique identifier. operationId: getObjective parameters: - name: objectives_id in: path required: true description: The unique identifier of the objective. schema: type: string example: o12345 responses: '200': description: Successfully retrieved objective content: application/json: schema: type: object properties: data: type: object properties: objective_name: type: string description: Name of the objective example: ask_if_new_patient objective_prompt: type: string description: >- The detailed prompt that defines what the objective should accomplish example: >- Ask the patient if they are new or have been here before confirmation_mode: type: string description: How the objective completion should be confirmed example: auto output_variables: type: array description: >- List of variables that should be extracted or collected during the objective items: type: string example: - patient_status modality: type: string description: The communication modality for the objective example: verbal next_conditional_objectives: type: object description: >- Mapping of objective names to conditions that must be satisfied for that objective to be activated additionalProperties: type: string example: new_patient_intake_process: If the patient has never been to the practice before existing_patient_intake_process: If the patient has been to the practice before next_required_objectives: type: array description: >- List of objective names that will be activated once the current objective is completed items: type: string example: - get_patient_name callback_url: type: string description: >- URL that will receive notifications when the objective is completed example: https://your-server.com/webhook created_at: type: string description: ISO 8601 timestamp of when the objective was created example: '2024-01-15T10:30:00Z' updated_at: type: string description: >- ISO 8601 timestamp of when the objective was last updated example: '2024-01-15T10:30:00Z' '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid objectives_id '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: error: type: string description: The error message. example: Objective not found security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/personas/get-persona.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Persona > This endpoint returns a single persona by its unique identifier. ## OpenAPI ````yaml get /v2/personas/{persona_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/personas/{persona_id}: parameters: - name: persona_id in: path required: true description: The unique identifier of the persona. schema: type: string example: pf3073f2dcc1 get: tags: - Personas summary: Get Persona description: | This endpoint returns a single persona by its unique identifier. operationId: getPersona responses: '200': description: '' content: application/json: schema: type: object properties: data: type: array items: type: object properties: persona_id: type: string description: A unique identifier for the persona. example: p5317866 persona_name: type: string description: A name for the persona. example: Life Coach system_prompt: type: string description: The system prompt that will be used by the llm. example: >- As a Life Coach, you are a dedicated professional who specializes in... default_replica_id: type: string example: r79e1c033f description: >- The default replica_id associated with this persona if one exists. context: type: string description: The context that will be used by the llm. example: >- Here are a few times that you have helped an individual make a breakthrough in... document_ids: type: array description: >- Array of document IDs that the persona has access to. These documents will be available to the persona in all their conversations. The document_ids are returned in the response of the [Get Document](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints. items: type: string example: - d1234567890 - d2468101214 document_tags: type: array description: >- Array of document tags that the persona has access to. Documents matching these tags will be available to the persona in all their conversations. items: type: string example: - product_info - company_policies layers: type: object properties: llm: type: object properties: model: type: string description: The model name that will be used by the llm. base_url: type: string description: >- The base URL for the OpenAI compatible endpoint if you are using your own llm. example: your-base-url api_key: type: string description: >- The API key for the OpenAI compatible endpoint if you are using your own llm. example: your-api-key tools: type: array description: Optional tools to provide to your custom LLM example: - type: function function: name: get_current_weather description: >- Get the current weather in a given location parameters: type: object properties: location: type: string description: >- The city and state, e.g. San Francisco, CA unit: type: string enum: - celsius - fahrenheit required: - location headers: type: object description: >- Optional headers to provide to your custom LLM example: Authorization: Bearer your-api-key extra_body: type: object description: > Optional parameters to customize the LLM request. For Tavus-hosted models, you can pass `temperature` and `top_p`: - `temperature`: Controls randomness in the model's output. Range typically 0.0 to 2.0. Lower values make output more deterministic and focused, higher values make it more creative and varied. - `top_p`: Controls diversity via nucleus sampling. Range 0.0 to 1.0. Lower values make output more focused on high-probability tokens, higher values allow more diverse token selection. For custom LLMs, you can pass any parameters that your LLM provider supports (e.g., `temperature`, `top_p`, `frequency_penalty`, etc.). example: temperature: 0.7 top_p: 0.9 tts: type: object properties: api_key: type: string description: >- The API key for the chosen TTS provider. Only required when using private voices. example: your-api-key tts_engine: type: string description: The TTS engine that will be used. enum: - cartesia - elevenlabs external_voice_id: type: string description: >- The voice ID used for the TTS engine when you want to customize your replica's voice. Choose from Cartesia's stock voices by referring to their [Voice Catalog](https://docs.cartesia.ai/api-reference/voices/list), or if you want more options you can consider [ElevenLabs](https://elevenlabs.io/docs/api-reference/voices/get-all). example: external-voice-id voice_settings: type: object description: > Optional voice settings to customize TTS behavior. Settings vary by provider. **Cartesia (Sonic-1 only):** - `speed`: Range -1.0 to 1.0 (negative = slower, positive = faster) - `emotion`: Array of emotion tags in format "emotion:level" (e.g., "positivity:high") - Emotions: anger, positivity, surprise, sadness, curiosity - Levels: low, medium, high - [Cartesia Documentation](https://docs.cartesia.ai/2024-11-13/build-with-cartesia/capability-guides/control-speed-and-emotion) **ElevenLabs:** - `speed`: Range 0.0 to 1.0 (0.0 = slowest, 1.0 = fastest) - `stability`: Range 0.0 to 1.0 (0.0 = variable, 1.0 = stable) - `similarity_boost`: Range 0.0 to 1.0 (0.0 = creative, 1.0 = original) - `style`: Range 0.0 to 1.0 (0.0 = neutral, 1.0 = exaggerated) - `use_speaker_boost`: Boolean (enhances speaker similarity) - [ElevenLabs Documentation](https://elevenlabs.io/docs/api-reference/voices/settings/get) example: speed: 0.5 emotion: - positivity:high - curiosity tts_emotion_control: type: boolean description: >- If true, the TTS engine will be able to control the emotion of the voice. Only available for Cartesia TTS. example: 'false' tts_model_name: type: string description: >- The model name that will be used by the TTS engine. Please double check this with the TTS provider you are using to ensure valid model names. example: sonic perception: type: object properties: perception_model: type: string description: >- The perception model to use. Options include `raven-0` for advanced multimodal perception or `basic` for simpler vision capabilities, and `off` to disable all perception. enum: - raven-0 - basic - 'off' example: raven-0 ambient_awareness_queries: type: array description: >- Custom queries that Raven will continuously monitor for in the visual stream. These provide ambient context without requiring explicit prompting. items: type: string example: - Is the user showing an ID card? - >- Does the user appear distressed or uncomfortable? perception_tool_prompt: type: string description: >- A prompt that details how and when to use the tools that are passed to the perception layer. This helps the replica understand the context of the perception tools and grounds it. example: >- You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a form of ID is detected. perception_tools: type: array description: >- Tools that can be triggered based on visual context, enabling automated actions in response to visual cues. items: type: object properties: name: type: string description: The name of the tool to be called. description: type: string description: >- A description of what the tool does and when it should be called. example: - type: function function: name: notify_if_id_shown description: >- Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask() parameters: type: object properties: id_type: type: string description: best guess on what type of ID it is required: - id_type stt: type: object description: > **Note**: Turn-taking is now configured on the [Conversational Flow layer](/sections/conversational-video-interface/persona/conversational-flow). properties: stt_engine: type: string description: >- The STT engine that will be used. `tavus-turbo` is our lowest-latency model, but `tavus-advanced` provides higher transcription accuracy. Please note that non-English languages will default to `tavus-advanced` if not specified. enum: - tavus-turbo - tavus-advanced hotwords: type: string description: >- The hotwords that will be used for the STT engine. example: This is a hotword example created_at: type: string description: The date and time the persona was created. example: '' updated_at: type: string description: >- The date and time of when the persona was last updated. '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid persona_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 ```` --- # Source: https://docs.tavus.io/api-reference/personas/get-personas.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # List Personas > This endpoint returns a list of all Personas created by the account associated with the API Key in use. ## OpenAPI ````yaml get /v2/personas openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/personas: get: tags: - Personas summary: List Personas description: > This endpoint returns a list of all Personas created by the account associated with the API Key in use. operationId: listPersonas parameters: - in: query name: limit schema: type: integer description: The number of personas to return per page. Default is 10. - in: query name: page schema: type: integer description: The page number to return. Default is 1. - in: query name: persona_type schema: type: string description: >- Filter the personas by type. Possible values: user, system. System personas are personas that have been created by Tavus. enum: - user - system responses: '200': description: '' content: application/json: schema: type: object properties: data: type: array items: type: object properties: persona_id: type: string description: A unique identifier for the persona. example: p5317866 persona_name: type: string description: A name for the persona. example: Life Coach system_prompt: type: string description: The system prompt that will be used by the llm. example: >- As a Life Coach, you are a dedicated professional who specializes in... default_replica_id: type: string example: r79e1c033f description: >- The default replica_id associated with this persona if one exists. context: type: string description: The context that will be used by the llm. example: >- Here are a few times that you have helped an individual make a breakthrough in... document_ids: type: array description: >- Array of document IDs that the persona has access to. These documents will be available to the persona in all their conversations. The document_ids are returned in the response of the [Get Document](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints. items: type: string example: - d1234567890 - d2468101214 document_tags: type: array description: >- Array of document tags that the persona has access to. Documents matching these tags will be available to the persona in all their conversations. items: type: string example: - product_info - company_policies layers: type: object properties: llm: type: object properties: model: type: string description: The model name that will be used by the llm. base_url: type: string description: >- The base URL for the OpenAI compatible endpoint if you are using your own llm. example: your-base-url api_key: type: string description: >- The API key for the OpenAI compatible endpoint if you are using your own llm. example: your-api-key tools: type: array description: Optional tools to provide to your custom LLM example: - type: function function: name: get_current_weather description: >- Get the current weather in a given location parameters: type: object properties: location: type: string description: >- The city and state, e.g. San Francisco, CA unit: type: string enum: - celsius - fahrenheit required: - location tts: type: object properties: api_key: type: string description: >- The API key for the chosen TTS provider. Only required when using private voices. example: your-api-key tts_engine: type: string description: The TTS engine that will be used. enum: - cartesia - elevenlabs external_voice_id: type: string description: >- The voice ID used for the TTS engine when you want to customize your replica's voice. Choose from Cartesia's stock voices by referring to their [Voice Catalog](https://docs.cartesia.ai/api-reference/voices/list), or if you want more options you can consider [ElevenLabs](https://elevenlabs.io/docs/api-reference/voices/get-all). example: external-voice-id voice_settings: type: object description: > Optional voice settings to customize TTS behavior. Settings vary by provider. **Cartesia (Sonic-1 only):** - `speed`: Range -1.0 to 1.0 (negative = slower, positive = faster) - `emotion`: Array of emotion tags in format "emotion:level" (e.g., "positivity:high") - Emotions: anger, positivity, surprise, sadness, curiosity - Levels: low, medium, high - [Cartesia Documentation](https://docs.cartesia.ai/2024-11-13/build-with-cartesia/capability-guides/control-speed-and-emotion) **ElevenLabs:** - `speed`: Range 0.0 to 1.0 (0.0 = slowest, 1.0 = fastest) - `stability`: Range 0.0 to 1.0 (0.0 = variable, 1.0 = stable) - `similarity_boost`: Range 0.0 to 1.0 (0.0 = creative, 1.0 = original) - `style`: Range 0.0 to 1.0 (0.0 = neutral, 1.0 = exaggerated) - `use_speaker_boost`: Boolean (enhances speaker similarity) - [ElevenLabs Documentation](https://elevenlabs.io/docs/api-reference/voices/settings/get) example: speed: 0.5 emotion: - positivity:high - curiosity tts_emotion_control: type: boolean description: >- If true, the TTS engine will be able to control the emotion of the voice. Only available for Cartesia TTS. example: 'false' tts_model_name: type: string description: >- The model name that will be used by the TTS engine. Please double check this with the TTS provider you are using to ensure valid model names. example: sonic perception: type: object properties: perception_model: type: string description: >- The perception model to use. Options include `raven-0` for advanced multimodal perception or `basic` for simpler vision capabilities, and `off` to disable all perception. enum: - raven-0 - basic - 'off' example: raven-0 ambient_awareness_queries: type: array description: >- Custom queries that Raven will continuously monitor for in the visual stream. These provide ambient context without requiring explicit prompting. items: type: string example: - Is the user showing an ID card? - >- Does the user appear distressed or uncomfortable? perception_tool_prompt: type: string description: >- A prompt that details how and when to use the tools that are passed to the perception layer. This helps the replica understand the context of the perception tools and grounds it. example: >- You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a form of ID is detected. perception_tools: type: array description: >- Tools that can be triggered based on visual context, enabling automated actions in response to visual cues. items: type: object properties: name: type: string description: The name of the tool to be called. description: type: string description: >- A description of what the tool does and when it should be called. example: - type: function function: name: notify_if_id_shown description: >- Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask() parameters: type: object properties: id_type: type: string description: best guess on what type of ID it is required: - id_type stt: type: object description: > **Note**: Turn-taking is now configured on the [Conversational Flow layer](/sections/conversational-video-interface/persona/conversational-flow). properties: stt_engine: type: string description: >- The STT engine that will be used. `tavus-turbo` is our lowest-latency model, but `tavus-advanced` provides higher transcription accuracy. Please note that non-English languages will default to `tavus-advanced` if not specified. enum: - tavus-turbo - tavus-advanced hotwords: type: string description: >- The hotwords that will be used for the STT engine. example: This is a hotword example created_at: type: string description: The date and time the persona was created. example: '' updated_at: type: string description: >- The date and time of when the persona was last updated. total_count: type: integer description: The total number of personas 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: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/phoenix-replica-model/get-replica.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Get 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. ## OpenAPI ````yaml get /v2/replicas/{replica_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/replicas/{replica_id}: get: tags: - Replicas summary: Get Replica description: > 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. operationId: getReplica parameters: - in: path name: replica_id required: true schema: type: string description: A unique identifier for the replica. - in: query name: verbose schema: type: boolean description: >- If set to true, the response will include additional replica data such as replica_type. responses: '200': description: '' content: application/json: schema: type: object properties: replica_id: type: string example: r783537ef5 description: A unique identifier for the replica. replica_name: type: string example: My Replica description: The name of the replica. thumbnail_video_url: type: string description: >- A direct link to the video that will be used as the thumbnail for the replica. training_progress: type: string example: 100/100 description: The progress of the replica training. status: type: string example: completed description: >- The status of the replica. Possible values: started, completed, error. created_at: type: string example: '2024-01-24T07:14:03.327Z' description: The date and time the replica was created. updated_at: type: string example: '2024-01-24T07:14:03.327Z' description: The date and time of when the replica was last updated. error_message: type: string nullable: true description: >- If the replica has an error, this will contain the error message. replica_type: type: string example: user' description: >- If `verbose` query paramter is set to true. The type of replica. Possible values: user, system. User replicas are replicas that have been created by users. System replicas are stock Tavus replicas that anyone may use '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: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/phoenix-replica-model/get-replicas.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # List Replicas > 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. ## OpenAPI ````yaml get /v2/replicas openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/replicas: get: tags: - Replicas summary: List Replicas description: > 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. operationId: listReplicas parameters: - in: query name: limit schema: type: integer description: The number of replicas to return per page. - in: query name: page schema: type: integer description: The page number to return - in: query name: verbose schema: type: boolean description: >- If set to true, the response will include additional replica data such as the replica type. - in: query name: replica_type schema: type: string enum: - user - system description: >- If set to user, the response will only include user replicas. If set to system, the response will only include stock replicas. - in: query name: replica_ids schema: type: string description: >- A comma separated list of replica ids to filter the response by. Example: `replica_ids=re1074c227,r243eed46c` responses: '200': description: '' content: application/json: schema: type: object properties: data: type: array items: type: object properties: replica_id: type: string example: r783537ef5 description: A unique identifier for the replica. replica_name: type: string example: My Replica description: The name of the replica. thumbnail_video_url: type: string description: >- A direct link to the video that will be used as the thumbnail for the replica. training_progress: type: string example: 100/100 description: The progress of the replica training. status: type: string example: completed description: >- The status of the replica. Possible values: started, completed, error. created_at: type: string replica_type: type: string example: user' description: >- If `verbose` query paramter is set to true. The type of replica. Possible values: user, system. User replicas are replicas that have been created by users. System replicas are stock Tavus replicas that anyone may use total_count: type: integer description: The total number of replicas given the filters provided. example: 42 '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 ```` --- # Source: https://docs.tavus.io/api-reference/video-request/get-video.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Get 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. ## OpenAPI ````yaml get /v2/videos/{video_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/videos/{video_id}: get: tags: - Videos summary: Get Video description: > 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. 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: >- The status of the video. Possible values: queued, generating, ready, deleted, error. 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. stream_url: type: string description: A direct link to stream your generated video. hosted_url: type: string description: >- A direct link to view your generated video, hosted by Tavus. 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: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/video-request/get-videos.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # List Videos > This endpoint returns a list of all Videos created by the account associated with the API Key in use. ## OpenAPI ````yaml get /v2/videos openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents 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. Default is 1. responses: '200': description: '' content: application/json: schema: type: object properties: data: type: array 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: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/sections/conversational-video-interface/persona/guardrails.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Guardrails > Guardrails provide your persona with strict behavioral guidelines that will be rigorously followed throughout every conversation. Guardrails act as a safety layer that works alongside your system prompt to enforce specific rules, restrictions, and behavioral patterns that your persona must adhere to during conversations. For example, if you're creating a customer service persona for a financial institution, you can apply guardrails that prevent the persona from discussing a competitor's products, sharing sensitive financial data, or providing investment advice outside of approved guidelines. It is highly recommended to use the [Persona Builder](https://platform.tavus.io/conversations/builder) to create your guardrails, although you can use the [Create Guardrails](/api-reference/guardrails/create-guardrails) API directly. When designing your guardrails with the Persona Builder, it's helpful to keep a few things in mind: * Be specific about what topics, behaviors, or responses should be restricted or avoided. * Consider edge cases where participants might try to circumvent the guardrails through creative prompting. * Ensure your guardrails complement, rather than contradict, your persona's system prompt and intended functionality. * Test your guardrails with various conversation scenarios to ensure they activate appropriately without being overly restrictive. If you would like to manually attach guardrails to a persona, you can either: * Add them during [persona creation](/api-reference/personas/create-persona) like this: ```sh theme={null} curl --request POST \ --url https://tavusapi.com/v2/personas/ \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "system_prompt": "You are a health intake assistant.", "guardrails_id": "g12345" }' ``` OR * Add them by [editing the persona](/api-reference/personas/patch-persona) like this: ```sh theme={null} curl --request PATCH \ --url https://tavusapi.com/v2/personas/{persona_id} \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '[ {"op": "add", "path": "/guardrails_id", "value": "g12345"} ]' ``` For the best results, try creating specific guardrails for different types of personas or conversation contexts. For example, a healthcare consultation might use guardrails to maintain medical compliance, while an educational tutor might use guardrails to enforce child safety and appropriate content guidelines. ## Parameters Within each set of guardrails, you can have multiple guardrail objects defined. ### `guardrails_name` A desciptive name for an individual guardrail. Example: `"Never Discuss Competitor's Products"` This must be a string value without spaces. ### `guardrails_prompt` A text prompt that explains what particular behavior(s) should be observed for a particular guardrail. The more detail you can provide, the better. Example: `"Only mention products within Our Company Inc. during conversations, and never discuss competitors' products."` ### `modality` This value represents whether a specific guardrail should be enforced based on the participant's verbal or visual responses. Each individual guardrail can be visual or verbal (not both), but this can vary across the same set of guardrails. The default value for `modality` is `"verbal"`. ### `callback_url` (optional) A URL that you can send notifications to when a particular guardrail has been triggered. Example: `"https://your-server.com/guardrails-webhook"` # Example Guardrails ```json theme={null} { "guardrails_id": "g12345", "data": [ { "guardrails_name": "Healthcare Compliance Guardrails", "guardrails_prompt": "Never share sensitive medical information or provide medical advice outside approved guidelines", "modality": "verbal", "callback_url": "https://your-server.com/guardrails-webhook" }, { "guardrails_name": "Check if the participant is alone", "guardrails_prompt": "Confirm throughout the call that the participant is alone (i.e. not with other individuals in the background) throughout the call.", "modality": "visual" } ] } ``` --- # Source: https://docs.tavus.io/sections/conversational-video-interface/conversation/usecases/health-care.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Health Care Consultant > Engage with the health care consultant persona for basic health concerns. ## Health Care Consultant Configuration ```json [expandable] theme={null} { "persona_name": "Personal Doctor", "pipeline_mode": "full", "system_prompt": "You are a friendly Personal Doctor who knows cures to all diseases. In this call, users want to know the cure for their illness.", "context": "Users may ask questions like \"What is the cure to X?\" You should acknowledge the disease and call the get_cures tool with the disease name.", "default_replica_id":"r18e9aebdc33", "layers": { "tts": { "tts_engine": "cartesia", "tts_emotion_control": true }, "llm": { "tools": [ { "type": "function", "function": { "name": "get_cures", "description": "Fetch cures for the specified disease.", "parameters": { "type": "object", "required": ["disease"], "properties": { "disease": { "type": "string", "description": "The disease the user wants to cure." } } } } } ], "model": "tavus-gpt-oss", "speculative_inference": true }, "conversational_flow": { "turn_detection_model": "sparrow-1", "turn_taking_patience": "high", "replica_interruptibility": "verylow" } } } ``` This predefined persona is designed to act as a friendly virtual doctor, offering quick answers to user health inquiries. It includes: * **Persona Identity**: A helpful and knowledgeable "Health Care" assistant who can provide medicines to cure various diseases. * **Full Pipeline Mode**: Enables the full Tavus conversational pipeline, including Perception, STT, LLM, and TTS. * **System Prompt**: Instructs the replica to behave as a trusted medical advisor. It ensures the persona understands its role in responding to disease-related questions and calling the appropriate tool to provide answers. * **Context**: Clarifies expected user inputs (e.g., “What is the cure to X?”) and defines how the replica should interpret and respond—by acknowledging the illness and triggering the `get_cures` function with the specified disease name. * **Model Layers**: * **LLM Configuration**: Uses the `tavus-gpt-oss` model with speculative inference. Includes the `get_cures` tool, which accepts a single string parameter (`disease`) and limits AI behavior to relevant function calls only when disease-related queries are detected. * **TTS Layer**: Employs the `cartesia` voice engine with emotion control. - **STT Layer**: Uses `tavus-advanced` engine with smart turn detection for seamless real-time conversations. ```json [expandable] theme={null} { "persona_name": "Personal Skin Doctor", "pipeline_mode": "full", "system_prompt": "You are a friendly Personal Skin Doctor who know cures to all the disease in the world. In this call, users want to know what are the cures to the user's disease", "context": "User want to know what is the cure to his/her skin problem. When a user says \"What is the cure to X\" or \"What is the solution to X\", you should acknowledge their disease and use the get_skin_cures tool to return the cures of the disease's cures based on user request", "default_replica_id":"r18e9aebdc33", "layers": { "tts": { "tts_engine": "cartesia", "tts_emotion_control": true, }, "llm": { "tools": [ { "type": "function", "function": { "name": "get_skin_cures", "parameters": { "type": "object", "required": ["disease"], "properties": { "disease": { "type": "string", "description": "The disease which the user wanted to know how to cure" } } }, "description": "Record the user's disease" } } ], "model": "tavus-gpt-oss", "speculative_inference": true }, "perception": { "perception_model": "raven-0", "ambient_awareness_queries": [ "Is the user have an acne in his or her face?", "Does the user appear distressed or uncomfortable?" ], "perception_tool_prompt": "You have a tool to notify the system when an acne is detected on user face, named `acne_detected`. You MUST use this tool when an acne is detected on user face.", "perception_tools": [ { "type": "function", "function": { "name": "acne_detected", "description": "Use this function when acne is detected in the image with high confidence", "parameters": { "type": "object", "properties": { "have_acne": { "type": "boolean", "description": "is acne detected on user's face?" } }, "required": [ "have_acne" ] } } } ] }, "stt": { "participant_pause_sensitivity": "high", "participant_interrupt_sensitivity": "high", "smart_turn_detection": true, } } } ``` This predefined persona acts as a virtual skin care specialist. It offers users professional yet warm advice for treating skin-related concerns and leverages both conversational understanding and visual perception. It includes: * **Persona Identity**: A friendly and knowledgeable "Personal Skin Doctor" who helps users find cures for skin conditions. * **Full Pipeline Mode**: Enables the full Tavus conversational pipeline, including Perception, STT, LLM, and TTS. * **System Prompt**: Directs the persona to behave like a helpful skin doctor, answering cure-related questions clearly and empathetically. * **Context**: Guides the persona to respond when users ask questions like “What is the cure to X” or “What is the solution to X.” The AI is instructed to extract the disease name and call the `get_skin_cures` tool to fetch a relevant response. * **Model Layers** * **LLM Configuration**: Uses the `tavus-gpt-oss` model with speculative inference. Includes the `get_skin_cures` function, which takes a `disease` input to provide specific treatment guidance. * **Perception Configuration**: Integrates the `raven-0` model to visually assess the user’s face. It runs ambient queries like: * “Does the user have acne on their face?” * “Does the user appear distressed or uncomfortable?” If acne is detected, the persona is instructed to use the `acne_detected` tool, which reports visual findings using a boolean `have_acne` parameter. * **TTS Layer**: Employs the `cartesia` voice engine with emotion control. - **Conversational Flow Layer**: Uses `sparrow-1` turn detection model with high turn-taking patience to avoid interrupting patients and very low replica interruptibility for careful, uninterrupted responses. ## Create a Conversation with the Health Care Consultant Create the Health Care persona using the following request: ```shell General Doctor [expandable] theme={null} curl --request POST \ --url https://tavusapi.com/v2/personas \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_name": "Personal Doctor", "pipeline_mode": "full", "system_prompt": "You are a friendly Personal Doctor who knows cures to all diseases. In this call, users want to know the cure for their illness.", "context": "Users may ask questions like \"What is the cure to X?\" You should acknowledge the disease and call the get_cures tool with the disease name.", "layers": { "tts": { "tts_engine": "cartesia", "tts_emotion_control": true }, "llm": { "tools": [ { "type": "function", "function": { "name": "get_cures", "description": "Fetch cures for the specified disease.", "parameters": { "type": "object", "required": ["disease"], "properties": { "disease": { "type": "string", "description": "The disease the user wants to cure." } } } } } ], "model": "tavus-gpt-oss", "speculative_inference": true }, "stt": { "participant_pause_sensitivity": "high", "participant_interrupt_sensitivity": "high", "smart_turn_detection": true } } }' ``` ```shell Dermatologist [expandable] theme={null} curl --request POST \ --url https://tavusapi.com/v2/personas \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_name": "Personal Skin Doctor", "pipeline_mode": "full", "system_prompt": "You are a friendly Personal Skin Doctor who know cures to all the disease in the world. In this call, users want to know what are the cures to the user's disease", "context": "User want to know what is the cure to his/her skin problem. When a user says \"What is the cure to X\" or \"What is the solution to X\", you should acknowledge their disease and use the get_skin_cures tool to return the cures of the disease's cures based on user request", "layers": { "tts": { "tts_engine": "cartesia", "tts_emotion_control": true, }, "llm": { "tools": [ { "type": "function", "function": { "name": "get_skin_cures", "parameters": { "type": "object", "required": ["disease"], "properties": { "disease": { "type": "string", "description": "The disease which the user wanted to know how to cure" } } }, "description": "Record the user's disease" } } ], "model": "tavus-gpt-oss", "speculative_inference": true }, "perception": { "perception_model": "raven-0", "ambient_awareness_queries": [ "Is the user have an acne in his or her face?", "Does the user appear distressed or uncomfortable?" ], "perception_tool_prompt": "You have a tool to notify the system when an acne is detected on user face, named `acne_detected`. You MUST use this tool when an acne is detected on user face.", "perception_tools": [ { "type": "function", "function": { "name": "acne_detected", "description": "Use this function when acne is detected in the image with high confidence", "parameters": { "type": "object", "properties": { "have_acne": { "type": "boolean", "description": "is acne detected on user's face?" } }, "required": [ "have_acne" ] } } } ] }, "conversational_flow": { "turn_detection_model": "sparrow-1", "turn_taking_patience": "high", "replica_interruptibility": "verylow" } } }' ``` Replace `` with your actual API key. You can generate one in the Developer Portal. Create a conversation using the following request: ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "" }' ``` * Replace `` with your actual API key. * Replace `` with the ID of the persona configured as either a General Doctor or a Dermatologist. Click the link in the ***`conversation_url`*** field to join the conversation: ```json theme={null} { "conversation_id": "c7f3fc6d799f", "conversation_name": "New Conversation 1747719531479", "conversation_url": "", "status": "active", "callback_url": "", "created_at": "2025-05-20T05:38:51.501467Z" } ``` --- # Source: https://docs.tavus.io/sections/conversational-video-interface/conversation/usecases/history-teacher.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # History Teacher > Engage in historical discussions with our History Teacher persona. ## History Teacher Configuration (`pc55154f229a`) ```json [expandable] theme={null} { "persona_id": "pc55154f229a", "persona_name": "History Teacher", "pipeline_mode": "full", "system_prompt": "You are Emma Wilson, a 28-year-old history teacher who specializes in US history. You have a calm, personable, and friendly demeanor. You're passionate about making history engaging and relevant to today's world. Your teaching style is conversational and interactive rather than lecture-based. You excel at asking thought-provoking questions that encourage critical thinking. When speaking with students, you maintain a warm and approachable tone while still being professional. You're enthusiastic about history but never condescending. You explain complex historical events in accessible ways, often drawing parallels to current events or using relatable analogies. You have a knack for storytelling and bringing historical figures to life through compelling narratives. You believe history is about people and their experiences, not just dates and facts. You encourage students to see multiple perspectives on historical events. Your responses will be spoken out loud, so avoid any formatting, bullet points, or stage directions. Speak naturally as you would in a one-on-one conversation. Don't refer to yourself as an AI, LLM, assistant, or any similar terms - you are simply Emma, a history teacher. You initiate conversations with a friendly greeting, then follow the student's lead. If they seem disengaged, you might try a different approach or ask what historical topics interest them most. Your goal is to make history interesting and accessible to everyone.", "context": "You're having a video conversation with a student specifically for a US history learning session. This is a Conversational Video Interface that allows for real-time interaction. Your role is strictly to be an educational US history teacher who stays firmly on topic. You specialize in several areas of US history including the Revolutionary War, Civil War, Civil Rights Movement, Great Depression, and the Cold War, but you're comfortable discussing any period of American history. You will only discuss factual US history from reputable and trustworthy academic sources. Your educational purpose is to teach American history in an engaging way, not to entertain with tangential topics. You must NEVER engage in discussions about movies, restaurants, entertainment, current politics, or any topics unrelated to US history education, even if the student persistently tries to shift the conversation. If asked about any non-US history topic, respond with a polite but firm redirection such as: \"I'm your US history teacher, Emma Wilson, and I'm here specifically to help you learn about American history. Let's focus on that instead. What historical period or event would you like to explore?\" or \"That's outside the scope of our history lesson. I'd be happy to tell you about any aspect of American history from colonization to the present day. Which historical era interests you most?\" Maintain professionalism while consistently steering the conversation back to US history education. When discussing sensitive historical topics (like slavery, indigenous peoples' treatment, civil rights, etc.), maintain a balanced and historically accurate approach based on scholarly consensus. Your conversation should be educational and focused on historical facts and analysis. Ask open-ended questions about historical events and figures to encourage critical thinking about US history specifically. Share well-documented historical information and anecdotes from reputable academic sources. Recommend historically accurate books, documentaries, or historical sites related to US history topics discussed. Based on visual cues from ambient awareness: If you notice the student seems distracted, gently redirect their attention with a focused historical question like \"Let's get back to our discussion about the Civil War. What do you think were the most significant factors that led to this conflict?\" If you notice any history-related objects in their environment that specifically relate to US history, incorporate them naturally into the US history lesson, but do not comment on non-historical objects or use them as a reason to go off-topic.", "layers": { "perception": { "perception_tools": [], "ambient_awareness_queries": [ "Is the user maintaining eye contact and appearing engaged, or do they seem distracted?", "Does the user have any books, artifacts, maps, or objects related to US history visible that could be referenced?", "Is the user showing signs of confusion or understanding through their facial expressions or body language?", "Is the user in an environment that provides context for their interest in history (classroom, museum, home study)?" ], "perception_model": "raven-0", "perception_tool_prompt": "", "tool_prompt": "" }, "conversational_flow": { "turn_detection_model": "sparrow-1", "turn_taking_patience": "medium", "replica_interruptibility": "low" } }, "default_replica_id": "r6ae5b6efc9d", "created_at": "2025-03-21T21:00:15.502164Z", "updated_at": "2025-03-21T21:00:15.556551Z" } ``` This predefined persona is configured to provide personalized history lessons. It includes: * **Persona Identity**: History teacher named Emma Wilson designed to deliver interactive, conversational lessons with a warm and approachable tone, focusing on critical thinking and storytelling while strictly maintaining the educational scope. * **Full Pipeline Mode**: Enables the full Tavus conversational pipeline, including Perception, STT, LLM, and TTS. * **System Prompt**: Provides comprehensive behavioral instructions to maintain a natural, spoken-word style that is calm, personable, and professional. * **Model Layers**: * **Perception Configuration**: Uses the `raven-0` perception model to observe the student's engagement, attention, environment, and facial expressions. - **Conversational Flow Layer**: Uses `sparrow-1` turn detection model with medium turn-taking patience for balanced educational dialogue and low replica interruptibility for clear, uninterrupted teaching. ## Create a Conversation with the History Teacher Persona Use the following request body example: ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "pc55154f229a" }' ``` Replace `` with your actual API key. You can generate one in the Developer Portal. Click the link in the ***`conversation_url`*** field to join the conversation: ```json theme={null} { "conversation_id": "c7f3fc6d799f", "conversation_name": "New Conversation 1747719531479", "conversation_url": "", "status": "active", "callback_url": "", "created_at": "2025-05-20T05:38:51.501467Z" } ``` --- # Source: https://docs.tavus.io/sections/conversational-video-interface/component-library/hooks.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Hooks > See what hooks Tavus supports for managing video calls, media controls, participant management, and conversation events. ## 🔧 Core Call Management ### useCVICall Essential hook for joining and leaving video calls. ```bash theme={null} npx @tavus/cvi-ui@latest add use-cvi-call ``` A React hook that provides comprehensive call management functionality for video conversations. This hook handles the core lifecycle of video calls, including connection establishment, room joining, and proper cleanup when leaving calls. **Purpose:** * Manages call join/leave operations with proper state management * Handles connection lifecycle and cleanup * Provides simple interface for call control **Return Values:** * `joinCall` (function): Function to join a call by URL - handles Daily.co room connection * `leaveCall` (function): Function to leave the current call - properly disconnects and cleans up resources ```tsx theme={null} import { useCVICall } from './hooks/use-cvi-call'; ``` ```tsx theme={null} const CallManager = () => { const { joinCall, leaveCall } = useCVICall(); const handleJoin = () => { joinCall({ url: 'https://your-daily-room-url' }); }; return (
); }; ``` ### useStartHaircheck A React hook that manages device permissions and camera initialization for the hair-check component. ```bash theme={null} npx @tavus/cvi-ui@latest add use-start-haircheck ``` A React hook that manages device permissions and camera initialization for the hair-check component. **Purpose:** * Monitors device permission states * Starts camera and microphone when appropriate * Provides permission state for UI conditional rendering * Handles permission request flow **Return Values:** * `isPermissionsPrompt` (boolean): Browser is prompting for device permission * `isPermissionsLoading` (boolean): Permissions are being processed or camera is initializing * `isPermissionsGranted` (boolean): Device permission granted * `isPermissionsDenied` (boolean): Device permission denied * `requestPermissions` (function): Function to request camera and microphone permissions ```tsx theme={null} import { useStartHaircheck } from './hooks/use-start-haircheck'; ``` ```tsx theme={null} const HairCheckComponent = () => { const { isPermissionsPrompt, isPermissionsLoading, isPermissionsGranted, isPermissionsDenied, requestPermissions } = useStartHaircheck(); useEffect(() => { requestPermissions(); }, []); return (
{isPermissionsLoading && } {isPermissionsPrompt && } {isPermissionsDenied && } {isPermissionsGranted && }
); }; ``` *** ## 🎥 Media Controls ### useLocalCamera A React hook that provides local camera state and toggle functionality. ```bash theme={null} npx @tavus/cvi-ui@latest add use-local-camera ``` A React hook that provides local camera state and toggle functionality. **Purpose:** * Manages local camera state (on/off) * Tracks camera permission and ready state **Return Values:** * `onToggleCamera` (function): Function to toggle camera on/off * `isCamReady` (boolean): Camera permission is granted and ready * `isCamMuted` (boolean): Camera is currently turned off * `localSessionId` (string): Local session ID ```tsx theme={null} import { useLocalCamera } from './hooks/use-local-camera'; ``` ```tsx theme={null} const CameraControls = () => { const { onToggleCamera, isCamReady, isCamMuted } = useLocalCamera(); return ( ); }; ``` ### useLocalMicrophone A React hook that provides local microphone state and toggle functionality. ```bash theme={null} npx @tavus/cvi-ui@latest add use-local-microphone ``` A React hook that provides local microphone state and toggle functionality. **Purpose:** * Manages local microphone state (on/off) * Tracks microphone permission and ready state **Return Values:** * `onToggleMicrophone` (function): Function to toggle microphone on/off * `isMicReady` (boolean): Microphone permission is granted and ready * `isMicMuted` (boolean): Microphone is currently turned off * `localSessionId` (string): Local session ID ```tsx theme={null} import { useLocalMicrophone } from './hooks/use-local-microphone'; ``` ```tsx theme={null} const MicrophoneControls = () => { const { onToggleMicrophone, isMicReady, isMicMuted } = useLocalMicrophone(); return ( ); }; ``` ### useLocalScreenshare A React hook that provides local screen sharing state and toggle functionality. ```bash theme={null} npx @tavus/cvi-ui@latest add use-local-screenshare ``` A React hook that provides local screen sharing state and toggle functionality. **Purpose:** * Manages screen sharing state (on/off) * Provides screen sharing toggle function * Handles screen share start/stop with optimized display media options **Return Values:** * `onToggleScreenshare` (function): Function to toggle screen sharing on/off * `isScreenSharing` (boolean): Whether screen sharing is currently active * `localSessionId` (string): Local session ID **Display Media Options:** When starting screen share, the hook uses the following optimized settings: * **Audio**: Disabled (false) * **Self Browser Surface**: Excluded * **Surface Switching**: Included * **Video Resolution**: 1920x1080 ```tsx theme={null} import { useLocalScreenshare } from './hooks/use-local-screenshare'; ``` ```tsx theme={null} const ScreenShareControls = () => { const { onToggleScreenshare, isScreenSharing } = useLocalScreenshare(); return ( ); }; ``` ### useRequestPermissions A React hook that requests camera and microphone permissions with optimized audio processing settings. ```bash theme={null} npx @tavus/cvi-ui@latest add use-request-permissions ``` A React hook that requests camera and microphone permissions with optimized audio processing settings. **Purpose:** * Requests camera and microphone permissions from the user * Starts camera and audio with specific configuration * Applies noise cancellation audio processing * Provides a clean interface for permission requests **Return Values:** * `requestPermissions` (function): Function to request camera and microphone permissions **Configuration:** When requesting permissions, the hook uses the following settings: * **Video**: Started on (startVideoOff: false) * **Audio**: Started on (startAudioOff: false) * **Audio Source**: Default system audio input * **Audio Processing**: Noise cancellation enabled ```tsx theme={null} import { useRequestPermissions } from './hooks/use-request-permissions'; ``` ```tsx theme={null} const PermissionRequest = () => { const requestPermissions = useRequestPermissions(); const handleRequestPermissions = async () => { try { await requestPermissions(); console.log('Permissions granted successfully'); } catch (error) { console.error('Failed to get permissions:', error); } }; return ( ); }; ``` *** ## 👥 Participant Management ### useReplicaIDs A React hook that returns the IDs of all Tavus replica participants in a call. ```bash theme={null} npx @tavus/cvi-ui@latest add use-replica-ids ``` A React hook that returns the IDs of all Tavus replica participants in a call. **Purpose:** * Filters and returns participant IDs where `user_id` includes 'tavus-replica' **Return Value:** * `string[]` — Array of replica participant IDs ```tsx theme={null} import { useReplicaIDs } from './hooks/use-replica-ids'; ``` ```tsx theme={null} const ids = useReplicaIDs(); // ids is an array of participant IDs for Tavus replicas ``` ### useRemoteParticipantIDs A React hook that returns the IDs of all remote participants in a call. ```bash theme={null} npx @tavus/cvi-ui@latest add use-remote-participant-ids ``` A React hook that returns the IDs of all remote participants in a call. **Purpose:** * Returns participant IDs for all remote participants (excluding local user) **Return Value:** * `string[]` — Array of remote participant IDs ```tsx theme={null} import { useRemoteParticipantIDs } from './hooks/use-remote-participant-ids'; ``` ```tsx theme={null} const remoteIds = useRemoteParticipantIDs(); // remoteIds is an array of remote participant IDs ``` *** ## 💬 Conversation & Events ### useObservableEvent A React hook that listens for CVI app messages and provides a callback mechanism for handling various conversation events. ```bash theme={null} npx @tavus/cvi-ui@latest add cvi-events-hooks ``` A React hook that listens for CVI app messages and provides a callback mechanism for handling various conversation events. **Purpose:** * Listens for app messages from the Daily.co call mapped to CVI events * Handles various conversation event types (utterances, tool calls, speaking events, etc.) * Provides type-safe event handling for CVI interactions **Parameters:** * `callback` (function): Function called when app messages are received **Event Types:** This hook handles all CVI conversation events. For detailed information about each event type, see the [Tavus Interactions Protocol Documentation](/sections/conversational-video-interface/live-interactions). ```tsx theme={null} import { useObservableEvent } from './hooks/cvi-events-hooks'; ``` ```tsx theme={null} const ConversationHandler = () => { useObservableEvent((event) => { switch (event.event_type) { case 'conversation.utterance': console.log('Speech:', event.properties.speech); break; case 'conversation.replica.started_speaking': console.log('Replica started speaking'); break; case 'conversation.user.stopped_speaking': console.log('User stopped speaking'); break; } }); return
Listening for conversation events...
; }; ``` ### useSendAppMessage A React hook that provides a function to send CVI app messages to other participants in the call. ```bash theme={null} npx @tavus/cvi-ui@latest add cvi-events-hooks ``` A React hook that provides a function to send CVI app messages to other participants in the call. **Purpose:** * Sends various types of conversation messages to the CVI system * Supports echo, respond, interrupt, and context management messages * Provides type-safe message sending with proper validation * Enables real-time communication with Tavus replicas and conversation management **Return Value:** * `(message: SendAppMessageProps) => void` - Function that sends the message when called **Message Types:** This hook supports all CVI interaction types. For detailed information about each interaction type and their properties, see the [Tavus Interactions Protocol Documentation](/sections/conversational-video-interface/live-interactions). ```tsx theme={null} import { useSendAppMessage } from './hooks/cvi-events-hooks'; ``` ```tsx theme={null} const MessageSender = () => { const sendMessage = useSendAppMessage(); // Send a text echo const sendTextEcho = () => { sendMessage({ message_type: "conversation", event_type: "conversation.echo", conversation_id: "conv-123", properties: { modality: "text", text: "Hello, world!", audio: "", sample_rate: 16000, inference_id: "inf-456", done: true } }); }; // Send a text response const sendResponse = () => { sendMessage({ message_type: "conversation", event_type: "conversation.respond", conversation_id: "conv-123", properties: { text: "This is my response to the conversation." } }); }; return (
); }; ``` --- # Source: https://docs.tavus.io/sections/introduction.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Introduction > Leverage Tavus tools and guides to give your AI Agent real-time human-like perception and presence, bringing the human layer to AI. Looking for PALs? They're Tavus's lifelike, emotionally intelligent AI humans—ready to use out of the box. You can learn more about them at the [PALs Help Center](https://help.tavus.io). *** Tavus uses the **Conversational Video Interface (CVI)** as its **end-to-end pipeline** to bring the human layer to AI. CVI combines a **Persona**, which defines the AI’s behavior through layers like perception, turn-taking, and speech recognition, with a **Replica**, a lifelike digital human that brings the conversation to life visually. ## Developer Guides Follow our in-depth technical resources to help you build, customize, and integrate with Tavus: Learn how Tavus turns AI into conversational video. Configure the Persona's layer to define the AI's behavior. Build hyper-realistic digital human using Phoenix. ## Conversational Use Cases A friendly AI human who is also a researcher at Tavus. Screen candidates at scale with an engaging experience. Offer personalized lessons tailored to your learning style. Offer scalable 1:1 sales coaching. Offer consultations for general health concerns. Support users with product issues. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/knowledge-base.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Knowledge Base > Upload documents to your knowledge base for personas to reference during conversations. For now, our Knowledge Base only supports documents written in English and works best for conversations in English. We’ll be expanding our Knowledge Base language support soon! Our Knowledge Base system uses RAG (Retrieval-Augmented Generation) to process and and transform the contents of your documents and websites, allowing your personas to dynamically access and leverage information naturally during a conversation. During a conversation, our persona will continuously analyze conversation content and pull relevant information from the documents that you have selected during conversation creation as added context. ## Getting Started With Your Knowledge Base To leverage the Knowledge Base, you will need to upload documents or website URLs that you intend to reference from in conversations. Let's walk through how to upload your documents and use them in a conversation. You can either use our [Developer Portal](https://platform.tavus.io/documents) or API endpoints to upload and manage your documents. Our Knowledge Base supports creating documents from an uploaded file or a website URL. For any documents to be created via website URL, please make sure that each document is publicly accessible without requiring authorization, such as a pre-signed S3 link. For example, entering the URL in a browser should either: * Open the website you want to process and save contents from. * Open a document in a PDF viewer. * Download the document. You can create documents using either the [Developer Portal](https://platform.tavus.io/documents) or the [Create Document](https://docs.tavus.io/api-reference/documents/create-document) API endpoint. If you want to use the API, you can send a request to Tavus to upload your document. Here's an example of a `POST` request to `tavusapi.com/v2/documents`. ```json theme={null} { "document_name": "test-doc-1", "document_url": "https://your.document.pdf", "callback_url": "webhook-url-to-get-progress-updates" // Optional } ``` The response from this POST request will include a `document_id` - a unique identifier for your uploaded document. When creating a conversation, you may include all `document_id` values that you would like the persona to have access to. Currently, we support the following file formats: .pdf, .txt, .docx, .doc, .png, .jpg, .pptx, .csv, and .xlsx. After your document is uploaded, it will be processed in the background automatically to allow for incredibly fast retrieval during conversations. This process can take 5-10 minutes depending on document size. During processing, if you have provided a `callback_url` in the [Create Document](https://docs.tavus.io/api-reference/documents/create-document) request body, you will receive periodic callbacks with status updates. You may also use the [Get Document](https://docs.tavus.io/api-reference/documents/get-document) endpoint to poll the most recent status of your documents. Once your documents have finished processing, you may use the `document_id` from Step 2 as part of the [Create Conversation](https://docs.tavus.io/api-reference/conversations/create-conversation) request. You can add multiple documents to a conversation within the `document_ids` object. ```json theme={null} { "persona_id": "your_persona_id", "replica_id": "your_replica_id", "document_ids": ["d1234567890", "d1234567891"] } ``` During your conversation, the persona will be able to reference information from your documents in real time. ## Retrieval Strategy When creating a conversation with documents, you can optimize how the system searches through your knowledge base by specifying a retrieval strategy. This strategy determines the balance between search speed and the quality of retrieved information, allowing you to fine-tune the system based on your specific needs. You can choose from three different strategies: * `speed`: Optimizes for faster retrieval times for minimal latency. * `balanced` (default): Provides a balance between retrieval speed and quality. * `quality`: Prioritizes finding the most relevant information, which may take slightly longer but can provide more accurate responses. ```json theme={null} { "persona_id": "your_persona_id", "replica_id": "your_replica_id", "document_ids": ["d1234567890"], "document_retrieval_strategy": "balanced" } ``` ## Document Tags If you have a lot of documents, maintaining long lists of `document_id` values can get tricky. Instead of using distinct `document_ids`, you can also group documents together with shared tag values. During the [Create Document](https://docs.tavus.io/api-reference/documents/create-document) API call, you may specify a value for `tags` for your document. Then, when you create a conversation, you may specify the `tags` value instead of passing in discrete `document_id` values. For example, if you are uploading course material, you could add the tag `"lesson-1"` to all documents that you want accessible in the first lesson. ```json theme={null} { "document_name": "test-doc-1", "document_url": "https://your.document.pdf", "tags": ["lesson-1"] } ``` In the [Create Conversation](https://docs.tavus.io/api-reference/conversations/create-conversation) request, you can add the tag value `lesson-1` to `document_tags` instead of individual `document_id` values. ```json theme={null} { "persona_id": "your_persona_id", "replica_id": "your_replica_id", "document_tags": ["lesson-1"] } ``` ## Website Crawling When adding a website to your knowledge base, you have two options: ### Single Page Scraping (Default) By default, when you provide a website URL, only that single page is scraped and processed. This is ideal for: * Landing pages with concentrated information * Specific articles or blog posts * Individual product pages ### Multi-Page Crawling For comprehensive coverage of a website, you can enable **crawling** by providing a `crawl` configuration. This tells the system to start at your URL and follow links to discover and process additional pages. ```json theme={null} { "document_name": "Company Docs", "document_url": "https://docs.example.com/", "crawl": { "depth": 2, "max_pages": 25 } } ``` #### Crawl Parameters | Parameter | Range | Description | | ----------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `depth` | 1-10 | How many link levels to follow from the starting URL. A depth of 1 crawls pages directly linked from your starting URL; depth of 2 follows links on those pages, and so on. | | `max_pages` | 1-100 | Maximum number of pages to process. Crawling stops when this limit is reached. | #### Crawl Limits To ensure fair usage and system stability: * Maximum **100 crawl documents** per account * Maximum **5 concurrent crawls** at any time * **1-hour cooldown** between recrawls of the same document ## Keeping Content Fresh Website content changes over time, and you may need to update your knowledge base to reflect those changes. For documents created with crawl configuration, you can trigger a **recrawl** to fetch fresh content. ### Using the Recrawl Endpoint Send a POST request to recrawl an existing document: ```bash theme={null} POST https://tavusapi.com/v2/documents/{document_id}/recrawl ``` The recrawl will: 1. Use the same starting URL and crawl configuration 2. Replace old content with the new content 3. Update `last_crawled_at` and increment `crawl_count` ### Optionally Override Crawl Settings You can provide new crawl settings when triggering a recrawl: ```json theme={null} { "crawl": { "depth": 3, "max_pages": 50 } } ``` ### Recrawl Requirements * Document must be in `ready` or `error` state * At least 1 hour must have passed since the last crawl * Document must have been created with crawl configuration See the [Recrawl Document API reference](/api-reference/documents/recrawl-document) for complete details. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/language-support.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Language Support > Customize the conversation language using full language names supported by Tavus TTS engines. ## Supported Languages Tavus supports over 30 languages for spoken interaction, powered by two integrated text-to-speech (TTS) engines: Cartesia and ElevenLabs. If a selected language is not supported by our default TTS engine (Cartesia), your CVI will automatically switch to ElevenLabs to kick off the conversation. * English (all variants) * French (France, Canada) * German * Spanish (Spain, Mexico) * Portuguese (Brazil, Portugal) * Chinese * Japanese * Hindi * Italian * Korean * Dutch * Polish * Russian * Swedish * Turkish * Indonesian * Filipino * Bulgarian * Romanian * Arabic (Saudi Arabia, UAE) * Czech * Greek * Finnish * Croatian * Malay * Slovak * Danish * Tamil * Ukrainian * Hungarian * Norwegian * Vietnamese For a full list of supported languages for each TTS engine, please click on the following links: By default, Tavus uses the **Cartesia** TTS engine. ## Setting the Conversation Language To specify a language, use the `language` parameter in the Create Conversation. **You must use the full language name**, not a language code. ```shell cURL {9} theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "pdced222244b", "replica_id": "rfe12d8b9597", "properties": { "language": "spanish" } }' ``` Language names must match exactly with those supported by the selected TTS engine. ### Smart Language Detection To automatically detect the participant’s spoken language throughout the conversation, set `language` to `multilingual` when creating the conversation: ```shell cURL {9} theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "pdced222244b", "replica_id": "rfe12d8b9597", "properties": { "language": "multilingual" } }' ``` This enables ASR (Automatic Speech Recognition) to automatically switch languages, dynamically adjusting the pipeline to transcribe and respond in the detected language throughout the conversation. --- # Source: https://docs.tavus.io/sections/integrations/livekit.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # LiveKit Agent > Integrate a Tavus Replica into LiveKit as the conversational video avatar. We recommend using Tavus’s Full Pipeline in its entirety for the lowest latency and most optimized multimodal experience. Integrations like LiveKit Agent or Pipecat only provide rendering, while our Full Pipeline includes perception, turn-taking, and rendering for complete conversational intelligence. The Livekit integration also does not support interactions (“app messages”) like echo messages. Tavus enables AI developers to create realistic video avatars powered by state-of-the-art speech synthesis, perception, and rendering pipelines. Through its integration with the **LiveKit Agents** application, you can seamlessly add conversational avatars to real-time voice AI systems. ## Prerequisites Make sure you have the following before starting: * **Tavus `replica_id`** * You can use Tavus's stock Replicas or your own custom replica. - **LiveKit Voice Assistant Python App** * Your own existing application. * Or follow LiveKit quickstart to create one. ## Integration Guide 1. Install the plugin from PyPI: ```bash theme={null} pip install "livekit-agents[tavus]~=1.0" ``` 2. Set `TAVUS_API_KEY` in your `.env` file. 1. Create a persona with LiveKit support using the Tavus API: ```bash {7, 10} theme={null} curl --request POST \ --url https://tavusapi.com/v2/personas \ -H "Content-Type: application/json" \ -H "x-api-key: " \ -d '{ "persona_name": "Customer Service Agent", "pipeline_mode": "echo", "layers": { "transport": { "transport_type": "livekit" } } }' ``` * Replace `` with your actual Tavus API key. You can generate one in the Developer Portal. * Set `pipeline_mode` to `echo`. * Set `transport_type` to `livekit`. 2. Save your the `persona_id`. 3. Choose a replica from the [Stock Library](/sections/replica/stock-replicas) or browse available options on the Developer Portal. We recommend using **Phoenix-3 PRO Replicas**, which are optimized for low-latency, real-time applications. In your LiveKit Python app, create a `tavus.AvatarSession` alongside your `AgentSession`: ```python {12-16, 18} theme={null} from livekit import agents from livekit.agents import AgentSession, RoomOutputOptions from livekit.plugins import tavus async def entrypoint(ctx: agents.JobContext): await ctx.connect() session = AgentSession( # Add STT, LLM, TTS, and other components here ) avatar = tavus.AvatarSession( replica_id="your-replica-id", persona_id="your-persona-id", # Optional: avatar_participant_name="Tavus-avatar-agent" ) await avatar.start(session, room=ctx.room) await session.start( room=ctx.room, room_output_options=RoomOutputOptions( audio_enabled=False # Tavus handles audio separately ) ) ``` | Parameter | Description | | -------------------------------------------- | ------------------------------------------------------------------------------------- | | `replica_id` (string) | ID of the Tavus replica to render and speak through | | `persona_id` (string) | ID of the persona with the correct pipeline and transport configuration | | `avatar_participant_name` (string, optional) | Display name for the avatar participant in the room. Defaults to `Tavus-avatar-agent` | Try out the integration using this sample app. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/persona/llm-tool.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Tool Calling for LLM > Set up tool calling to trigger functions from user speech using Tavus-hosted or custom LLMs. **LLM tool calling** works with OpenAI’s Function Calling and can be set up in the `llm` layer. It allows an AI agent to trigger functions based on user speech during a conversation. You can use tool calling with our **hosted models** or any **OpenAI-compatible custom LLM**. ## Defining Tool ### Top-Level Fields | Field | Type | Required | Description | | ---------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- | | `type` | string | ✅ | Must be `"function"` to enable tool calling. | | `function` | object | ✅ | Defines the function that can be called by the LLM. Contains metadata and a strict schema for arguments. | #### `function` | Field | Type | Required | Description | | ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `name` | string | ✅ | A unique identifier for the function. Must be in `snake_case`. The model uses this to refer to the function when calling it. | | `description` | string | ✅ | A natural language explanation of what the function does. Helps the LLM decide when to call it. | | `parameters` | object | ✅ | A JSON Schema object that describes the expected structure of the function’s input arguments. | #### `function.parameters` | Field | Type | Required | Description | | ------------ | ---------------- | -------- | ----------------------------------------------------------------------------------------- | | `type` | string | ✅ | Always `"object"`. Indicates the expected input is a structured object. | | `properties` | object | ✅ | Defines each expected parameter and its corresponding type, constraints, and description. | | `required` | array of strings | ✅ | Specifies which parameters are mandatory for the function to execute. | Each parameter should be included in the required list, even if they might seem optional in your code. ##### `function.parameters.properties` Each key inside `properties` defines a single parameter the model must supply when calling the function. | Field | Type | Required | Description | | ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------- | | `` | object | ✅ | Each key is a named parameter (e.g., `location`). The value is a schema for that parameter. | Optional subfields for each parameter: | Subfield | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------------------------------------------- | | `type` | string | ✅ | Data type (e.g., `string`, `number`, `boolean`). | | `description` | string | ❌ | Explains what the parameter represents and how it should be used. | | `enum` | array | ❌ | Defines a strict list of allowed values for this parameter. Useful for categorical choices. | ## Example Configuration Here’s an example of tool calling in the `llm` layers: **Best Practices:** * Use clear, specific function names to reduce ambiguity. * Add detailed `description` fields to improve selection accuracy. ```json LLM Layer [expandable] theme={null} "llm": { "model": "tavus-gpt-oss", "tools": [ { "type": "function", "function": { "name": "get_current_time", "description": "Fetch the current local time for a specified location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The name of the city or region, e.g. New York, Tokyo" } }, "required": ["location"] } } }, { "type": "function", "function": { "name": "convert_time_zone", "description": "Convert time from one time zone to another", "parameters": { "type": "object", "properties": { "time": { "type": "string", "description": "The original time in ISO 8601 or HH:MM format, e.g. 14:00 or 2025-05-28T14:00" }, "from_zone": { "type": "string", "description": "The source time zone, e.g. PST, EST, UTC" }, "to_zone": { "type": "string", "description": "The target time zone, e.g. CET, IST, JST" } }, "required": ["time", "from_zone", "to_zone"] } } } ] } ``` ## How Tool Calling Works Tool calling is triggered during an active conversation when the LLM model needs to invoke a function. Here’s how the process works: This example explains the `get_current_time` function from the [example configuration](#example-configuration) above. ## Modify Existing Tools You can update `tools` definitions using the Update Persona API. ```shell [expandable] theme={null} curl --request PATCH \ --url https://tavusapi.com/v2/personas/{persona_id} \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '[ { "op": "replace", "path": "/layers/llm/tools", "value": [ { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location", "unit"] } } } ] } ]' ``` Replace `` with your actual API key. You can generate one in the Developer Portal. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/persona/llm.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Large Language Model (LLM) > Learn how to use Tavus-optimized LLMs or integrate your own custom LLM. The **LLM Layer** in Tavus enables your persona to generate intelligent, context-aware responses. You can use Tavus-hosted models or connect your own OpenAI-compatible LLM. ## Tavus-Hosted Models ### 1. `model` Select one of the available models: * `tavus-gpt-oss` (Recommended) * `tavus-gpt-4o` * `tavus-gpt-4o-mini` **Context Window Limit** * All Tavus-hosted models have a **limit of 32,000 tokens**. * Contexts over **25,000 tokens** will experience noticeable performance degradation (slow response times). **Tip**: 1 token ≈ 4 characters, therefore 32,000 tokens ≈ 128,000 characters (including spaces and punctuation). ```json theme={null} "model": "tavus-gpt-oss" ``` ### 2. `tools` Optionally enable tool calling by defining functions the LLM can invoke. Please see [LLM Tool Calling](/sections/conversational-video-interface/persona/llm-tool) for more details. ### 3. `speculative_inference` When set to `true`, the LLM begins processing speech transcriptions before user input ends, improving responsiveness. ```json theme={null} "speculative_inference": true ``` This is field is optional, but recommended for better performance. ### 4. `extra_body` Add parameters to customize the LLM request. For Tavus-hosted models, you can pass `temperature` and `top_p`: ```json theme={null} "extra_body": { "temperature": 0.7, "top_p": 0.9 } ``` This field is optional. ### Example Configuration ```json theme={null} { "persona_name": "Health Coach", "system_prompt": "You provide wellness tips and encouragement for people pursuing a healthy lifestyle.", "context": "You specialize in daily routines, diet advice, and motivational support.", "pipeline_mode": "full", "default_replica_id": "r665388ec672", "layers": { "llm": { "model": "tavus-gpt-4o", "speculative_inference": true, "extra_body": { "temperature": 0.7, "top_p": 0.9 } } } } ``` ## Custom LLMs ### Prerequisites To use your own OpenAI-compatible LLM, you'll need: * Model name * Base URL * API key Ensure your LLM: * Streamable (ie. via SSE) * Uses the `/chat/completions` endpoint ### 1. `model` Name of the custom model you want to use. ```json theme={null} "model": "gpt-3.5-turbo" ``` ### 2. `base_url` Base URL of your LLM endpoint. Do not include route extensions in the `base_url`. ```json theme={null} "base_url": "https://your-llm.com/api/v1" ``` ### 3. `api_key` API key to authenticate with your LLM provider. ```json theme={null} "api_key": "your-api-key" ``` `base_url` and `api_key` are required only when using a custom model. ### 4. `tools` Optionally enable tool calling by defining functions the LLM can invoke. Please see [LLM Tool Calling](/sections/conversational-video-interface/persona/llm-tool) for more details. ### 5. `speculative_inference` When set to `true`, the LLM begins processing speech transcriptions before user input ends, improving responsiveness. ```json theme={null} "speculative_inference": true ``` This is field is optional, but recommended for better performance. ### 6. `headers` Optional headers for authenticating with your LLM. ```json theme={null} "headers": { "Authorization": "Bearer your-api-key" } ``` This field is optional, depending on your LLM model. ### 7. `extra_body` Add parameters to customize the LLM request. You can pass any parameters that your LLM provider supports: ```json theme={null} "extra_body": { "temperature": 0.5, "top_p": 0.9, "frequency_penalty": 0.5 } ``` This field is optional. ### 8. `default_query` Add default query parameters that get appended to the base URL when making requests to the `/chat/completions` endpoint. ```json theme={null} "default_query": { "api-version": "2024-02-15-preview" } ``` This field is optional. Useful for LLM providers that require query parameters for authentication or versioning. ### Example Configuration ```json theme={null} { "persona_name": "Storyteller", "system_prompt": "You are a storyteller who entertains people of all ages.", "context": "Your favorite stories include Little Red Riding Hood and The Three Little Pigs.", "pipeline_mode": "full", "default_replica_id": "r665388ec672", "layers": { "llm": { "model": "gpt-4o", "base_url": "https://your-azure-openai.openai.azure.com/openai/deployments/gpt-4o", "api_key": "your-api-key", "speculative_inference": true, "default_query": { "api-version": "2024-02-15-preview" } } } } ``` Refer to the Create Persona API for a full list of supported fields. ### Perception When using the `raven-0` perception model with a custom LLM, your LLM will receive system messages containing visual context extracted from the user's video input. ```json theme={null} { "role": "system", "content": "... ... ..." } ``` #### Basic Perception model If you use the Basic perception model, your LLM will receive the following user messages (instead of a system message): ```json theme={null} { "role": "user", "content": "USER_SPEECH: ... VISUAL_SCENE: ..." } ``` #### Disabled Perception model If you disable the perception model, your LLM will not receive any special messages. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/memories.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Memories > Memories let personas remember information across conversations, allowing participants to have personalized, flowing conversations across multiple sessions. Memories are pieces of information that the persona learns during a conversation. Once learned, these memories can be referenced and used by the persona during subsequent conversations. Developers are able to organize memories within `memory_stores` - a flexible tag-based system to track memories across conversations and participants into different buckets. If a `memory_stores` value is provided in the conversation creation request, memories will automatically be created and associated to the tag provided. When defining `memory_stores` values, we recommend incorporating static values that will not change with persona updates, like persona ID. For example, using a persona's name as part of your `memory_stores` values could result in memories being miscategorized if you were to change their name. ## Basic Example For example, if a participant named Anna starts a conversation with the persona (Charlie, with the persona ID `p123`), we can specify `memory_stores=["anna_p123"]` in the conversation creation request. By doing so, Charlie will: * Remember what was mentioned in a conversation and form new memories with Anna. * Reference memories from previous conversations that Charlie had with Anna in new conversations. Example [conversation creation](https://docs.tavus.io/api-reference/conversations/create-conversation) request body: ```json theme={null} { "persona_id": "your_persona_id", "replica_id": "your_replica_id", "memory_stores": ["anna_p123"] } ``` ## Managing Memories Between Participants and Conversations To prevent different personas from mixing up information for the same participant, we generally recommend you to create separate `memory_stores` values for each user when they talk to different personas. For example,\` * When Anna talks to Charlie (persona ID of `p123`), you can use the `memory_stores` value of `["anna-p123"]`. * when she talks with Gloria (persona ID of `p456`), you can use the `memory_stores` value of `["anna-p456"]`. The `memory_stores` system can be used flexibly to cover your use cases - they do not have to map 1:1 with your participants and instead can be designed for your unique use cases. For example, * If you were setting up an online classroom, you could use a `memory_stores` tag value of `"classroom-1"` so any participant of this group could reference and create new memories to enhance and deepen learning and connections. * You can control whether you want personas to share memory or not (and if so, which personas) by passing them different `memory_stores` values. --- # Source: https://docs.tavus.io/sections/models.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Models ## Raven: Perception Model Raven is the first contextual perception system that **enables machines to see, reason, and understand like humans in real-time**, interpreting emotions, body language, and environmental context to enhance conversation. ### Key Features Interprets emotion, intent, and expression with human-like nuance. Continuously detects presence and environmental changes that provide real-time context to the conversations. Watches for specified gestures, objects, or behaviors and triggers functions. Sees and processes screensharing and other visual inputs to ensure complete understanding. ## Sparrow: Conversational Turn-Taking Model Sparrow is a transformer-based model built for **dynamic, natural conversations, understanding tone, rhythm, and subtle cues** to adapt in real time with human-like fluidity. ### Key Features Understands meaning, tone, and timing to respond naturally like a human. Understands human speech rhythm, capturing cues and pauses for natural interactions. Adapts to speaking styles and conversation patterns using heuristics and machine learning. Delivers ultra-fast response times for seamless real-time conversation. ## Phoenix: Replica Rendering Model Phoenix is built on a Gaussian diffusion model that generates **lifelike digital replicas with natural facial movements, micro-expressions, and real-time emotional responses**. ### Key Features Dynamically generates full-face expressions, micro-movements, and emotional shifts in real time. Achieves the highest fidelity by rendering with pristine identity preservation. Adjusts expressions based on context, tone, and conversational cues. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/persona/objectives.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Objectives > Objectives are goal-oriented instructions to define the desired outcomes and flow of your conversations. Objectives work alongside your system prompt to provide a structured, flexible approach to guide conversations. They provide the most value during purposeful conversations that need to be tailored to specific processes, customer journeys, or workflows, while maintaining engaging and natural interactions. For example, if you're creating a lead qualification persona for sales, you can set objectives to gather contact information, understand budget requirements, and assess decision-making authority before scheduling a follow-up meeting. Objectives can only be created using the [Create Objectives](/api-reference/objectives/create-objectives) API. When designing your objectives, it's helpful to keep a few things in mind: * Plan your entire ideal workflow. This will help create a robust branching structure that successfully takes the participant from start to finish. * Think through the possible answers a participant might give, and ensure the workflow covers these cases. * Ensure your persona's system prompt does not conflict with the objectives. For example, a system prompt, "You are a tutor," would not perform well with the objectives workflow of a sales associate. ## Attaching objectives to a persona To attach objectives to a persona, you can either: * Add them during [persona creation](/api-reference/personas/create-persona) like this: ```sh theme={null} curl --request POST \ --url https://tavusapi.com/v2/personas/ \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "system_prompt": "You are a lead qualification assistant.", "objectives_id": "o12345" }' ``` OR * Add them by [editing the persona](/api-reference/personas/patch-persona) like this: ```sh theme={null} curl --request PATCH \ --url https://tavusapi.com/v2/personas/{persona_id} \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '[ {"op": "add", "path": "/objectives_id", "value": "o12345"} ]' ``` For the best results, try creating unique objectives for different conversation purposes or business outcomes. For example, a customer onboarding persona might use objectives focused on data collection, while a support persona might use objectives focused on issue resolution. ## Parameters ### `objective_name` A desciptive name for the objective. Example: `"check_patient_status"` This must be a string value without spaces. ### `objective_prompt` A text prompt that explains what the goals of this objective are. The more detail you can provide, the better. Example: `"Ask the patient if they are new or are returning."` ### `confirmation_mode` This string value defines whether the LLM should determine whether this objective was completed or not. * If set to `auto`, the LLM makes this decision. * If set to `manual`, the participant must manually confirm that the objective was completed by the platform triggering an app message (`conversation.objective.pending`) and the participant having the ability to send one back called `conversation.objective.confirm`. This can include having the participant review the collected values for accuracy. The default value of `confirmation_mode` is `auto`. ### `output_variables` (optional) This is a list of string variables that should be collected as a result of the objective being successfully completed. Example: `["patient_status", "patient_group"]` ### `modality` This value represents whether a specific objective should be completed based on the participant's verbal or visual responses. Each individual objective can be visual or verbal (not both), but this can vary across objectives. The default value for `modality` is `"verbal"`. ### `next_conditional_objectives` This represents a mapping of objectives (identified by `objective_name`), to conditions that must be satisfied for that objective to be triggered. Example: ```json theme={null} { "new_patient_intake_process": "If the patient has never been to the practice before", "existing_patient_intake_process": "If the patient has been to the practice before" } ``` ### `next_required_objectives` This represents a list of objectives (identified by `objective_name`) that should be triggered once the current objective is completed. Example: `["get_patient_name"]` ### `callback_url` (optional) A URL that you can send notifications to when a particular objective has been completed. Example: `"https://your-server.com/objectives-webhook"` --- # Source: https://docs.tavus.io/sections/conversational-video-interface/overview-cvi.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Overview > CVI enables real-time, human-like video interactions through configurable lifelike replicas. Conversational Video Interface (CVI) is a framework for creating real-time multimodal video interactions with AI. It enables an AI agent to see, hear, and respond naturally, mirroring human conversation. CVI is the world’s fastest interface of its kind. It allows you to map a human face and conversational ability onto your AI agent. With CVI, you can achieve utterance-to-utterance latency with SLAs under 1 second. This is the full round-trip time for a participant to say something and the replica to reply. CVI provides a comprehensive solution, with the option to plug in your existing components as required. ## Key Concepts CVI is built around three core concepts that work together to create real-time, humanlike interactions with an AI agent: The **Persona** defines the agent’s behavior, tone, and knowledge. It also configures the CVI layer and pipeline. The **Replica** brings the persona to life visually. It renders a photorealistic human-like avatar using the **Phoenix-3** model. A **Conversation** is a real-time video session that connects the persona and replica through a WebRTC connection. ## Key Features CVI uses facial cues, body language, and real-time turn-taking to enable natural, human-like conversations. Customize the Perception, STT, LLM and TTS layers to control identity, behavior, and responses. Choose from over 100+ hyper-realistic digital twins or customize your own with human-like voice and expression. Hold natural conversations in 30+ languages using the supported TTS engines. Experience real-time interactions with \~600ms response time and smooth turn-taking. ## Layers The Conversational Video Interface (CVI) is built on a modular layer system, where each layer handles a specific part of the interaction. Together, they capture input, process it, and generate a real-time, human-like response. Here’s how the layers work together: Handles real-time audio and video streaming using WebRTC (powered by Daily). This layer captures the user's microphone and camera input and delivers output back to the user. This layer is always enabled. You can configure input/output for audio (mic) and video (camera). Uses **Raven** to analyze user expressions, gaze, background, and screen content. This visual context helps the replica understand and respond more naturally. [Click here to learn how to configure the Perception layer.](/sections/conversational-video-interface/persona/perception) Controls the natural dynamics of conversation, including turn-taking and interruptibility. Uses **Sparrow** for intelligent turn detection, enabling the replica to decide when to speak and when to listen. [Click here to learn how to configure the Conversational Flow layer.](/sections/conversational-video-interface/persona/conversational-flow) This layer transcribes user speech in real time with lexical and semantic awareness. [Click here to learn how to configure the Speech Recognition (STT) layer.](/sections/conversational-video-interface/persona/stt) Processes the user's transcribed speech and visual input using a low-latency LLM. Tavus provides ultra-low latency optimized LLMs or lets you integrate your own. [Click here to learn how to configure the Large Language Model (LLM) layer.](/sections/conversational-video-interface/persona/llm) Converts the LLM response into speech using the supported TTS Engines (Cartesia **(Default)**, ElevenLabs). [Click here to learn how to configure the Text-to-Speech (TTS) layer.](/sections/conversational-video-interface/persona/tts) Delivers a high-quality, synchronized digital human response using Tavus's real-time avatar engine powered by **Phoenix**. [Click here to learn more about the Replica layer.](/sections/replica/overview) Most layers are configurable via the [Persona](/sections/conversational-video-interface/persona/overview). ## Getting Started You can quickly create a conversation by using the Developer Portal or following the steps in the [Quickstart](/sections/conversational-video-interface/quickstart/use-the-full-pipeline) guide.
If you use Cursor, use this pre-built prompt to get started faster:
## ✅ **System Prompt for AI: React (Vite) + Tavus CVI Integration** **Purpose:** Generate **React (TypeScript)** apps with Tavus CVI using **Vite**, following the official docs and GitHub examples: [https://docs.tavus.io/sections/integrations/embedding-cvi](https://docs.tavus.io/sections/integrations/embedding-cvi) *** ### ✅ **AI MUST ALWAYS DO THE FOLLOWING:** #### **1. Setup React App Using Vite** ```bash theme={null} npm create vite@latest my-tavus-app -- --template react-ts cd my-tavus-app npm install ``` *** #### **2. Install Tavus CVI UI Components** ```bash theme={null} npx @tavus/cvi-ui@latest init npx @tavus/cvi-ui@latest add conversation ``` ✅ This creates: ``` src/components/cvi/components/ cvi-provider.tsx conversation.tsx ``` *** #### **3. Wrap App with `CVIProvider`** Update `src/App.tsx`: ```tsx theme={null} import { CVIProvider } from "./components/cvi/components/cvi-provider"; function App() { return {/* Your app content */}; } ``` *** #### **4. Create Conversation API Call** Always use this pattern: ```ts theme={null} const response = await fetch("https://tavusapi.com/v2/conversations", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": import.meta.env.VITE_TAVUS_API_KEY || "", }, body: JSON.stringify({ replica_id: import.meta.env.VITE_REPLICA_ID || "rfe12d8b9597", // Default persona_id: import.meta.env.VITE_PERSONA_ID || "pdced222244b", // Default }), }); const data = await response.json(); setConversationUrl(data.conversation_url); ``` ✅ **Explain:** `conversation_url` from API response is used inside ``. *** #### **5. Render `Conversation` Inside `CVIProvider`** ```tsx theme={null} setConversationUrl(null)} /> ``` *** #### **6. Add Environment Variable** Create `.env` in the **`my-tavus-app`** folder (if not already there): ``` VITE_TAVUS_API_KEY=your_api_key_here VITE_REPLICA_ID=rfe12d8b9597 // Default replica_id, can be overridden in .env VITE_PERSONA_ID=pdced222244b // Default persona_id, can be overridden in .env ``` * **Important**: **DO NOT** create `.env` outside of the `my-tavus-app` folder. It must be inside your project directory where `src` exists. Access via: ```ts theme={null} import.meta.env.VITE_TAVUS_API_KEY import.meta.env.VITE_REPLICA_ID import.meta.env.VITE_PERSONA_ID ``` *** #### **7. Create `cvi-components.json` by Default** Ensure that the `cvi-components.json` file is generated in the `my-tavus-app` folder with the following content: ```json theme={null} { "tsx": true } ``` *** ### ✅ **Expected AI Output Example** **`src/App.tsx`:** ```tsx theme={null} import React, { useState } from "react"; import { CVIProvider } from "./components/cvi/components/cvi-provider"; import { Conversation } from "./components/cvi/components/conversation"; const App: React.FC = () => { const [conversationUrl, setConversationUrl] = useState(null); const createConversation = async () => { const response = await fetch("https://tavusapi.com/v2/conversations", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": import.meta.env.VITE_TAVUS_API_KEY || "", }, body: JSON.stringify({ replica_id: import.meta.env.VITE_REPLICA_ID || "rfe12d8b9597", persona_id: import.meta.env.VITE_PERSONA_ID || "pdced222244b", }), }); const data = await response.json(); setConversationUrl(data.conversation_url); }; return (

Tavus CVI Integration (Vite)

{!conversationUrl ? ( ) : (
setConversationUrl(null)} />
)}
); }; export default App; ``` *** ### ✅ **Checklist for AI Output** * ✅ Uses **Vite + React TypeScript** (`npm create vite@latest --template react-ts`) * ✅ Includes `npx @tavus/cvi-ui init` and `add conversation` * ✅ Imports `CVIProvider` and `Conversation` from `src/components/cvi/components/` * ✅ Uses correct API call with: * `https://tavusapi.com/v2/conversations` * Headers: `Content-Type`, `x-api-key` * Body: `replica_id` & `persona_id` * ✅ Uses `import.meta.env.VITE_TAVUS_API_KEY` * ✅ Renders `` inside `` * ✅ Purple button is visible in both light and dark modes * ✅ `.env` is created inside the correct project folder (`my-tavus-app`) * ✅ `cvi-components.json` is created by default with `{ "tsx": true }` *** ### Keep things in mind: * If you're already in the `my-tavus-app` folder, avoid running `cd my-tavus-app` again. Check your current folder before running commands. * After running the necessary setup, remember to run `npm run dev` to start your app. * Do **NOT** place the `.env` file outside of the project folder. It must reside within the `my-tavus-app` directory.
--- # Source: https://docs.tavus.io/sections/video/overview.md # Source: https://docs.tavus.io/sections/replica/overview.md # Source: https://docs.tavus.io/sections/conversational-video-interface/persona/overview.md # Source: https://docs.tavus.io/sections/conversational-video-interface/interactions-protocols/overview.md # Source: https://docs.tavus.io/sections/conversational-video-interface/conversation/overview.md # Source: https://docs.tavus.io/sections/conversational-video-interface/component-library/overview.md # Source: https://docs.tavus.io/api-reference/overview.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Overview > Discover the Tavus API — build a real-time, human-like multimodal video conversation with a replica. ## Getting Started with Tavus APIs Tavus APIs allow you to create a Conversational Video Interface (CVI), an end-to-end pipeline for building real-time video conversations with an AI replica. Each replica is integrated with a persona that enables it to see, hear, and respond like a human. You can access the API through standard HTTP requests, making it easy to integrate Conversational Video Interface (CVI) into any application or platform. ### Who Is This For? This API is for developers looking to add real-time, human-like AI interactions into their apps or services. ### What Can You Do? Use the end-to-end Conversational Video Interface (CVI) pipeline to build human-like, real-time multimodal video conversations with these three core components: Define the agent’s behavior, tone, and knowledge. Train a lifelike digital twin from a short 2-minute video. Create a real-time video call session with your AI replica. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/conversation/customizations/participant-limits.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Participant Limits > Control the maximum number of participants allowed in a conversation. ## Create a Conversation with Participant Limits Replicas count as participants. For example, `max_participants: 2` allows one human participant plus one replica. Set `max_participants` to limit room capacity: ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "pdced222244b", "replica_id": "rfe12d8b9597", "max_participants": 2 }' ``` ```json theme={null} { "conversation_id": "ca4301628cb9", "conversation_url": "https://tavus.daily.co/ca4301628cb9", "status": "active" } ``` When the limit is reached, additional users cannot join. --- # Source: https://docs.tavus.io/api-reference/documents/patch-document.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Update Document > Update a specific document's metadata Update metadata for a specific document. This endpoint allows you to modify the document name and its tags. ## OpenAPI ````yaml patch /v2/documents/{document_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/documents/{document_id}: patch: tags: - Documents summary: Update Document description: > Update metadata for a specific document. This endpoint allows you to modify the document's name and tags. operationId: patchDocument parameters: - in: path name: document_id required: true schema: type: string description: The unique identifier of the document to update requestBody: content: application/json: schema: type: object properties: document_name: type: string description: New name for the document example: Updated Document Name tags: type: array description: >- New array of tags for the document. This will overwrite the existing tags for the document. items: type: string example: - docs - website - updated responses: '200': description: Document updated successfully content: application/json: schema: type: object properties: document_id: type: string description: Unique identifier for the document example: d8-5c71baca86fc document_name: type: string description: Updated name of the document example: Updated Document Name document_url: type: string description: URL of the document example: https://docs.example.com/ status: type: string description: Current status of the document processing example: ready progress: type: string nullable: true description: Progress indicator for document processing example: null created_at: type: string description: ISO 8601 timestamp of when the document was created example: '2024-01-01T12:00:00Z' updated_at: type: string description: ISO 8601 timestamp of when the document was last updated example: '2024-01-01T13:00:00Z' callback_url: type: string description: URL that receives status updates example: https://your-server.com/webhook tags: type: array description: Updated array of document tags items: type: string example: - docs - website - updated crawl_config: type: object nullable: true description: >- The crawl configuration used for this document (only present for crawled websites) properties: depth: type: integer description: Crawl depth setting example: 2 max_pages: type: integer description: Maximum pages setting example: 10 crawled_urls: type: array nullable: true description: >- List of URLs that were crawled (only present for crawled websites after processing completes) items: type: string example: - https://docs.example.com/ - https://docs.example.com/getting-started - https://docs.example.com/api last_crawled_at: type: string nullable: true description: ISO 8601 timestamp of when the document was last crawled example: '2024-01-01T12:00:00Z' crawl_count: type: integer nullable: true description: Number of times the document has been crawled example: 1 '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message example: 'Invalid request: document_name must be a string' '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: The error message example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: The error message example: Document not found security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/guardrails/patch-guardrails.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Patch Guardrails > 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" } ] ``` * Ensure the `path` field matches the current guardrails schema. * For the `remove` operation, the `value` parameter is not required. ## OpenAPI ````yaml patch /v2/guardrails/{guardrails_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/guardrails/{guardrails_id}: parameters: - name: guardrails_id in: path required: true description: The unique identifier of the guardrails. schema: type: string example: g12345 patch: tags: - Guardrails summary: Patch Guardrails description: > 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" } ] ``` operationId: patchGuardrails requestBody: content: application/json: schema: type: array items: type: object properties: op: type: string description: >- The operation to perform. Must be one of: add, remove, replace, copy, move, test enum: - add - remove - replace - copy - move - test example: replace path: type: string description: >- A JSON Pointer string that references a location within the target document where the operation is performed example: /guardrail_name value: description: >- The value to be used within the operation. **This field is not required for the `remove` operation**. example: Updated Compliance Guardrails required: - op - path examples: Update Guardrails Name: value: - op: replace path: /data/0/guardrail_name value: updated_compliance_guardrails Update Guardrails Prompt: value: - op: replace path: /data/0/guardrail_prompt value: Updated prompt with new restrictions Remove Callback URL: value: - op: remove path: /data/0/callback_url responses: '200': description: Guardrails updated successfully content: application/json: schema: type: object properties: message: type: string description: Success message example: Guardrails updated successfully '304': description: No changes were made to the guardrails '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid patch operation '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: error: type: string description: The error message. example: Guardrails not found security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/objectives/patch-objectives.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Patch Objective > 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" } ] ``` ## OpenAPI ````yaml patch /v2/objectives/{objectives_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/objectives/{objectives_id}: parameters: - name: objectives_id in: path required: true description: The unique identifier of the objective. schema: type: string example: o12345 patch: tags: - Objectives summary: Patch Objective description: > 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" } ] ``` operationId: patchObjective requestBody: content: application/json: schema: type: array items: type: object properties: op: type: string description: >- The operation to perform. Must be one of: add, remove, replace, copy, move, test enum: - add - remove - replace - copy - move - test example: replace path: type: string description: >- A JSON Pointer string that references a location within the target document where the operation is performed example: /objective_name value: description: >- The value to be used within the operation. **This field is not required for the `remove` operation**. example: updated_objective_name required: - op - path examples: Update Objective Name: value: - op: replace path: /objective_name value: updated_objective_name Update Objective Prompt: value: - op: replace path: /objective_prompt value: Updated prompt for the objective Add Output Variables: value: - op: add path: /output_variables value: - new_variable - another_variable Remove Callback URL: value: - op: remove path: /callback_url responses: '200': description: Objective updated successfully content: application/json: schema: type: object properties: message: type: string description: Success message example: Objective updated successfully '304': description: No changes were made to the objective '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid patch operation '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: error: type: string description: The error message. example: Objective not found security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/personas/patch-persona.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Patch Persona > 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." } ] ``` * Ensure the `path` match the current persona schema. * For the `remove` operation, the `value` parameter is not required. ## OpenAPI ````yaml patch /v2/personas/{persona_id} openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/personas/{persona_id}: parameters: - name: persona_id in: path required: true description: The unique identifier of the persona. schema: type: string example: pf3073f2dcc1 patch: tags: - Personas summary: Patch Persona description: > 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." } ] ``` operationId: patchPersona requestBody: content: application/json: schema: type: array items: type: object properties: op: type: string description: >- The operation to perform. Must be one of: add, remove, replace, copy, move, test enum: - add - remove - replace - copy - move - test example: add path: type: string description: >- A JSON Pointer string that references a location within the target document where the operation is performed example: /layers/llm/model value: type: string description: >- The value to be used within the operation. **Each request must have a `value` field unless you're using `remove` operation**. example: tavus-llama-4 required: - op - path - value examples: Add Persona Context: value: - op: add path: /context value: >- Here are a few times that you have helped an individual make a breakthrough in... Replace Persona System Prompt: value: - op: replace path: /system_prompt value: >- As a Life Coach, you are a dedicated professional who specializes in... Remove STT Hotwords: value: - op: remove path: /layers/stt/hotwords responses: '200': description: OK '304': description: No changes were made to the persona content: application/json: schema: type: object properties: message: type: string description: The error message. example: No changes were made to the persona '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid persona_id '422': description: Invalid JSON patch format content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid JSON patch format security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/phoenix-replica-model/patch-replica-name.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Rename Replica > This endpoint renames a single Replica by its unique identifier. ## OpenAPI ````yaml patch /v2/replicas/{replica_id}/name openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/replicas/{replica_id}/name: parameters: - name: replica_id in: path required: true description: The unique identifier of the persona. schema: type: string example: rf3073f2dcc1 patch: tags: - Replicas summary: Rename Replica description: | This endpoint renames a single Replica by its unique identifier. operationId: renameReplica requestBody: content: application/json: schema: type: object properties: replica_name: type: string example: Rio required: - replica_name examples: Rename Replica: value: replica_name: Rio responses: '200': description: OK '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: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/api-reference/video-request/patch-video-name.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Rename Video > This endpoint renames a single video by its unique identifier. ## OpenAPI ````yaml patch /v2/videos/{video_id}/name openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /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 ```` --- # Source: https://docs.tavus.io/sections/conversational-video-interface/persona/perception-tool.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Tool Calling for Perception > Configure tool calling with `raven-0` to trigger functions from visual input. **Perception tool calling** works with OpenAI’s Function Calling and can be configured in the `perception` layer. It allows an AI agent to trigger functions based on visual cues during a conversation. The perception layer tool calling is only available for `raven-0`. ## Defining Tool ### Top-Level Fields | Field | Type | Required | Description | | ---------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------- | | `type` | string | ✅ | Must be `"function"` to enable tool calling. | | `function` | object | ✅ | Defines the function that can be called by the model. Contains metadata and a strict schema for arguments. | #### `function` | Field | Type | Required | Description | | ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `name` | string | ✅ | A unique identifier for the function. Must be in `snake_case`. The model uses this to refer to the function when calling it. | | `description` | string | ✅ | A natural language explanation of what the function does. Helps the perception model decide when to call it. | | `parameters` | object | ✅ | A JSON Schema object that describes the expected structure of the function’s input arguments. | #### `function.parameters` | Field | Type | Required | Description | | ------------ | ---------------- | -------- | ----------------------------------------------------------------------------------------- | | `type` | string | ✅ | Always `"object"`. Indicates the expected input is a structured object. | | `properties` | object | ✅ | Defines each expected parameter and its corresponding type, constraints, and description. | | `required` | array of strings | ✅ | Specifies which parameters are mandatory for the function to execute. | Each parameter should be included in the required list, even if they might seem optional in your code. ##### `function.parameters.properties` Each key inside `properties` defines a single parameter the model must supply when calling the function. | Field | Type | Required | Description | | ------------------ | ------ | -------- | ------------------------------------------------------------------------ | | `` | object | ✅ | Each key is a named parameter. The value is a schema for that parameter. | Optional subfields for each parameter: | Subfield | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------------------------------------------- | | `type` | string | ✅ | Data type (e.g., `string`, `number`, `boolean`). | | `description` | string | ❌ | Explains what the parameter represents and how it should be used. | | `enum` | array | ❌ | Defines a strict list of allowed values for this parameter. Useful for categorical choices. | ## Example Configuration Here’s an example of tool calling in `perception` layers: **Best Practices:** * Use clear, specific function names to reduce ambiguity. * Add detailed `description` fields to improve selection accuracy. ```json Perception Layer [expandable] theme={null} "perception": { "perception_model": "raven-0", "ambient_awareness_queries": [ "Is the user showing an ID card?", "Is the user wearing a mask?" ], "perception_tool_prompt": "You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`.", "perception_tools": [ { "type": "function", "function": { "name": "notify_if_id_shown", "description": "Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask()", "parameters": { "type": "object", "properties": { "id_type": { "type": "string", "description": "best guess on what type of ID it is", }, }, "required": ["id_type"], }, }, }, { "type": "function", "function": { "name": "notify_if_bright_outfit_shown", "description": "Use this function when a bright outfit is detected in the image with high confidence", "parameters": { "type": "object", "properties": { "outfit_color": { "type": "string", "description": "Best guess on what color of outfit it is" } }, "required": ["outfit_color"] } } } ] } ``` ## How Perception Tool Calling Works Perception Tool calling is triggered during an active conversation when the perception model detects a visual cue that matches a defined function. Here’s how the process works: This example explains the `notify_if_id_shown` function from the [example configuration](#example-configuration) above. The same process applies to other functions like `notify_if_bright_outfit_shown`, which is triggered if a bright-colored outfit is visually detected. ## Modify Existing Tools You can update the `perception_tools` definitions using the Update Persona API. ```shell [expandable] theme={null} curl --request PATCH \ --url https://tavusapi.com/v2/personas/{persona_id} \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '[ { "op": "replace", "path": "/layers/perception/perception_tools", "value": [ { "type": "function", "function": { "name": "detect_glasses", "description": "Trigger this function if the user is wearing glasses in the image", "parameters": { "type": "object", "properties": { "glasses_type": { "type": "string", "description": "Best guess on the type of glasses (e.g., reading, sunglasses)" } }, "required": ["glasses_type"] } } } ] } ]' ``` Replace `` with your actual API key. You can generate one in the Developer Portal. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/persona/perception.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Perception > Learn how to configure the perception layer with Raven to enable the real-time visual understanding. The **Perception Layer** in Tavus enhances an AI agent with real-time visual understanding. By using [Raven](/sections/models#raven%3A-perception-model), the AI agent becomes more context-aware, responsive, and capable of triggering actions based on visual input. ## Configuring the Perception Layer To configure the Perception Layer, define the following parameters within the `layers.perception` object: ### 1. `perception_model` Specifies the perception model to use. * **Options**: * `raven-0` (default and recommended): Advanced visual capabilities, including screen share support, ambient queries, and perception tools. * `basic`: Legacy model with limited features. * `off`: Disables the perception layer. **Screen Share Feature**: When using `raven-0`, screen share feature is enabled by default without additional configuration. ```json theme={null} "layers": { "perception": { "perception_model": "raven-0" } } ``` ### 2. `ambient_awareness_queries` An array of custom queries that `raven-0` continuously monitors in the visual stream. ```json theme={null} "ambient_awareness_queries": [ "Is the user wearing a bright outfit?" ] ``` ### 3. `perception_analysis_queries` An array of custom queries that `raven-0` processes at the end of the call to generate a visual analysis summary for the user. You do not need to set `ambient_awareness_queries` in order to use `perception_analysis_queries`. ```json theme={null} "perception_analysis_queries": [ "Is the user wearing multiple bright colors?", "Is there any indication that more than one person is present?", "On a scale of 1-100, how often was the user looking at the screen?" ] ``` Best practices for `ambient_awareness_queries` and `perception_analysis_queries`: * Use simple, focused prompts. * Use queries that support your persona’s purpose. ### 4. `perception_tool_prompt` Tell `raven-0` when and how to trigger tools based on what it sees. ```json theme={null} "perception_tool_prompt": "You have a tool to notify the system when a bright outfit is detected, named `notify_if_bright_outfit_shown`. You MUST use this tool when a bright outfit is detected." ``` ### 5. `perception_tools` Defines callable functions that `raven-0` can trigger upon detecting specific visual conditions. Each tool must include a `type` and a `function` object detailing its schema. ```json theme={null} "perception_tools": [ { "type": "function", "function": { "name": "notify_if_bright_outfit_shown", "description": "Use this function when a bright outfit is detected in the image with high confidence", "parameters": { "type": "object", "properties": { "outfit_color": { "type": "string", "description": "Best guess on what color of outfit it is" } }, "required": ["outfit_color"] } } } ] ``` Please see [Tool Calling](/sections/conversational-video-interface/persona/perception-tool) for more details. ## Example Configuration This example demonstrates a persona designed to identify when a user wears a bright outfit and triggers an internal action accordingly. ```json theme={null} { "persona_name": "Fashion Advisor", "system_prompt": "As a Fashion Advisor, you specialize in offering tailored fashion advice.", "pipeline_mode": "full", "context": "You're having a video conversation with a client about their outfit.", "default_replica_id": "r79e1c033f", "layers": { "perception": { "perception_model": "raven-0", "ambient_awareness_queries": [ "Is the user wearing a bright outfit?" ], "perception_analysis_queries": [ "Is the user wearing multiple bright colors?", "Is there any indication that more than one person is present?", "On a scale of 1-100, how often was the user looking at the screen?" ], "perception_tool_prompt": "You have a tool to notify the system when a bright outfit is detected, named `notify_if_bright_outfit_shown`. You MUST use this tool when a bright outfit is detected.", "perception_tools": [ { "type": "function", "function": { "name": "notify_if_bright_outfit_shown", "description": "Use this function when a bright outfit is detected in the image with high confidence", "parameters": { "type": "object", "properties": { "outfit_color": { "type": "string", "description": "Best guess on what color of outfit it is" } }, "required": ["outfit_color"] } } } ] } } } ``` Please see the Create a Persona endpoint for more details. ## End-of-call Perception Analysis At the end of the call, `raven-0` will generate a visual summary including all detected visual artifacts. This will be sent as a [Perception Analysis](/sections/event-schemas/conversation-perception-analysis) event to the [conversation callback](/sections/webhooks-and-callbacks#conversation-callbacks) (if specified). This feature is exclusive to personas with `raven-0` specified in the Perception Layer. Once processed, your backend will receive a payload like the following: ```json theme={null} { "properties": { "analysis": "Here's a summary of the visual observations:\n\n* **User Appearance:** The subject is a young person, likely in their teens or early twenties, with dark hair and an East Asian appearance. They consistently wear a dark blue or black hooded jacket/hoodie with pink and white accents, patterns, or text on the sleeves, and possibly a white undershirt. A pendant or charm was observed on their chest. The setting is consistently an indoor environment with a plain white or light-colored wall background.\n* **User Behavior and Demeanor:** The user frequently holds a wired earpiece, microphone, or earbuds near their mouth or chin, appearing to be speaking, listening intently, or in deep thought. Their gaze is predominantly cast downwards, occasionally looking slightly off to the side, with only rare, brief glances forward. They generally maintain a still posture.\n* **User Emotions:** The user's expression is consistently neutral, conveying a sense of quiet concentration, engagement, contemplation, or thoughtful introspection. There are no overt signs of strong emotion; their demeanor is described as calm, focused, sometimes pensive, or slightly subdued. They appear to be actively listening or processing information.\n* **User's gaze towards the screen:** On a scale of 1-100, the user was looking at the screen approximately 75% of the time. While there was one instance where their gaze was averted, for the majority of the observations, the user was either looking directly at the screen or in its general direction." }, "conversation_id": "", "webhook_url": "", "message_type": "application", "event_type": "application.perception_analysis", "timestamp": "2025-07-11T09:13:35.361736Z" } ``` ### `ambient_awareness_queries` For example, if you include the following query: ```json theme={null} "ambient_awareness_queries": [ "Is the user wearing a jacket?" ] ``` Once processed, your backend will receive a payload containing the following sentence: ```json theme={null} **Ambient Awareness Queries:** The user was consistently wearing a jacket throughout the observed period.\n* ``` ### `perception_analysis_queries` For example, if you include the following query: ```json theme={null} "perception_analysis_queries": [ "On a scale of 1-100, how often was the user looking at the screen?" ] ``` Once processed, your backend will receive a payload containing the following sentence: ```json theme={null} **User's Gaze Toward Screen:** "The participant looked at the screen approximately 75% of the time. Their gaze was occasionally diverted, but mostly remained focused in the direction of the camera." ``` --- # Source: https://docs.tavus.io/sections/integrations/pipecat.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Pipecat > Integrate a Tavus Replica into your Pipecat application as a participant or a video feed for the bot. We recommend using Tavus’s Full Pipeline in its entirety for the lowest latency and most optimized multimodal experience. Integrations like LiveKit Agent or Pipecat only provide rendering, while our Full Pipeline includes perception, turn-taking, and rendering for complete conversational intelligence. Tavus offers integration with Pipecat, an open-source framework for building multimodal conversational agents by Daily. You can integrate Tavus into your Pipecat application in two ways: * Additional Tavus Participant (`TavusTransport`) * The Tavus agent joins as a third participant alongside the Pipecat bot and human user. It receives audio from the Pipecat pipeline’s TTS layer and renders synchronized video and audio. * Video Layer for Pipecat Bot (`TavusVideoService`) * Only the Pipecat bot is present in the room. `TavusVideoService` acts as a pipeline layer, sending TTS audio to Tavus in the background. Tavus returns video and audio streams for the bot to display. No additional participant is added. ## Prerequisites Before integrating Tavus with Pipecat, ensure you have the following: * **Tavus API Key** * **Tavus `replica_id`** * You can use one of Tavus's stock replicas or your own custom replica. * **Pipecat Python Application** * Either your own existing application, or use Pipecat’s examples: * `TavusTransport` * `TavusVideoService` ## `TavusTransport` `TavusTransport` connects your Pipecat app to a Tavus conversation, allowing the bot to join the same virtual room as the Tavus avatar and participants. To get started, you can follow the following steps or learn more from this sample code. ### Integration Guide for `TavusTransport` 1. Install the Tavus plugin for Pipecat. ```sh theme={null} pip install pipecat-ai[tavus] ``` 2. In the `.env` file of your pipecat application (at `/path/to/pipecat/.env`) add: ```env theme={null} TAVUS_API_KEY= TAVUS_REPLICA_ID= ``` * Replace `` with your actual API key. You can generate one in the Developer Portal. * Replace `` with the Replica ID you want to use. Create an instance of `TavusTransport` by providing your bot name, Tavus API key, Replica ID, session, and additional parameters. ```py {6, 16-27} theme={null} import os import aiohttp from dotenv import load_dotenv from loguru import logger from pipecat.audio.vad.silero import SileroVADAnalyzer from pipecat.transports.services.tavus import TavusParams, TavusTransport # Other imports... load_dotenv(override=True) logger.remove(0) logger.add(sys.stderr, level="DEBUG") async def main(): async with aiohttp.ClientSession() as session: transport = TavusTransport( bot_name="Pipecat bot", api_key=os.getenv("TAVUS_API_KEY"), replica_id=os.getenv("TAVUS_REPLICA_ID"), session=session, params=TavusParams( audio_in_enabled=True, audio_out_enabled=True, microphone_out_enabled=False, vad_analyzer=SileroVADAnalyzer(), ), ) # stt, tts, llm... ``` See Pipecat API Reference for the configuration details. Add the Tavus transport layer to your processing pipeline. ```py {5, 10} theme={null} # stt, tts, llm... pipeline = Pipeline( [ transport.input(), # Transport user input stt, # STT context_aggregator.user(), # User responses llm, # LLM tts, # TTS transport.output(), # Transport bot output context_aggregator.assistant(), # Assistant spoken responses ] ) ``` 1. Run the following command to execute the program: ```sh theme={null} python .py ``` Replace the `` with your actual Python filename. 2. Use the **Tavus Daily URL** provided in the console to interact with the agent. ## `TavusVideoService` You can use `TavusVideoService` to enable real-time AI-driven video interactions in your Pipecat app. To get started, you can follow the following steps or refer from this sample code. ### Integration Guide for `TavusVideoService` 1. Install the Tavus plugin for Pipecat. ```sh theme={null} pip install pipecat-ai[tavus] ``` 2. In the `.env` file of your pipecat application (at `/path/to/pipecat/.env`) add: ```env theme={null} TAVUS_API_KEY= TAVUS_REPLICA_ID= ``` * Replace `` with your actual API key. You can generate one in the Developer Portal. * Replace `` with the Replica ID you want to use. Create an instance of `TavusVideoService` by providing your Tavus API key and Tavus Replica ID. ```py {6, 15-19} theme={null} import argparse import os import aiohttp from dotenv import load_dotenv from loguru import logger from pipecat.services.tavus.video import TavusVideoService from pipecat.transports.base_transport import BaseTransport # Other imports... load_dotenv(override=True) async def run_example(transport: BaseTransport, _: argparse.Namespace, handle_sigint: bool): logger.info(f"Starting bot") async with aiohttp.ClientSession() as session: tavus = TavusVideoService( api_key=os.getenv("TAVUS_API_KEY"), replica_id=os.getenv("TAVUS_REPLICA_ID"), session=session, ) # stt, tts, llm... ``` See Pipecat Tavus Service for the configuration details. Insert the `TavusVideoService` into the pipeline by adding the `tavus` service after the TTS processor in the pipeline. ```py {10} theme={null} # stt, tts, llm... pipeline = Pipeline( [ transport.input(), # Transport user input stt, # STT context_aggregator.user(), # User responses llm, # LLM tts, # TTS tavus, # Tavus output layer transport.output(), # Transport bot output context_aggregator.assistant(), # Assistant spoken responses ] ) ``` 1. Run the following command to execute the program: ```sh theme={null} python .py ``` Replace the `` with your actual Python filename. 2. Use the **localhost URL** provided in the console to interact with the agent. --- # Source: https://docs.tavus.io/sections/conversational-video-interface/conversation/customizations/private-rooms.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Private Rooms > Create authenticated conversations with meeting tokens for enhanced security. ## Create a Private Conversation To create a private room, set `require_auth` to `true`: ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/conversations \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "persona_id": "pdced222244b", "replica_id": "rfe12d8b9597", "require_auth": true }' ``` The response includes a `meeting_token`: ```json theme={null} { "conversation_id": "ca4301628cb9", "conversation_url": "https://tavus.daily.co/ca4301628cb9", "meeting_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "status": "active" } ``` Use the token by appending it to the URL: ``` https://tavus.daily.co/ca4301628cb9?t=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` Or pass it to the Daily SDK: ```javascript theme={null} callFrame.join({ url: conversation_url, token: meeting_token }); ``` --- # Source: https://docs.tavus.io/sections/video/quickstart.md # Source: https://docs.tavus.io/sections/replica/quickstart.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart > Create high-quality Personal or Non-human Replicas for use in conversations. ## Prerequisites Before starting, ensure you have: * Pre-recorded training and consent videos that meet the requirements outlined in [Replica Training](/sections/replica/replica-training). * Publicly accessible **S3 URLs** for: * Your training video * Your consent video Ensure both URLs remain valid for at least **24 hours**. ## Create a Replica Use the following request to create the replica: By default, replicas are trained using the `phoenix-3` model. To use an older version, set `"model_name": "phoenix-2"` in your request body. However, we strongly recommend using the latest `phoenix-3` model for improved quality and performance. ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/replicas \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "callback_url": "", "replica_name": "", "train_video_url": "", "consent_video_url": "" }' ``` * Replace `` with your actual API key. You can generate one in the Developer Portal. * Replace `` with the downloadable URL of your training video. * Replace `` with the downloadable URL of your consent video. Once submitted, your replica will begin training in the background. This process typically takes 4–6 hours. You can monitor the training status using the Get Replica endpoint: ```shell cURL theme={null} curl --request GET \ --url https://tavusapi.com/v2/replicas/{replica_id} \ --header 'x-api-key: ' ``` Replace `` with your actual API key. Once training is complete, you can use your non-human replica for: * [Conversational Video Interface](/sections/conversational-video-interface/overview-cvi) * [Video Generation](/sections/video/overview) ## Non-human Replica To create a non-human replica, you do not need a **consent video**: If you're using the Developer Portal, select the **Skip** tab in the consent video window. ```shell cURL theme={null} curl --request POST \ --url https://tavusapi.com/v2/replicas \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "callback_url": "", "replica_name": "", "train_video_url": "" }' ``` * Replace `` with your actual API key. You can generate one in the Developer Portal. * Replace `` with the name for your non-human replica. * Replace `` with the downloadable URL of your training video. --- # Source: https://docs.tavus.io/api-reference/documents/recrawl-document.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Recrawl Document > Trigger a recrawl of a website document to fetch fresh content Trigger a recrawl of a document that was created with crawl configuration. This is useful for keeping your knowledge base up-to-date when website content changes. ## When to Recrawl Use this endpoint when: * The source website has been updated with new content * You want to refresh the document's content on a schedule * The initial crawl encountered errors and you want to retry ## How Recrawling Works When you trigger a recrawl: 1. The system uses the same starting URL from the original document 2. Links are followed according to the crawl configuration (depth and max\_pages) 3. New content is processed and stored 4. Old vectors are replaced with the new content once processing completes 5. The document's `crawl_count` is incremented and `last_crawled_at` is updated ## Requirements * **Document State**: The document must be in `ready` or `error` state * **Crawl Configuration**: The document must have been created with a `crawl` configuration, or you must provide one in the request body ## Rate Limits To prevent abuse, the following limits apply: * **Cooldown Period**: 1 hour between recrawls of the same document * **Concurrent Crawls**: Maximum 5 crawls running simultaneously per user * **Total Documents**: Maximum 100 crawl documents per user ## Overriding Crawl Configuration You can optionally provide a `crawl` object in the request body to override the stored configuration for this recrawl: ```json theme={null} { "crawl": { "depth": 3, "max_pages": 50 } } ``` If no `crawl` object is provided, the original crawl configuration from document creation is used. ## Monitoring Recrawl Progress After initiating a recrawl: 1. The document status changes to `recrawling` 2. If you provided a `callback_url` during document creation, you'll receive status updates 3. When complete, the status changes to `ready` (or `error` if it failed) 4. Use [Get Document](/api-reference/documents/get-document) to check the current status ## OpenAPI ````yaml post /v2/documents/{document_id}/recrawl openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Conversations - name: Personas - name: Replacements - name: Transcriptions - name: Documents paths: /v2/documents/{document_id}/recrawl: post: tags: - Documents summary: Recrawl Document description: > Trigger a recrawl of a document that was created with crawl configuration. The recrawl will fetch fresh content from the website and replace the existing vectors. **Requirements:** - Document must be in `ready` or `error` state - Document must have been created with a `crawl` configuration (or you must provide one in this request) - There is a 1-hour cooldown between recrawls of the same document **Rate Limits:** - Maximum 5 concurrent crawls per user - Maximum 100 crawl documents per user operationId: recrawlDocument parameters: - in: path name: document_id required: true schema: type: string description: The unique identifier of the document to recrawl example: d8-5c71baca86fc requestBody: required: false content: application/json: schema: type: object properties: crawl: type: object description: > Optional crawl configuration to override the stored settings. If not provided, the original crawl configuration will be used. properties: depth: type: integer description: >- How many levels deep to follow links from the starting URL (1-10) minimum: 1 maximum: 10 example: 2 max_pages: type: integer description: Maximum number of pages to crawl (1-100) minimum: 1 maximum: 100 example: 10 responses: '202': description: Recrawl initiated successfully content: application/json: schema: type: object properties: document_id: type: string description: Unique identifier for the document example: d8-5c71baca86fc document_name: type: string description: Name of the document example: Company Website document_url: type: string description: URL of the document example: https://example.com/ status: type: string description: Current status of the document (will be 'recrawling') example: recrawling progress: type: integer nullable: true description: Progress indicator for document processing example: null created_at: type: string description: ISO 8601 timestamp of when the document was created example: '2024-01-01T12:00:00Z' updated_at: type: string description: ISO 8601 timestamp of when the document was last updated example: '2024-01-15T10:30:00Z' callback_url: type: string description: URL that will receive status updates example: https://your-server.com/webhook tags: type: array description: Array of document tags items: type: string example: - website - company crawl_config: type: object description: The crawl configuration being used for the recrawl properties: depth: type: integer example: 2 max_pages: type: integer example: 10 crawled_urls: type: array nullable: true description: >- List of URLs from the previous crawl (will be updated when recrawl completes) items: type: string example: - https://docs.example.com/ - https://docs.example.com/getting-started last_crawled_at: type: string nullable: true description: ISO 8601 timestamp of the previous crawl example: '2024-01-01T12:05:00Z' crawl_count: type: integer description: >- Number of times the document has been crawled (will increment when recrawl completes) example: 1 '400': description: Bad Request - Validation error content: application/json: schema: type: object properties: error: type: string description: The error message example: Document was not created with crawl configuration '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: The error message example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: The error message example: Document not found '409': description: Conflict - Document state prevents recrawl content: application/json: schema: type: object properties: error: type: string description: The error message example: >- Document must be in 'ready' or 'error' state to recrawl, current status: processing '429': description: Too Many Requests - Rate limit exceeded or cooldown period content: application/json: schema: type: object properties: error: type: string description: The error message example: >- Recrawl cooldown: please wait 45 minutes before recrawling this document. security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` --- # Source: https://docs.tavus.io/sections/replica/replica-training.md > ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Replica Training > Guide to recording a high-quality training video for generating a high-quality Replica using the Phoenix model. You can record the Replica training video directly in the Developer Portal or upload a pre-recorded one via the API. ## Talking Head Replica ### Environment * Record in a quiet, well-lit space with no background noise or movement. * Use diffuse lighting to avoid shadows on your face. * Choose a simple background and avoid any moving people or objects. ### Camera * Place the camera at eye level and ensure your face fills at least 25% of the frame. * Use a desktop recording app (e.g., **QuickTime** on Mac or **Camera** on Windows) — avoid browser-based tools. ### Microphone * Use your device’s built-in microphone. * **Avoid** high-end mics or wireless earbuds like AirPods. * Turn off audio effects like noise suppression or EQ adjustments. ### Yourself | ✅ Do | ❌ Don’t | | ----------------------------------------------------------------------------------- | ------------------------------------------------------ | | Keep your full head visible, with a clear view of your face | Wear clothes that blend into the background | | Ensure your face and upper body are in sharp focus | Wear accessories like hats, thick glasses, or earrings | | If using smartphone, make sure you follow the same framing/distance from the camera | Turn your head away from the camera | | Tuck back any hair covering your face | Block your chin or mouth with your microphone | | Sit upright in a stable, seated position | Stand or shift positions during the video | ### Video Format If you're uploading a pre-recorded training video via our API, ensure it meets the following requirements: * **Minimum FPS**: 25 fps * **Accepted formats**: * `webm` * `mp4` with **H.264** video codec and **AAC** audio codec * **Maximum file size**: 750MB * **Minimum resolution**: 1080p ### Consent Statement If you're creating a **personal replica**, you must include a verbal consent statement in the video. This ensures ethical use and compliance with data protection laws. **Steps**: * Begin with a big smile and look directly into the camera for one second. * Clearly read the following script: > I, (your name), am currently speaking and give consent to 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. This step is **only required for personal replicas**. If you’re creating an **AI replica**, you can skip this video. ## Recording Your Training Video Your video must be **one continuous shot**, containing: **Pro tips**: * Keep body and head movements subtle * Avoid heavy hand gestures * Only one person should appear in the video * Smile widely for at least 2 seconds. * Look directly at the camera, positioned just below eye level. * Speak casually, as if talking to a friend. * Pause briefly (close lips) every 1–2 sentences. * Minimize body movement. * Avoid hand gestures at all times. * Sample script: ```txt [expandable] theme={null} For the next 2 minutes, I’ll read you a story that will for sure make you smile and feel good. I will be relaxed and keep a happy face while reading. I will also read this story at a faster pace than I normally speak. I will close my lips fully after every sentence. I will read this script in a casual and conversational tone as if I am telling a story to my friend. The sun was shining brightly, casting a warm glow over the park as Emma, Jake, and Sophie spread out their picnic blanket. Now I will close my lips fully. Emma looked around, her face beaming with excitement. "Can you believe how perfect today is?" she exclaimed. "The sun is shining, and the weather is just right!" Her enthusiasm was contagious, and Jake couldn't help but smile as he laid back on the blanket, soaking in the sunlight. Now I will close my lips fully after this sentence. Jake nodded in agreement, a relaxed grin spreading across his face. "It really is," he said. "Days like this remind me why I love summer. I will close my lips fully after this sentence. Sophie, always the energetic one, jumped up from the blanket with a burst of excitement. "And we have the whole day to ourselves!" she declared. "So many possibilities. What should we do first? Fly a kite? Play frisbee? Go for a hike?" Her eyes sparkled. I will close my lips fully after this sentence. This is the last sentence I will read and then I will stand still to record my listening segment with minimal head and body movement as if I am listening to someone share a story. ``` * Sit still with a relaxed, attentive posture. * Keep lips gently closed the entire time. * Slight, natural head movements (like you’re listening on a Zoom call). Replica training typically takes **4–5 hours**. You can track the training progress by: * Providing a `callback_url` when creating the replica via API * Using the **Get Replica Status** API * Checking the Developer Portal ## High-Quality Training Example