Skip to main content

​
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.

Tavus Video API Reference

Pipecat’s API methods for Tavus video integration

Example Implementation

Complete example with avatar video generation

Tavus Documentation

Official Tavus replica and avatar documentation

Tavus Platform

Create avatars and manage API keys

​
Installation

To use Tavus services, install the required dependency: 
pip install "pipecat-ai[tavus]"

​
Prerequisites

​
Tavus Account Setup

Before using Tavus video services, you need:
  1. Tavus Account: Sign up at Tavus Platform
  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

​
api_key
str
required
Tavus API key for authentication.
​
replica_id
str
required
ID of the Tavus voice replica to use for speech synthesis.
​
persona_id
str
default:"pipecat-stream"
ID of the Tavus persona. Defaults to "pipecat-stream" for Pipecat TTS voice.
​
session
aiohttp.ClientSession
required
Async HTTP session used for communication with Tavus.
​
settings
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 for details.

​
Usage

​
Basic Setup

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

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.