> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tavus

> AI avatar video generation service for creating realistic talking avatars

## Overview

`TavusVideoService` integrates with Tavus to generate AI-powered video avatars that speak your text-to-speech output in real-time. The service takes audio input and produces synchronized video of a realistic avatar speaking, enabling engaging conversational AI experiences with visual presence.

<CardGroup cols={2}>
  <Card title="Tavus Video API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.tavus.video.html">
    Pipecat's API methods for Tavus video integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/video-avatar/video-avatar-tavus-video-service.py">
    Complete example with avatar video generation
  </Card>

  <Card title="Tavus Documentation" icon="book" href="https://docs.tavus.io/sections/replica/overview">
    Official Tavus replica and avatar documentation
  </Card>

  <Card title="Tavus Platform" icon="microphone" href="https://platform.tavus.io/auth/sign-up?plan=free">
    Create avatars and manage API keys
  </Card>
</CardGroup>

## Installation

To use Tavus services, install the required dependency:

```bash theme={null}
uv add "pipecat-ai[tavus]"
```

## Prerequisites

### Tavus Account Setup

Before using Tavus video services, you need:

1. **Tavus Account**: Sign up at [Tavus Platform](https://platform.tavus.io/auth/sign-up?plan=free)
2. **API Key**: Generate an API key from your account dashboard
3. **Replica Creation**: Create and train voice replicas for your avatars
4. **Avatar Selection**: Choose or create avatar models for video generation

### Required Environment Variables

* `TAVUS_API_KEY`: Your Tavus API key for authentication
* `TAVUS_REPLICA_ID`: ID of your trained voice replica

## Configuration

<ParamField path="api_key" type="str" required>
  Tavus API key for authentication.
</ParamField>

<ParamField path="replica_id" type="str" required>
  ID of the Tavus voice replica to use for speech synthesis.
</ParamField>

<ParamField path="persona_id" type="str" default="pipecat-stream">
  ID of the Tavus persona. Defaults to `"pipecat-stream"` for Pipecat TTS voice.
</ParamField>

<ParamField path="session" type="aiohttp.ClientSession" required>
  Async HTTP session used for communication with Tavus.
</ParamField>

<ParamField path="settings" type="TavusVideoService.Settings" default="None">
  Runtime-configurable settings. Tavus has no model-level settings, so this is
  primarily used for the `extra` dict. See [Service
  Settings](/pipecat/fundamentals/service-settings) for details.
</ParamField>

## Usage

### Basic Setup

```python theme={null}
import aiohttp
from pipecat.services.tavus import TavusVideoService

async with aiohttp.ClientSession() as session:
    tavus = TavusVideoService(
        api_key=os.getenv("TAVUS_API_KEY"),
        replica_id=os.getenv("TAVUS_REPLICA_ID"),
        session=session,
    )
```

### With Custom Persona

```python theme={null}
tavus = TavusVideoService(
    api_key=os.getenv("TAVUS_API_KEY"),
    replica_id=os.getenv("TAVUS_REPLICA_ID"),
    persona_id="my-custom-persona",
    session=session,
)
```

## Notes

* **Dual room architecture**: When used with DailyTransport, Tavus creates two virtual rooms -- a Tavus room (containing the avatar and the Pipecat bot) and a user room (containing the Pipecat bot and the user).
* **Interruption handling**: The service handles interruptions by resetting the audio send task and sending an interrupt message to the Tavus client.
* **Metrics support**: The service supports TTFB metrics tracking using `TTSStartedFrame` and `BotStartedSpeakingFrame` signals.