Quickstart

Create a PAL

Step 1: Get an API Key

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

We cannot recover your API Key if you lose it.

Step 2: Create a PAL

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

A Phoenix-3 stock face.
raven-1 as the perception model to enable screen sharing.
Conversational Flow layer with Sparrow-1 for turn detection.

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": "medium",
        "pal_interruptibility": "medium"
      }
    }
  }'

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

Step 3: Create a 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"
}'

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"
}

Modify Existing PAL

Tavus lets you update any existing PAL configuration using standard JSON Patch operations (add, replace, remove).

Please see the Patch PAL endpoint for more details.

curl --request PATCH \
  --url https://tavusapi.com/v2/pals/{pal_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '[
    {
      "op": "add",
      "path": "/layers/stt/hotwords",
      "value": "leadership"
    }
  ]'

curl --request PATCH \
  --url https://tavusapi.com/v2/pals/{pal_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '[
    {
      "op": "replace",
      "path": "/layers/stt/stt_engine",
      "value": "tavus-auto"
    }
  ]'

curl --request PATCH \
  --url https://tavusapi.com/v2/pals/{pal_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '[
    {
      "op": "remove",
      "path": "/layers/conversational_flow/turn_taking_patience"
    }
  ]'

⌘I

Getting Started

Build

Deploy

Debug

Guides

Resources

Create a PAL

Step 1: Get an API Key

Step 2: Create a PAL

Step 3: Create a Conversation

Step 4: Join the Conversation

Modify Existing PAL

​Create a PAL

Step 1: Get an API Key

Step 2: Create a PAL

Step 3: Create a Conversation

Step 4: Join the Conversation

​Modify Existing PAL

Create a PAL

Modify Existing PAL