Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tavus.io/llms.txt

Use this file to discover all available pages before exploring further.

Use this page when you want to create a persona and start your first Tavus conversation. If you are building a web app that creates conversations from a backend and embeds the returned conversation_url, use CVI App Quickstart.
Use the full pipeline to unlock the complete range of replica capabilities—including perception and speech recognition.
1

Step 1: Create a Persona

In this example, we’ll create an interviewer persona with the following settings:
  • A Phoenix-4 Pro replica.
  • raven-1 as the perception model for visual and audio understanding.
  • sparrow-1 for natural turn-taking with high patience (ideal for interviews).
r90bbd427f71 is the stock Anna replica ID used throughout these docs. It is a stock ID, not a placeholder. A replica controls the face and voice in the call; a persona controls behavior, prompt, context, and conversational configuration.
Use the following request body example:
cURL
curl --request POST \
  --url https://tavusapi.com/v2/personas \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "persona_name": "Interviewer",
    "system_prompt": "As an Interviewer, you are a skilled professional who conducts thoughtful and structured interviews. Your aim is to ask insightful questions, listen carefully, and assess responses objectively to identify the best candidates.",
    "pipeline_mode": "full",
    "context": "You have a track record of conducting interviews that put candidates at ease, draw out their strengths, and help organizations make excellent hiring decisions.",
    "default_replica_id": "r90bbd427f71",
    "layers": {
      "perception": {
        "perception_model": "raven-1"
      },
      "conversational_flow": {
        "turn_detection_model": "sparrow-1",
        "turn_taking_patience": "high",
        "replica_interruptibility": "medium"
      }
    }
  }'
Replace <api_key> with your actual API key. You can generate one in the Developer Portal.
Tavus offers full layer customizations for your persona. Please see the following for each layer configurations:
2

Step 2: Create Your Conversation

Create a new conversation using your newly created persona_id:
cURL
curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
  "persona_id": "<your_persona_id>",
  "conversation_name": "Interview User"
}'
  • Replace <api_key> with your actual API key.
  • Replace <your_persona_id> with your newly created Persona ID.
3

Step 3: Join the Conversation

To join the conversation, click the link in the conversation_url field from the response:
{
  "conversation_id": "c477c9dd7aa6e4fe",
  "conversation_name": "Interview User",
  "conversation_url": "<conversation_link>",
  "status": "active",
  "callback_url": "",
  "created_at": "2025-05-13T06:42:58.291561Z"
}
Building an app around this flow? Follow CVI App Quickstart. React apps that want Tavus-provided UI can use the @tavus/cvi-ui component library for CVIProvider, Conversation, hooks, and server helpers.