API Conversation Quickstart

Use this page when you want to create a PAL 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 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:

A Phoenix-4 Pro face.
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.

r90bbd427f71 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": "r90bbd427f71",
    "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 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.

Getting Started

Guides

Build

Deploy

Debug

Resources

API Conversation Quickstart

Step 1: Create a PAL

Step 2: Create Your Conversation

Step 3: Join the Conversation