Skip to main content
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.
1

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-1 for natural turn-taking with high patience (ideal for interviews).
r90bbd427f71 is the stock Anna Face ID used throughout these docs. It is a stock ID, not a placeholder. A Face defines the on-screen likeness and voice; a PAL defines behavior, knowledge, and pipeline configuration.
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-1",
        "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:
2

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.
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.