Use the full pipeline to unlock the complete range of replica capabilities—including perception and speech recognition.

1

Step 1: Get an API Key

  1. Go to the Tavus platform and select API Key from the sidebar menu.
  2. Click Create New Key to begin generating your API key.
  3. Enter a name for the key and (optional) specify allowed IP addresses, then click Create API Key.
  4. Copy your newly created API key and store it securely.

We cannot recover your API Key if you lose it.

2

Step 2: Create a Persona

In this example, we’ll create an interviewer persona with the following settings:

  • A Phoenix-3 stock replica.
  • raven-0 as the perception model to enable screen sharing.
  • smart_turn_detection enabled using the Sparrow model.

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": "rfe12d8b9597",
    "layers": {
      "perception": {
        "perception_model": "raven-0"
      },
      "stt": {
        "stt_engine": "tavus-advanced",
        "smart_turn_detection": true
      }
    }
  }'

Replace <api_key> with your actual API key.

Tavus offers full layer customizations for your persona. Please see the following for each layer configurations:

3

Step 3: Create a 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> and <your_persona_id> with your actual API key and persona_id.

4

Step 4: 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"
}

​
Echo Mode

Tavus also supports an Echo mode pipeline. It lets you send text or audio input directly to the persona for playback, bypassing most of the CVI pipeline.

This mode is not recommended if you plan to use the perception or speech recognition layers, as it is incompatible with them.