API Conversation Quickstart

Use this page when you want to create a PAL and start your first Tavus conversation. If you are putting a conversation in your own web app, use CVI App Quickstart, which needs no backend.

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

Step 1: Create a PAL

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

The Anna - Casual Phoenix-4.5 Pro face (rc9cff32ceba).
raven-1 as the perception model for visual and audio understanding.
sparrow-2 for fewer interruptions and graceful handling of backchannels, tuned with high patience to give interview candidates time to think.

rc9cff32ceba is the stock Anna Face ID used throughout these docs. It is a stock ID, not a placeholder. A PAL is what you build in CVI: configure its Face to define how it looks, its Voice to define how it sounds, and its other settings to shape how it thinks and acts.

Use the following request body example:

cURL

curl --request POST \
  --url https://tavusapi.com/v2/pals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "pal_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_face_id": "rc9cff32ceba",
    "layers": {
      "perception": {
        "perception_model": "raven-1"
      },
      "conversational_flow": {
        "turn_detection_model": "sparrow-2",
        "turn_taking_patience": "high",
        "pal_interruptibility": "medium"
      }
    }
  }'

Replace <api_key> with your actual API key. You can generate one in the PAL Maker.

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

Step 2: Create Your Conversation

Create a new conversation using your newly created pal_id:

cURL

curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
  "pal_id": "<your_pal_id>",
  "conversation_name": "Interview User"
}'

Replace <api_key> with your actual API key.
Replace <your_pal_id> with your newly created PAL ID.

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 a web app? Follow CVI App Quickstart to add a conversation with @tavus/embed and no backend. React apps that need full control and want Tavus-provided UI can use the @tavus/cvi-ui component library for CVIProvider, Conversation, hooks, and server helpers.

Getting Started

Guides

Build

Deploy

Debug

Teams & SSO

Resources

API Conversation Quickstart

Step 1: Create a PAL

Step 2: Create Your Conversation

Step 3: Join the Conversation