RolePilot
Powered by GOLS EdTech
← Back to App
đŸŽŦ

Tavus CVI Setup Guide

Enable live video roleplay with a photorealistic AI avatar that speaks, listens, and reacts in real time — powered by Tavus Conversational Video Interface (CVI).

5-min setup Photorealistic Avatar Real-time Voice In-browser
How it works
RolePilot
Frontend
Browser
→
FastAPI
Backend
Your Server
→
Tavus CVI
API
tavusapi.com
→
iframe
video call
Embedded

When a learner clicks Video AI, the frontend calls your backend which calls the Tavus API to create a conversation. Tavus returns a conversation_url that gets embedded as an iframe. The avatar speaks in real time, hears the learner's mic, and stays in character using the scenario's system prompt.

Setup Steps
1
Get your Tavus API Key
Free tier available — no credit card required to test

Sign up or log in at platform.tavus.io →

Go to Settings → API Keys and create a new key. Copy it — you'll need it in Step 2.

💡
Tavus free tier includes a few hours of video per month, which is plenty for testing and demos. Upgrade when you go to production.
2
Add credentials to your .env
All keys live in .env — never hardcoded

Open your .env file (copy from .env.example if you haven't already) and set:

.envTAVUS_API_KEY=tvs_xxxxxxxxxxxxxxxxxxxxxxxx TAVUS_REPLICA_ID=rf4e9d9790f0 # see Step 3 TAVUS_PERSONA_ID= # optional, see Step 4 TAVUS_BASE_URL=https://tavusapi.com/v2 # don't change
⚠ī¸
Never commit .env to git. It's already in .gitignore. Use environment variables or a secrets manager in production.
3
Choose a Replica (Avatar)
The digital human that appears in video sessions

A Replica is the photorealistic avatar model. You can use:

  • Tavus stock replicas — available immediately, find IDs in your dashboard at platform.tavus.io/replicas →
  • Custom replica — record a 2-minute video of yourself, Tavus clones it in ~1 hour. Best for branded training.

Copy the replica_id (format: rf<hex>) and paste it as TAVUS_REPLICA_ID in your .env.

You can also set a per-scenario replica by storing tavus_replica_id on the scenario record in the admin panel.

ℹī¸
The default replica ID in .env.example (rf4e9d9790f0) is Tavus's public demo replica — it works but has limited daily minutes. Replace it with your own replica for production.
4
(Optional) Pre-create Personas for faster starts
Saves ~1s per session — recommended for production

A Persona holds the system prompt (scenario context, character personality, rules). You can create one per scenario so that starting a video session is instant.

After adding a scenario in the admin panel, call:

Terminal / curlcurl -X POST https://your-domain/api/tavus/create-persona \ -H "Authorization: Bearer <your-jwt>" \ -H "Content-Type: application/json" \ -d '{"scenario_id": "<scenario-uuid>"}'

The persona ID is automatically saved on the scenario and used for all future video sessions for that scenario.

If no persona is pre-created, the system prompt is passed inline per session — slightly slower but fully functional.

5
Restart the server and test
The change takes effect immediately on restart

Restart RolePilot:

Terminalpython run.py

Then:

  • Open a scenario → Lobby
  • Select đŸŽŦ AI Video Roleplay
  • Click Begin Role Play
  • Allow camera + microphone when the browser asks
  • The avatar should appear in the iframe within a few seconds
✅
If it works, the avatar will greet you in character. If you see the error screen instead, check the browser console — the error message from the backend will tell you exactly what's wrong (wrong key, wrong replica ID, rate limit, etc.).
6
(Optional) Set up the Webhook for transcripts
Get conversation transcripts and trigger AI reports automatically

Register your webhook in the Tavus dashboard under Settings → Webhooks:

https://your-domain.com/api/tavus/webhook

Tavus will POST to this URL when a video session ends, sending the full transcript. RolePilot's /api/tavus/webhook handler receives this and can trigger the AI report generation.

⚠ī¸
Webhooks require your server to be publicly accessible. For local testing, use a tunnel like ngrok: ngrok http 8000
Troubleshooting / FAQ
The video iframe shows a loading spinner forever
Check the browser console for errors. Common causes: (1) TAVUS_API_KEY is not set or invalid — check your .env; (2) TAVUS_REPLICA_ID doesn't exist in your account; (3) The replica has no minutes remaining on the free plan.
I see "Tavus CVI is not configured" in the error panel
The TAVUS_API_KEY environment variable is empty. Open your .env file and add it, then restart the server with python run.py.
HTTP 502 from /api/tavus/start-session
The Tavus API returned an error. The full Tavus response is included in the error message in the browser console. Most common: (1) invalid API key; (2) replica_id not found in your account; (3) rate limit exceeded on the free plan.
Camera/microphone not working inside the iframe
The Tavus iframe needs explicit permissions. The <iframe> tag in session.html already includes allow="camera; microphone; autoplay; display-capture". If it still doesn't work, check your browser's site permissions — some browsers require HTTPS for camera access. Use a local HTTPS proxy or deploy to a domain with TLS.
Can I use a different AI voice / language?
Yes. Tavus uses its own TTS tied to the replica. For language, set the scenario's language in the admin panel — the system prompt passed to Tavus will instruct the persona to speak in that language. Custom voices require a custom replica trained on voice samples.
How does video mode differ from voice mode?
Voice mode uses OpenAI TTS + WebSocket — the AI text + audio streams through your server. Video mode embeds Tavus's CVI directly as an iframe — Tavus handles everything (STT, LLM, TTS, avatar rendering) peer-to-peer. Video mode has richer presence but session reports require the webhook integration to capture the transcript.
🔗 Open Tavus Dashboard 📖 Tavus Full Docs ⚙ī¸ RolePilot Admin ← Back to App