Phoenix Replicas
Conversational Video Interface
Replica Personas
List Personas
This endpoint returns a list of all Personas created by the account associated with the API Key in use.
curl --request GET \
--url https://tavusapi.com/v2/personas \
--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"
},
"vqa": {
"enable_vision": "false"
},
"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>"
}
],
"total_count": 123
}Authorizations
Query Parameters
The number of personas to return per page. Default is 10.
The page number to return. Default is 1.
Filter the personas by type. Possible values: user, system. System personas are personas that have been created by Tavus.
user, system Response
A unique identifier for the persona.
A name for the persona.
The system prompt that will be used by the llm.
The default replica_id associated with this persona if one exists.
The context that will be used by the llm.
The model name that will be used by the llm.
The base URL for the OpenAI compatible endpoint if you are using your own llm.
The API key for the OpenAI compatible endpoint if you are using your own llm.
Optional tools to provide to your custom LLM
The custodial API key to be used to make requests to the chosen TTS provider.
The TTS engine that will be used.
cartesia, elevenlabs, playht 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.
Optional voice settings to be used for the TTS engine. These vary depending on the TTS engine you are using.
The user ID, required if using Playht TTS.
If true, the TTS engine will be able to control the emotion of the voice. Only available for Cartesia TTS.
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.
If true, the persona will have the ability to implement visual context.
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.
tavus-turbo, tavus-advanced 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.
low, medium, high 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.
low, medium, high The hotwords that will be used for the STT engine.
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 date and time the persona was created.
The date and time of when the persona was last updated.
The total number of personas given the filters provided.
curl --request GET \
--url https://tavusapi.com/v2/personas \
--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"
},
"vqa": {
"enable_vision": "false"
},
"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>"
}
],
"total_count": 123
}