---
name: Tavus
description: Use when building real-time video conversations with AI replicas, creating personas with specific behaviors, training digital humans, generating videos, or integrating conversational AI into applications. Reach for this skill when working with the Conversational Video Interface (CVI) pipeline, configuring persona layers, managing replicas, or handling knowledge base integration.
metadata:
mintlify-proj: tavus
version: "1.0"
---
# Tavus Skill Reference
## Product Summary
Tavus is a platform for building real-time, multimodal video conversations with AI replicas. The core product is the **Conversational Video Interface (CVI)**, an end-to-end pipeline that combines three components: **Persona** (behavior and knowledge), **Replica** (photorealistic digital human), and **Conversation** (real-time video session). All interactions use the Tavus API via HTTP requests with header-based authentication (`x-api-key`). The primary documentation is at https://docs.tavus.io. Key endpoints live under `https://tavusapi.com/v2/` (personas, conversations, replicas, documents, videos, objectives, guardrails).
## When to Use
Reach for this skill when:
- Building a real-time video conversation feature (sales calls, interviews, customer support, coaching)
- Configuring an AI agent's behavior, tone, knowledge, and response style via a Persona
- Training a custom digital replica from video or image
- Generating static videos with a replica reading a script
- Attaching knowledge documents (PDFs, websites) to a persona for grounded responses
- Setting up structured conversation workflows with Objectives or behavioral guardrails
- Integrating Tavus into a web app via the React component library or custom UI
- Troubleshooting latency, persona behavior, or document retrieval issues
## Quick Reference
### API Authentication
All requests require the `x-api-key` header. Generate keys in the Developer Portal at https://platform.tavus.io/api-keys.
```bash
curl --request POST \
--url https://tavusapi.com/v2/conversations \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api_key>' \
--data '{"persona_id": "...", "replica_id": "..."}'
```
### Core Resources & IDs
| Resource | Purpose | ID Prefix | Create Endpoint |
|----------|---------|-----------|-----------------|
| Persona | Behavior, tone, knowledge, layer config | `p` | POST `/personas` |
| Replica | Digital human avatar | `r` | POST `/replicas` |
| Conversation | Real-time video session | `c` | POST `/conversations` |
| Document | Knowledge base file/URL | `d` | POST `/documents` |
| Objective | Structured conversation goal | `o` | POST `/objectives` |
| Guardrail | Behavioral boundary rule | `g` | POST `/guardrails` |
| Voice | TTS voice option | varies | GET `/voices` |
### Persona Layers (Configurable)
| Layer | Purpose | Key Config |
|-------|---------|------------|
| Perception | Visual understanding (facial expressions, gaze, background) | `perception_model: "raven-1"` |
| STT | Speech-to-text transcription | `stt_engine: "default"` |
| Conversational Flow | Turn-taking, interruption handling | `turn_taking_patience: "high"/"medium"/"low"` |
| LLM | Language model for responses | `model: "tavus-gpt-oss"` (or custom) |
| TTS | Text-to-speech voice | `tts_engine: "cartesia"` (default) |
### LLM Model Options (Tavus-Hosted)
| Model | Speed | Intelligence | Best For |
|-------|-------|--------------|----------|
| `tavus-gpt-oss` | Fastest | Good | Snappy, low-latency responses |
| `tavus-gemini-2.5-flash` | Fast | Better | Balanced latency + reasoning |
| `tavus-claude-haiku-4.5` | Fast | Better | Grounded, fewer hallucinations |
| `tavus-gemini-3-flash` | Slower | Best | Highest intelligence, lower speed |
Note: Keep prompts under 5,000 tokens for optimal performance.
## Workflow
### 1. Create a Persona
Write a system prompt using Identity -> Personality -> Core Behaviors -> Response Style Rules -> Guardrails -> optional Conversation Flow.
```bash
curl --request POST \
--url https://tavusapi.com/v2/personas \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api_key>' \
--data '{
"persona_name": "Sales Coach",
"system_prompt": "You are Alex, a sales coach...",
"pipeline_mode": "full",
"default_replica_id": "r5dc7c7d0bcb",
"layers": {
"perception": {"perception_model": "raven-1"},
"conversational_flow": {
"turn_detection_model": "sparrow-1",
"turn_taking_patience": "high"
},
"llm": {"model": "tavus-gpt-oss"}
}
}'
```
### 2. Create or Select a Replica
Use a stock replica for instant setup, train a custom replica from a 1-10 minute video for highest fidelity, or create an image-based replica from a headshot and voice.
### 3. Create a Conversation
```bash
curl --request POST \
--url https://tavusapi.com/v2/conversations \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api_key>' \
--data '{
"persona_id": "p...",
"replica_id": "r...",
"conversation_name": "Strategy Session",
"conversational_context": "You are speaking with a construction executive about project risk.",
"document_ids": ["d..."],
"document_retrieval_strategy": "quality"
}'
```
The response includes `conversation_url`. Embed it in the app or open it for the user.
## Common Gotchas
- Never expose the Tavus API key in client-side code.
- Keep system prompts under 5,000 tokens; use `conversational_context` for session-specific details.
- Confirm replicas are `ready` before creating conversations.
- Billing starts when the conversation is created, so set call duration and idle timeout limits.
- Conversation context is appended to the persona prompt; it does not replace the base prompt.
- Replicas can only talk. They cannot submit forms, send emails, or perform app actions unless you build that separately.
- Parse upstream error bodies defensively because Tavus may return non-JSON error text.
## Verification Checklist
- System prompt is spoken-first and natural aloud.
- Prompt is under 5,000 tokens.
- API key is loaded from secure server-side environment variables.
- Conversation has call duration and idle timeout limits.
- Persona and replica IDs are configured.
- The app reports missing configuration explicitly.
- Upstream Tavus errors return concise, non-generic errors.
## Resources
- Comprehensive navigation: https://docs.tavus.io/llms.txt
- Conversational Video Interface overview: https://docs.tavus.io/sections/conversational-video-interface/overview-cvi
- Prompting guide: https://docs.tavus.io/sections/onboarding-guide/prompting-guide
- API reference overview: https://docs.tavus.io/api-reference/overview
