Replica Personas

Create Persona

Create and customize a digital replica’s personality for Conversational Video Interface (CVI). A persona defines the replica’s behavior and capabilities through configurable layers including:

Core Components:

Replica - Choice of audio/visual appearance
Context - Customizable contextual information, for use by LLM
System Prompt - Customizable system prompt, for use by LLM
Layers
- STT - Transcription, and turn taking settings
- LLM - Language model settings
- TTS - Text-to-Speech settings
- VQA - Visual Question Answering settings

When creating a conversation, the persona configuration determines how the replica interacts, processes information, and responds to participants. Each layer can be fine-tuned to achieve the desired conversational experience.

POST

personas

curl --request POST \
  --url https://tavusapi.com/v2/personas \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "persona_name": "Life Coach",
  "system_prompt": "As a Life Coach, you are a dedicated professional who specializes in...",
  "context": "Here are a few times that you have helped an individual make a breakthrough in...",
  "default_replica_id": "r79e1c033f",
  "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",
      "prompt": "What is in this image?"
    },
    "stt": {
      "stt_engine": "tavus-turbo",
      "participant_pause_sensitivity": "low",
      "participant_interrupt_sensitivity": "low",
      "hotwords": "This is a hotword example",
      "smart_turn_detection": true
    }
  }
}'

{
  "persona_id": "p5317866",
  "persona_name": "Life Coach",
  "created_at": "<string>"
}

Authorizations

x-api-key

string

header

required

Body

application/json

persona_name

string

A name for the persona.

system_prompt

string

This is the system prompt that will be used by the llm.

context

string

This is the context that will be used by the llm.

default_replica_id

string

The default replica_id associated with this persona if one exists. When creating a conversation, a persona_id with a default_replica_id associated can we used to create a conversation without specifying a replica_id.

layers

object

layers.llm

object

layers.tts

object

layers.vqa

object

layers.stt

object

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

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

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

layers.stt.hotwords

string

The hotwords that will be used for the STT engine.

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.

How it works:

Continuously evaluates the participant's speech patterns and content
Assesses the likelihood that the participant has finished speaking
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 serves as an initial timeout threshold

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.

Response

200 - application/json

persona_id

string

A unique identifier for the persona.

persona_name

string

The name of the persona.

created_at

string

The date and time the persona was created.

Delete Conversation Get Persona

curl --request POST \
  --url https://tavusapi.com/v2/personas \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "persona_name": "Life Coach",
  "system_prompt": "As a Life Coach, you are a dedicated professional who specializes in...",
  "context": "Here are a few times that you have helped an individual make a breakthrough in...",
  "default_replica_id": "r79e1c033f",
  "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",
      "prompt": "What is in this image?"
    },
    "stt": {
      "stt_engine": "tavus-turbo",
      "participant_pause_sensitivity": "low",
      "participant_interrupt_sensitivity": "low",
      "hotwords": "This is a hotword example",
      "smart_turn_detection": true
    }
  }
}'

{
  "persona_id": "p5317866",
  "persona_name": "Life Coach",
  "created_at": "<string>"
}

Phoenix Replicas

Videos

Conversational Video Interface

Replica Personas

Speech

Create Persona

Authorizations

Body

Response