Skip to main content

​
Create a Persona

1

Step 1: Get an API Key

  1. Go to the Developer Portal 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-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/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": "rf4e9d9790f0",
    "layers": {
      "perception": {
        "perception_model": "raven-1",
      },
      "conversational_flow": {
        "turn_detection_model": "sparrow-1",
        "turn_taking_patience": "medium",
        "replica_interruptibility": "medium"
      }
    }
  }'
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_created_persona_id>",
  "conversation_name": "Interview User"
}'
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"
}

​
Modify Existing Persona

Tavus lets you update any existing persona configuration using standard JSON Patch operations (add, replace, remove).
Please see the Patch Persona endpoint for more details.
curl --request PATCH \
  --url https://tavusapi.com/v2/personas/{persona_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '[
    {
      "op": "add",
      "path": "/layers/stt/hotwords",
      "value": "leadership"
    }
  ]'