Get Persona

GET

personas

{persona_id}

curl --request GET \
  --url https://tavusapi.com/v2/personas/{persona_id} \
  --header 'x-api-key: <api-key>'

{
  "data": [
    {
      "persona_id": "p5317866",
      "persona_name": "Life Coach",
      "system_prompt": "As a Life Coach, you are a dedicated professional who specializes in...",
      "default_replica_id": "r79e1c033f",
      "context": "Here are a few times that you have helped an individual make a breakthrough in...",
      "layers": {
        "llm": {
          "model": "<string>",
          "base_url": "your-base-url",
          "api_key": "your-api-key",
          "tools": [
            {
              "type": "function",
              "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                  "type": "object",
                  "properties": {
                    "location": {
                      "type": "string",
                      "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                      "type": "string",
                      "enum": [
                        "celsius",
                        "fahrenheit"
                      ]
                    }
                  },
                  "required": [
                    "location"
                  ]
                }
              }
            }
          ]
        },
        "tts": {
          "api_key": "your-api-key",
          "tts_engine": "cartesia",
          "external_voice_id": "external-voice-id",
          "voice_settings": {
            "speed": "normal",
            "emotion": [
              "positivity:high",
              "curiosity"
            ]
          },
          "playht_user_id": "your-playht-user-id",
          "tts_emotion_control": "false",
          "tts_model_name": "sonic"
        },
        "perception": {
          "perception_model": "raven-0",
          "ambient_awareness_queries": [
            "Is the user showing an ID card?",
            "Does the user appear distressed or uncomfortable?"
          ],
          "perception_tool_prompt": "You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a form of ID is detected.",
          "perception_tools": [
            {
              "type": "function",
              "function": {
                "name": "notify_if_id_shown",
                "description": "Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask()",
                "parameters": {
                  "type": "object",
                  "properties": {
                    "id_type": {
                      "type": "string",
                      "description": "best guess on what type of ID it is"
                    }
                  },
                  "required": [
                    "id_type"
                  ]
                }
              }
            }
          ]
        },
        "stt": {
          "stt_engine": "tavus-turbo",
          "participant_pause_sensitivity": "low",
          "participant_interrupt_sensitivity": "low",
          "hotwords": "This is a hotword example",
          "smart_turn_detection": true
        }
      },
      "created_at": "",
      "updated_at": "<string>"
    }
  ]
}

Authorizations

x-api-key

string

header

required

Path Parameters

persona_id

string

required

Response

200 - application/json

data

object[]

data.persona_id

string

A unique identifier for the persona.

Example:

"p5317866"

data.persona_name

string

A name for the persona.

Example:

"Life Coach"

data.system_prompt

string

The system prompt that will be used by the llm.

Example:

"As a Life Coach, you are a dedicated professional who specializes in..."

data.default_replica_id

string

The default replica_id associated with this persona if one exists.

Example:

"r79e1c033f"

data.context

string

The context that will be used by the llm.

Example:

"Here are a few times that you have helped an individual make a breakthrough in..."

data.layers

object

data.layers.llm

object

data.layers.llm.model

string

The model name that will be used by the llm.

data.layers.llm.base_url

string

The base URL for the OpenAI compatible endpoint if you are using your own llm.

Example:

"your-base-url"

data.layers.llm.api_key

string

The API key for the OpenAI compatible endpoint if you are using your own llm.

Example:

"your-api-key"

data.layers.llm.tools

any[]

Optional tools to provide to your custom LLM

Example:

[
  {
    "type": "function",
    "function": {
      "name": "get_current_weather",
      "description": "Get the current weather in a given location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"]
      }
    }
  }
]

data.layers.tts

object

data.layers.tts.api_key

string

The custodial API key to be used to make requests to the chosen TTS provider.

Example:

"your-api-key"

data.layers.tts.tts_engine

enum<string>

The TTS engine that will be used.

Available options:

cartesia,

elevenlabs,

playht

data.layers.tts.external_voice_id

string

The voice ID used for the TTS engine when you want to customize your replica's voice. Choose from Cartesia's stock voices by referring to their Voice Catalog, or if you want more options you can consider ElevenLabs or PlayHT.

Example:

"external-voice-id"

data.layers.tts.voice_settings

object

Optional voice settings to be used for the TTS engine. These vary depending on the TTS engine you are using.

Example:

{
  "speed": "normal",
  "emotion": ["positivity:high", "curiosity"]
}

data.layers.tts.playht_user_id

string

The user ID, required if using Playht TTS.

Example:

"your-playht-user-id"

data.layers.tts.tts_emotion_control

boolean

If true, the TTS engine will be able to control the emotion of the voice. Only available for Cartesia TTS.

Example:

"false"

data.layers.tts.tts_model_name

string

The model name that will be used by the TTS engine. Please double check this with the TTS provider you are using to ensure valid model names.

Example:

"sonic"

data.layers.perception

object

data.layers.perception.perception_model

enum<string>

The perception model to use. Options include raven-0 for advanced multimodal perception or basic for simpler vision capabilities, and off to disable all perception.

Available options:

raven-0,

basic,

off

Example:

"raven-0"

data.layers.perception.ambient_awareness_queries

string[]

Custom queries that Raven will continuously monitor for in the visual stream. These provide ambient context without requiring explicit prompting.

Example:

[
  "Is the user showing an ID card?",
  "Does the user appear distressed or uncomfortable?"
]

data.layers.perception.perception_tool_prompt

string

A prompt that details how and when to use the tools that are passed to the perception layer. This helps the replica understand the context of the perception tools and grounds it.

Example:

"You have a tool to notify the system when an ID card is detected, named notify_if_id_shown. You MUST use this tool when a form of ID is detected."

data.layers.perception.perception_tools

object[]

Tools that can be triggered based on visual context, enabling automated actions in response to visual cues.

Example:

[
  {
    "type": "function",
    "function": {
      "name": "notify_if_id_shown",
      "description": "Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask()",
      "parameters": {
        "type": "object",
        "properties": {
          "id_type": {
            "type": "string",
            "description": "best guess on what type of ID it is"
          }
        },
        "required": ["id_type"]
      }
    }
  }
]

data.layers.stt

object

data.layers.stt.stt_engine

enum<string>

The STT engine that will be used. tavus-turbo is our lowest-latency model, but tavus-advanced provides higher transcription accuracy. Please note that non-English languages will default to tavus-advanced if not specified.

Available options:

tavus-turbo,

tavus-advanced

data.layers.stt.participant_pause_sensitivity

enum<string>

Use this parameter to control how long of a pause you can take before the replica will respond to you. See more details here. The default is medium, but you can adjust this to low or high depending on your needs.

Available options:

low,

medium,

high

data.layers.stt.participant_interrupt_sensitivity

enum<string>

Use this parameter to control how long you can speak before the replica will be interrupted by you. See more details here. The default is medium, but you can adjust this to low or high depending on your needs.

Available options:

low,

medium,

high

data.layers.stt.hotwords

string

The hotwords that will be used for the STT engine.

Example:

"This is a hotword example"

data.layers.stt.smart_turn_detection

boolean

Smart Turn Detection enhances the natural flow of conversation between participants and digital replicas. This intelligent system uses lexical and semantic analysis to determine the optimal moment for the digital replica to respond. The default value is set to true.

How it works:

Continuously evaluates the participant's speech patterns and content
Assesses the likelihood that the participant has finished speaking
Multilingual, support for 100 languages
Works seamlessly with both speculative and non-speculative inference,
Continuously uses participant speech patterns and content to determine how long to wait to respond.
Works in conjunction with the participant_pause_sensitivity setting, which adjusts the maximum pause for when participant is clearly not done.

Key benefits:

Rapid response: Triggers quick replies when the participant has definitively concluded their statement.
Extended listening: Allows more time when the participant is clearly in the middle of expressing a thought.

Enabling Smart Turn Detection creates a more natural and engaging conversational experience, allowing the digital replica to interact more seamlessly with human participants.

data.created_at

string

The date and time the persona was created.

Example:

""

data.updated_at

string

The date and time of when the persona was last updated.

Create Persona List Personas

curl --request GET \
  --url https://tavusapi.com/v2/personas/{persona_id} \
  --header 'x-api-key: <api-key>'

{
  "data": [
    {
      "persona_id": "p5317866",
      "persona_name": "Life Coach",
      "system_prompt": "As a Life Coach, you are a dedicated professional who specializes in...",
      "default_replica_id": "r79e1c033f",
      "context": "Here are a few times that you have helped an individual make a breakthrough in...",
      "layers": {
        "llm": {
          "model": "<string>",
          "base_url": "your-base-url",
          "api_key": "your-api-key",
          "tools": [
            {
              "type": "function",
              "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                  "type": "object",
                  "properties": {
                    "location": {
                      "type": "string",
                      "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                      "type": "string",
                      "enum": [
                        "celsius",
                        "fahrenheit"
                      ]
                    }
                  },
                  "required": [
                    "location"
                  ]
                }
              }
            }
          ]
        },
        "tts": {
          "api_key": "your-api-key",
          "tts_engine": "cartesia",
          "external_voice_id": "external-voice-id",
          "voice_settings": {
            "speed": "normal",
            "emotion": [
              "positivity:high",
              "curiosity"
            ]
          },
          "playht_user_id": "your-playht-user-id",
          "tts_emotion_control": "false",
          "tts_model_name": "sonic"
        },
        "perception": {
          "perception_model": "raven-0",
          "ambient_awareness_queries": [
            "Is the user showing an ID card?",
            "Does the user appear distressed or uncomfortable?"
          ],
          "perception_tool_prompt": "You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a form of ID is detected.",
          "perception_tools": [
            {
              "type": "function",
              "function": {
                "name": "notify_if_id_shown",
                "description": "Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask()",
                "parameters": {
                  "type": "object",
                  "properties": {
                    "id_type": {
                      "type": "string",
                      "description": "best guess on what type of ID it is"
                    }
                  },
                  "required": [
                    "id_type"
                  ]
                }
              }
            }
          ]
        },
        "stt": {
          "stt_engine": "tavus-turbo",
          "participant_pause_sensitivity": "low",
          "participant_interrupt_sensitivity": "low",
          "hotwords": "This is a hotword example",
          "smart_turn_detection": true
        }
      },
      "created_at": "",
      "updated_at": "<string>"
    }
  ]
}

Phoenix Replicas

Videos

Conversational Video Interface

Replica Personas

Speech

Authorizations

Path Parameters

Response