---
name: tavus
description: Use when building real-time conversational AI video interfaces (CVI), creating PALs (Personified Application Layers) with custom faces and voices, deploying AI agents to websites, integrating tool calling and knowledge bases, or managing AI conversations at scale
metadata:
    mintlify-proj: tavus
    version: "1.0"
---

# Tavus Skill

## Product Summary

Tavus is a platform for building real-time conversational video interfaces (CVI) powered by AI agents called PALs (Personified Application Layers). A PAL is a configurable AI agent that combines behavior (system prompt, objectives, guardrails), a Face (photorealistic avatar via Phoenix), and a Voice (TTS engine). The CVI pipeline layers—Perception (Raven), Conversational Flow (Sparrow), STT, LLM, and TTS—process input and generate human-like responses over WebRTC. Deploy PALs as managed widgets/embeds, embed them in web apps, or call the REST API directly. Key files: API endpoints at `https://tavusapi.com/v2/`, authentication via `x-api-key` header, PAL Maker at `https://maker.tavus.io/dev`. Primary docs: https://docs.tavus.io

## When to Use

Reach for this skill when:
- **Building a PAL**: Creating a new conversational AI agent with custom behavior, knowledge, objectives, or guardrails
- **Deploying conversations**: Publishing a PAL as a widget, embed, or landing page without backend code
- **Integrating tool calling**: Wiring LLM or perception tools so the PAL can trigger external APIs, webhooks, or frontend actions
- **Managing faces and voices**: Training custom faces from video/image or selecting stock faces; configuring TTS engines
- **Handling conversations**: Creating, managing, or ending real-time video sessions; attaching memory, documents, or custom context
- **Debugging conversations**: Checking conversation status, reviewing event schemas, troubleshooting latency or tool failures
- **Using MCP or CLI**: Building PALs programmatically via the hosted MCP server or `tavus` CLI for automation

## Quick Reference

### Core Concepts

| Concept | What It Is | Where to Configure |
|---------|-----------|-------------------|
| **PAL** | Personified Application Layer—the AI agent you build | API `/v2/pals` or PAL Maker |
| **Face** | Photorealistic avatar (Phoenix model) | API `/v2/faces` or PAL Maker |
| **Voice** | Text-to-speech engine (Cartesia, ElevenLabs, Azure) | PAL's TTS layer |
| **Conversation** | Live WebRTC session linking a PAL and Face | API `/v2/conversations` |
| **Deployment** | Managed widget/embed/landing-page for public use | PAL Maker, no API key needed |
| **Tool** | Function the PAL can call (LLM, perception, post-call) | API `/v2/tools` |
| **Skill** | Tavus-authored capability (search, Magic Canvas, etc.) | Attach via API, not user-defined |
| **Knowledge Base** | Documents (PDF, URL, etc.) for RAG retrieval | API `/v2/documents` |

### API Endpoints (Core)

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/v2/pals` | POST | Create a PAL |
| `/v2/pals/{pal_id}` | GET, PATCH, DELETE | Read, update, or delete a PAL |
| `/v2/conversations` | POST | Start a conversation |
| `/v2/conversations/{id}` | GET, END, DELETE | Manage a conversation |
| `/v2/faces` | POST | Create a custom face |
| `/v2/faces/{id}` | GET, UPDATE, DELETE | Manage a face |
| `/v2/tools` | POST | Create a tool |
| `/v2/tools/{id}` | GET, UPDATE, DELETE | Manage a tool |
| `/v2/documents` | POST | Upload a knowledge document |
| `/v2/deployments` | POST | Create a deployment |
| `/v2/objectives` | POST | Create objectives for workflow |
| `/v2/guardrails` | POST | Create guardrails for safety |

### Authentication

```bash
# Set API key in header on every request
x-api-key: <your-api-key>

# Generate key in PAL Maker: https://maker.tavus.io/dev → API Key
# Store securely; never expose in client code
```

### PAL Creation (Minimal Example)

```json
{
  "pal_name": "My Agent",
  "system_prompt": "You are a helpful assistant.",
  "pipeline_mode": "full",
  "default_face_id": "rc9cff32ceba",
  "layers": {
    "llm": {
      "model": "tavus-gemma-4"
    },
    "perception": {
      "perception_model": "raven-1"
    },
    "conversational_flow": {
      "turn_detection_model": "sparrow-2"
    }
  }
}
```

### Conversation Creation

```json
{
  "pal_id": "<your-pal-id>",
  "face_id": "<optional-override>",
  "conversation_name": "Session Name",
  "participant_tags": ["user-123"],
  "document_ids": ["doc-1", "doc-2"],
  "properties": {
    "max_call_duration": 3600,
    "languages": ["en"]
  }
}
```

### Deployment (No API Key Needed)

```html
<!-- Widget (floating launcher) -->
<tavus-widget deployment-id="YOUR_DEPLOYMENT_ID"></tavus-widget>
<script src="https://unpkg.com/@tavus/widget"></script>

<!-- Embed (inline) -->
<tavus-embed deployment-id="YOUR_DEPLOYMENT_ID"></tavus-embed>
<script src="https://unpkg.com/@tavus/embed"></script>
```

## Decision Guidance

### When to Use X vs Y

| Decision | Use This | When | Use That | When |
|----------|----------|------|----------|------|
| **Deployment vs API** | Deployment (widget/embed) | No backend, managed lifecycle, public-facing | API + custom embed | Full control, private rooms, complex logic |
| **Stock Face vs Custom** | Stock face | Prototyping, demos, no training data | Custom face | Brand identity, specific likeness required |
| **LLM Model** | `tavus-gemma-4` | Default; low latency + good quality | `tavus-gpt-5.6-sol` | Highest intelligence, tool adherence |
| **Tool Delivery** | App message | Frontend handles result, real-time feedback | API call | Tavus calls your webhook directly |
| **Memory** | Participant tags | Stateful, multi-turn with same user | No tags | Stateless, one-off conversations |
| **Objectives** | Use | Templated workflows (intake, interviews) | Skip | Free-flowing, open-ended conversations |
| **Guardrails** | Use | Safety/compliance boundaries needed | Skip | No behavioral constraints required |
| **Knowledge Base** | Use | PAL needs to reference documents | Skip | No external knowledge needed |

## Workflow

### 1. Create a PAL

1. **Authenticate**: Get API key from PAL Maker (`https://maker.tavus.io/dev` → API Key).
2. **Choose a face**: Pick a stock face ID (e.g., `rc9cff32ceba`) or create a custom face first.
3. **Define behavior**: Write a system prompt, set objectives/guardrails if needed.
4. **Configure layers**: Set LLM model, perception, STT, TTS, conversational flow.
5. **POST to `/v2/pals`**: Send the PAL config; save the returned `pal_id`.
6. **Attach tools/skills** (optional): Use `/v2/pals/{pal_id}/tools` or `/v2/pal-skills/attach-skill-to-pal`.

### 2. Create a Conversation

1. **POST to `/v2/conversations`**: Pass `pal_id`, optional `face_id` override, `participant_tags` for memory.
2. **Receive `conversation_url`**: Share this link or embed it in your app.
3. **Join the call**: User clicks the link or your app joins via WebRTC.
4. **Monitor events**: Listen for `conversation.tool_call`, `conversation.utterance`, etc. via webhooks or app messages.
5. **End the call**: POST to `/v2/conversations/{id}/end` or let it timeout.

### 3. Deploy to Production

1. **Create a deployment** in PAL Maker: Choose channel (widget/embed/landing-page), set customizations, limits, origins.
2. **Get deployment ID**: Copy from PAL Maker.
3. **Add to your site**: Drop the script tag and custom element into your HTML.
4. **Configure protections**: Set allowed origins, call limits, bot protection (Cloudflare Turnstile).
5. **No backend needed**: Tavus manages conversation creation and lifecycle server-side.

### 4. Integrate Tool Calling

1. **Create a tool**: POST to `/v2/tools` with name, description, parameters (JSON Schema), origin (`llm` or `vision`), delivery (app message or API).
2. **Attach to PAL**: POST to `/v2/pals/{pal_id}/tools` with the tool ID.
3. **Handle calls**: Listen for `conversation.tool_call` events or receive webhooks at your API endpoint.
4. **Return result**: Send the result back via app message or return from your webhook.

### 5. Add Knowledge Base

1. **Create documents**: POST to `/v2/documents` with URL or file; wait for `status: ready`.
2. **Attach to PAL**: POST to `/v2/pals/{pal_id}/knowledge` with document IDs or tags.
3. **Configure RAG**: Patch `/v2/pals/{pal_id}` to tune `layers.knowledge_base` (score threshold, chunk count).
4. **Use in conversation**: Pass `document_ids` or `document_tags` when creating a conversation.

## Common Gotchas

- **API key in client code**: Never expose `x-api-key` in browsers or mobile apps. Always call Tavus from your backend.
- **Face ID required**: Every PAL must have a `default_face_id`. If you override it per conversation, both must be valid.
- **Conversation URL expires**: The `conversation_url` is valid for the lifetime of the conversation. Once ended, it cannot be rejoined.
- **Tool delivery timeout**: API-delivered tools have a 5-second timeout. If your webhook is slow, mark it as `fire_and_forget` or use app messages.
- **Memory is per-PAL**: Participant tags create memory stores scoped to a PAL. Reuse the same tag with the same PAL to continue memory across sessions.
- **Knowledge Base is English-only**: Documents must be in English; conversations work best in English.
- **Objectives are rigid**: Objectives define a fixed workflow. For dynamic conversations, rely on system prompt and guardrails instead.
- **Perception model overhead**: `raven-1` adds latency. Use `disabled` if you don't need visual/audio analysis.
- **Context window limits**: Keep system prompts + context under 5,000 tokens for best performance.
- **Legacy field names**: Old code may use `persona_id`, `replica_id`, `memory_stores`. These still work but prefer `pal_id`, `face_id`, `participant_tags`.
- **Deployment ID is public**: The deployment ID is safe to expose; it's protected by origin restrictions and call limits, not secrecy.
- **Tool parameters must be JSON Schema**: Tool parameters must be valid JSON Schema; missing `type` or `properties` will fail validation.
- **Guardrails don't block**: Guardrails steer the PAL and flag violations; they don't prevent the PAL from speaking. Use objectives for hard workflow gates.

## Verification Checklist

Before submitting work with Tavus:

- [ ] **API key is set** and stored securely (environment variable, not hardcoded).
- [ ] **PAL has a valid `default_face_id`** (stock or custom, and status is `ready` for custom faces).
- [ ] **System prompt is clear and concise** (under 5,000 tokens total with context).
- [ ] **LLM model is chosen** (default `tavus-gemma-4` unless you have a reason to change).
- [ ] **Perception/STT/TTS layers are configured** (or explicitly disabled if not needed).
- [ ] **Tools are attached and tested**: Create a test conversation and verify tool calls fire.
- [ ] **Knowledge documents are ready**: Check `/v2/documents/{id}` status is `ready` before attaching.
- [ ] **Objectives/guardrails are valid JSON** (if used) and attached to the PAL.
- [ ] **Conversation creation succeeds**: Test POST to `/v2/conversations` and verify `conversation_url` is returned.
- [ ] **Deployment origins are set** (if public): Restrict to your domains to prevent abuse.
- [ ] **Memory tags are stable**: Reuse the same `participant_tags` for multi-turn sessions.
- [ ] **Error handling is in place**: Check for 400 (validation), 401 (auth), 429 (rate limit), 5xx (server).
- [ ] **Webhooks are tested** (if using tool delivery or callbacks): Verify your endpoint receives and responds correctly.

## Resources

- **Full docs index**: https://docs.tavus.io/llms.txt (comprehensive page-by-page navigation for agents)
- **Full docs export**: https://docs.tavus.io/llms-full.txt (bundled markdown for offline reference)
- **OpenAPI spec**: https://docs.tavus.io/openapi.yaml (HTTP API contract)
- **Critical pages**:
  - [What Is CVI?](https://docs.tavus.io/sections/conversational-video-interface/overview-cvi) — Architecture, layers, and pipeline
  - [API Conversation Quickstart](https://docs.tavus.io/sections/conversational-video-interface/quickstart/cvi-quickstart) — Create PAL and conversation in 3 steps
  - [Deployments Overview](https://docs.tavus.io/sections/deployments/overview) — Widget, embed, landing page patterns

---

> For additional documentation and navigation, see: https://docs.tavus.io/llms.txt