openapi: 3.0.3 info: title: Tavus Developer API Collection Conversations Personas API version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Personas paths: /v2/personas: post: tags: - Personas summary: Create Persona description: Creates a persona that configures how a replica behaves and sounds in CVI for every conversation that uses that persona. operationId: createPersona requestBody: content: application/json: schema: type: object properties: persona_name: type: string description: A name for the persona. example: Life Coach system_prompt: type: string description: This is the system prompt that will be used by the llm. **Each request must have a `system_prompt` value unless you're using echo mode**. example: As a Life Coach, you are a dedicated professional who specializes in... pipeline_mode: type: string description: 'The pipeline mode to use for the persona. Possible values: `full`, `echo`. `full` will provide the default end-to-end experience. `echo` will turn off most steps, and allow the replica to sync video with audio passed in through Echo events, which it will speak out.' enum: - full - echo default_replica_id: type: string description: 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. example: r90bbd427f71 document_ids: type: array description: Array of document IDs that the persona will have access to. These documents will be available to the persona in all their conversations. The `document_ids` are returned in the response of the [Get Document](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints. items: type: string example: - d1234567890 - d2468101214 document_tags: type: array description: Array of document tags that the persona will have access to. Documents matching these tags will be available to the persona in all their conversations. The tags are passed in the `document_tags` parameter of the [Create Document](/api-reference/documents/create-document) endpoint. As soon as one document has the tag, you will be able to pass the tags in this parameter.. items: type: string example: - product_info - company_policies objectives_id: type: string description: The unique identifier of the objectives to attach to this persona. Objectives provide goal-oriented instructions that help guide conversations toward specific outcomes. Create objectives using the [Create Objectives](/api-reference/objectives/create-objectives) endpoint. example: o12345 guardrails_id: type: string description: The unique identifier of the guardrails to attach to this persona. Guardrails provide strict behavioral boundaries and guidelines that will be rigorously followed throughout conversations. Create guardrails using the [Create Guardrails](/api-reference/guardrails/create-guardrails) endpoint. example: g12345 layers: type: object description: 'Optional nested settings for each CVI pipeline layer (perception, STT, conversational flow, LLM, TTS). For an overview of what each layer controls, see [Persona overview — CVI layers](/sections/conversational-video-interface/persona/overview#cvi-layer). ' properties: perception: type: object properties: perception_model: type: string description: The perception model to use. `raven-1` (default and recommended) provides real-time emotional understanding from user audio, more natural and human-like interactions, plus all visual capabilities from raven-0. `raven-0` (legacy settings [here](/sections/troubleshooting#migration-from-legacy-perception-to-raven-1)) offers advanced visual perception only. `off` disables all perception. enum: - raven-1 - raven-0 - 'off' default: raven-1 example: raven-1 visual_awareness_queries: type: array description: Custom queries that Raven continuously monitors in the visual stream. These provide ambient visual context without requiring explicit prompting. items: type: string example: - Is the user showing an ID card? - Does the user appear distressed or uncomfortable? visual_tool_prompt: type: string description: A prompt that details how and when to use visual tools based on what Raven sees. This helps the replica understand the context of the visual tools. 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. visual_tools: type: array description: Tools that can be triggered based on visual context, enabling automated actions in response to visual cues. items: type: object properties: name: type: string description: The name of the tool to be called. description: type: string description: A description of what the tool does and when it should be called. 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 audio_awareness_queries: type: array description: Custom queries that Raven-1 continuously monitors in the audio stream. These provide ambient audio context such as user tone and emotional state. Only available with `raven-1`. items: type: string example: - Does the user sound frustrated or confused? - Is the user speaking quickly as if in a hurry? audio_tool_prompt: type: string description: A prompt that details how and when to use audio tools based on what Raven-1 hears. Only available with `raven-1`. example: You have a tool to escalate to a human agent when the user sounds very frustrated, named `escalate_to_human`. Use this tool when detecting sustained frustration. audio_tools: type: array description: Tools that can be triggered based on audio analysis, enabling automated actions in response to user tone and emotion. Only available with `raven-1`. items: type: object properties: name: type: string description: The name of the tool to be called. description: type: string description: A description of what the tool does and when it should be called. example: - type: function function: name: escalate_to_human description: Escalate the conversation to a human agent when user frustration is detected parameters: type: object properties: reason: type: string description: The reason for escalation required: - reason stt: type: object description: '**Note**: Turn-taking is now configured on the [Conversational Flow layer](/sections/conversational-video-interface/persona/conversational-flow). ' properties: stt_engine: type: string description: The STT engine used for transcription. `tavus-auto` (default, recommended) automatically selects the best model for the conversation's language. `tavus-parakeet` offers highest throughput and lowest latency for English and European languages. `tavus-soniox` is purpose-built for Indian languages with broad multilingual coverage. `tavus-whisper` provides broad multilingual coverage across all supported languages. `tavus-deepgram-medical` is domain-specific English STT optimized for clinical and healthcare vocabulary. `tavus-advanced` is deprecated and not recommended for new integrations. See the [STT layer documentation](/sections/conversational-video-interface/persona/stt) for details. enum: - tavus-auto - tavus-parakeet - tavus-soniox - tavus-whisper - tavus-deepgram-medical - tavus-advanced default: tavus-auto example: tavus-auto hotwords: type: string description: 'The hotwords parameter lets you provide example phrases that guide the STT model to prioritize certain words or phrases—especially names, technical terms, or uncommon language. For instance, including "Roey is the name of the person you''re speaking with" helps the model transcribe "Roey" correctly instead of "Rowie." ' example: Roey is the name of the person you're speaking with. conversational_flow: type: object description: Controls conversational flow dynamics for the replica. When not explicitly provided, all fields default to None (turned off). If any parameter is provided, sensible defaults are applied to all other parameters. See more details [here](/sections/conversational-video-interface/persona/conversational-flow). properties: turn_detection_model: type: string description: The model used for turn detection. Options include `sparrow-1` (recommended) for advanced turn detection that is faster, more accurate, and more natural, and `sparrow-0` (legacy) for standard turn detection. Default is `sparrow-1` when any conversational flow parameter is provided. enum: - sparrow-1 - sparrow-0 example: sparrow-1 turn_taking_patience: type: string description: Controls how eagerly and quickly the replica claims conversational turns. Affects both response latency and likelihood of interrupting during natural pauses. `low` = eager and quick to respond, may interrupt pauses; `medium` (default) = balanced; `high` = patient, waits for clear turn completion. enum: - low - medium - high example: medium replica_interruptibility: type: string description: Controls how sensitive the replica is to user speech while the replica is talking. Determines whether the replica stops to listen or keeps speaking. `low` = keeps talking, less interruptible; `medium` (default) = balanced; `high` = stops easily, more interruptible. enum: - low - medium - high example: medium voice_isolation: type: string description: Controls the voice isolation model used on participant audio. Voice isolation separates speech from background noise in the participant's microphone audio. `near` (default) = separates speech from background noise for scenarios where the user is less than 1 meter away from the microphone; `off` = no voice isolation, raw audio is sent down the conversational pipeline. Default is `near`. enum: - 'off' - near default: near example: near wake_phrase: type: string description: A specific phrase the persona listens for before responding. When set, the persona remains silent until it hears the wake phrase, similar to a voice assistant. The persona still records all user utterances in the transcript so it has full conversation context when it does respond. Choose a phrase that is unique enough to avoid over-triggering (avoid generic greetings like `Hey`). Default is `None` (disabled). example: Hey Siri idle_engagement: type: string description: Controls whether the replica proactively re-engages the user after a stretch of silence, and how eagerly. `off` (default) = the replica never breaks silence; `patient` = re-engages after longer silences, suited to tutors or contemplative use cases; `eager` = re-engages after shorter silences, suited to SDR or sales-style use cases. enum: - 'off' - patient - eager default: 'off' example: 'off' llm: type: object properties: model: type: string description: 'The model name that will be used by the LLM. **tavus-gpt-oss** is recommended as a good starting point. Other Tavus-hosted options include tavus-gemini-2.5-flash, tavus-claude-haiku-4.5, tavus-gpt-5.2, and tavus-gemini-3-flash. See the [LLM layer documentation](/sections/conversational-video-interface/persona/llm) for a full comparison. For your own OpenAI-compatible LLM, provide a `model`, `base_url`, and `api_key`. **Context window:** Performance and intelligence are best when prompts are limited to 5,000 tokens. Degradations in speed and instruction following may occur in the 15,000–20,000 token range. Tavus-hosted models support up to 32,000 tokens. Tip: 1 token ≈ 4 characters. ' base_url: type: string description: The base url for your OpenAI compatible endpoint. example: your-base-url api_key: type: string description: The API key for the OpenAI compatible endpoint. example: your-api-key speculative_inference: type: boolean description: When set to `true`, the LLM begins processing speech transcriptions before user input ends, improving responsiveness. Default is `true`. example: true default: true tools: type: array description: Optional tools to provide to your custom LLM - click [here](/sections/conversational-video-interface/persona/llm-tool) for more details. 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 headers: type: object description: Optional headers to provide to your custom LLM example: Authorization: Bearer your-api-key extra_body: type: object description: "Optional parameters to customize the LLM request. \n\nFor Tavus-hosted models, you can pass `temperature` and `top_p`:\n- `temperature`: Controls randomness in the model's output. Range typically 0.0 to 2.0. Lower values make output more deterministic and focused, higher values make it more creative and varied.\n- `top_p`: Controls diversity via nucleus sampling. Range 0.0 to 1.0. Lower values make output more focused on high-probability tokens, higher values allow more diverse token selection.\n\nFor custom LLMs, you can pass any parameters that your LLM provider supports (e.g., `temperature`, `top_p`, `frequency_penalty`, etc.).\n" example: temperature: 0.7 top_p: 0.9 tts: type: object properties: api_key: type: string description: 'The API key for the chosen TTS provider. Only required when using private voices. **ElevenLabs:** When using pronunciation dictionaries with your own ElevenLabs key, the key must have the `pronunciation_dictionaries_write` scope (or full account access). See [ElevenLabs API key scopes](https://elevenlabs.io/docs/api-reference/service-accounts/api-keys/create). **Cartesia:** No additional scope required — any valid Cartesia API key works. ' example: your-api-key tts_engine: type: string description: The TTS engine that will be used. enum: - cartesia - elevenlabs external_voice_id: type: string description: 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](https://docs.cartesia.ai/api-reference/voices/list), or if you want more options you can consider [ElevenLabs](https://elevenlabs.io/docs/api-reference/voices/get-all). example: external-voice-id voice_settings: type: object description: 'Optional voice settings to customize TTS behavior. For Cartesia we support inline Cartesia SSML settings (https://docs.cartesia.ai/build-with-cartesia/sonic-3/ssml-tags). For ElevenLabs we support: `speed` (0.7–1.2), `stability` (0.0–1.0), `similarity_boost` (0.0–1.0), `style` (0.0–1.0), `use_speaker_boost` (boolean). See [ElevenLabs Voice Settings](https://elevenlabs.io/docs/api-reference/voices/settings/get). ' example: speed: 0.5 emotion: - positivity:high - curiosity tts_emotion_control: type: boolean description: When true, Tavus automatically handles LLM prompting for emotion tags, enabling expressive vocal delivery and natural emotional facial movements (only available with Phoenix-4 replicas). Defaults to true. example: true default: true tts_model_name: type: string description: 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-3 pronunciation_dictionary_id: type: string description: 'The unique identifier of a Tavus pronunciation dictionary to attach to this persona. Tavus will apply the dictionary''s rules at conversation time. Provider-specific dictionary IDs are managed internally by Tavus and are not exposed in GET responses — only this field is visible. ' example: pd_abc123def456 examples: Required Parameters Only: value: pipeline_mode: full system_prompt: As a Life Coach, you are a dedicated professional who specializes in... Full Customizations: value: persona_name: Life Coach system_prompt: As a Life Coach, you are a dedicated professional who specializes in... pipeline_mode: full default_replica_id: r90bbd427f71 layers: llm: model: tavus-gpt-oss speculative_inference: true tools: - type: function function: name: life_coach_insight description: Offer personalized life coaching advice or guidance based on a user's challenge or goal. parameters: type: object properties: topic: type: string description: The area of life or goal the user wants to improve (e.g. career, relationships, confidence) urgency_level: type: string enum: - low - medium - high required: - topic tts: tts_engine: cartesia voice_settings: speed: normal emotion: - positivity:high - curiosity tts_emotion_control: true tts_model_name: sonic-3 perception: perception_model: raven-1 visual_awareness_queries: - Is the user showing an ID card? - Does the user appear distressed or uncomfortable? visual_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. visual_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 audio_awareness_queries: - Does the user sound frustrated or confused? stt: stt_engine: tavus-auto conversational_flow: turn_detection_model: sparrow-1 turn_taking_patience: medium turn_commitment: medium replica_interruptibility: high voice_isolation: near idle_engagement: 'off' document_ids: - d1234567890 - d2468101214 document_tags: - product_info - company_policies responses: '200': description: '' content: application/json: schema: type: object properties: persona_id: type: string description: A unique identifier for the persona. example: pcb7a34da5fe persona_name: type: string description: The name of the persona. example: Life Coach created_at: type: string description: The date and time the persona was created. '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid replica_uuid '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid access token security: - apiKey: [] get: tags: - Personas summary: List Personas description: 'This endpoint returns a list of all Personas created by the account associated with the API Key in use. ' operationId: listPersonas parameters: - in: query name: limit schema: type: integer description: The number of personas to return per page. Default is 10. - in: query name: page schema: type: integer description: The page number to return. Default is 1. - in: query name: persona_type schema: type: string description: 'Filter the personas by type. Possible values: user, system. System personas are personas that have been created by Tavus.' enum: - user - system responses: '200': description: '' content: application/json: schema: type: object properties: data: type: array description: Personas for the current page; use `total_count` for the full count under the applied filters. items: type: object properties: persona_id: type: string description: A unique identifier for the persona. example: pcb7a34da5fe persona_name: type: string description: A name for the persona. example: Life Coach system_prompt: type: string description: The system prompt that will be used by the llm. example: As a Life Coach, you are a dedicated professional who specializes in... default_replica_id: type: string example: r90bbd427f71 description: The default replica_id associated with this persona if one exists. document_ids: type: array description: Array of document IDs that the persona has access to. These documents will be available to the persona in all their conversations. The document_ids are returned in the response of the [Get Document](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints. items: type: string example: - d1234567890 - d2468101214 document_tags: type: array description: Array of document tags that the persona has access to. Documents matching these tags will be available to the persona in all their conversations. items: type: string example: - product_info - company_policies layers: type: object properties: llm: type: object properties: model: type: string description: The model name that will be used by the llm. base_url: type: string description: The base URL for the OpenAI compatible endpoint if you are using your own llm. example: your-base-url api_key: type: string description: The API key for the OpenAI compatible endpoint if you are using your own llm. example: your-api-key tools: type: array description: 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 tts: type: object properties: api_key: type: string description: 'The API key for the chosen TTS provider. Only required when using private voices. **ElevenLabs:** When using pronunciation dictionaries with your own ElevenLabs key, the key must have the `pronunciation_dictionaries_write` scope (or full account access). See [ElevenLabs API key scopes](https://elevenlabs.io/docs/api-reference/service-accounts/api-keys/create). ' example: your-api-key tts_engine: type: string description: The TTS engine that will be used. enum: - cartesia - elevenlabs external_voice_id: type: string description: 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](https://docs.cartesia.ai/api-reference/voices/list), or if you want more options you can consider [ElevenLabs](https://elevenlabs.io/docs/api-reference/voices/get-all). example: external-voice-id voice_settings: type: object description: 'Optional voice settings to customize TTS behavior. For Cartesia we support inline Cartesia SSML settings (https://docs.cartesia.ai/build-with-cartesia/sonic-3/ssml-tags). For ElevenLabs we support: speed (0.7–1.2), stability (0.0–1.0), similarity_boost (0.0–1.0), style (0.0–1.0), use_speaker_boost (boolean). See https://elevenlabs.io/docs/api-reference/voices/settings/get. ' example: speed: 0.5 emotion: - positivity:high - curiosity tts_emotion_control: type: boolean description: If true, the TTS engine will be able to control the emotion of the voice. Defaults to true. example: true default: true tts_model_name: type: string description: 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-3 pronunciation_dictionary_id: type: string description: The unique identifier of the Tavus pronunciation dictionary attached to this persona, if any. Provider-specific dictionary IDs are managed internally and are not exposed. example: pd_abc123def456 perception: type: object properties: perception_model: type: string description: The perception model to use. `raven-1` (default and recommended) provides real-time emotional understanding from user audio, more natural and human-like interactions, plus all visual capabilities from raven-0. `raven-0` (legacy settings [here](/sections/troubleshooting#migration-from-legacy-perception-to-raven-1)) offers advanced visual perception only. `off` disables all perception. enum: - raven-1 - raven-0 - 'off' default: raven-1 example: raven-1 visual_awareness_queries: type: array description: Custom queries that Raven continuously monitors in the visual stream. These provide ambient visual context without requiring explicit prompting. items: type: string example: - Is the user showing an ID card? - Does the user appear distressed or uncomfortable? visual_tool_prompt: type: string description: A prompt that details how and when to use visual tools based on what Raven sees. This helps the replica understand the context of the visual tools. 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. visual_tools: type: array description: Tools that can be triggered based on visual context, enabling automated actions in response to visual cues. items: type: object properties: name: type: string description: The name of the tool to be called. description: type: string description: A description of what the tool does and when it should be called. 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 audio_awareness_queries: type: array description: Custom queries that Raven-1 continuously monitors in the audio stream. These provide ambient audio context such as user tone and emotional state. Only available with `raven-1`. items: type: string example: - Does the user sound frustrated or confused? - Is the user speaking quickly as if in a hurry? audio_tool_prompt: type: string description: A prompt that details how and when to use audio tools based on what Raven-1 hears. Only available with `raven-1`. example: You have a tool to escalate to a human agent when the user sounds very frustrated, named `escalate_to_human`. Use this tool when detecting sustained frustration. audio_tools: type: array description: Tools that can be triggered based on audio analysis, enabling automated actions in response to user tone and emotion. Only available with `raven-1`. items: type: object properties: name: type: string description: The name of the tool to be called. description: type: string description: A description of what the tool does and when it should be called. example: - type: function function: name: escalate_to_human description: Escalate the conversation to a human agent when user frustration is detected parameters: type: object properties: reason: type: string description: The reason for escalation required: - reason stt: type: object description: '**Note**: Turn-taking is now configured on the [Conversational Flow layer](/sections/conversational-video-interface/persona/conversational-flow). ' properties: stt_engine: type: string description: The STT engine used for transcription. `tavus-auto` (default, recommended) automatically selects the best model. `tavus-parakeet` offers highest throughput for English and European languages. `tavus-soniox` is purpose-built for Indian languages. `tavus-whisper` provides broad multilingual coverage. `tavus-deepgram-medical` is optimized for clinical vocabulary (English only). `tavus-advanced` is deprecated. enum: - tavus-auto - tavus-parakeet - tavus-soniox - tavus-whisper - tavus-deepgram-medical - tavus-advanced default: tavus-auto example: tavus-auto hotwords: type: string description: The hotwords that will be used for the STT engine. example: This is a hotword example created_at: type: string description: The date and time the persona was created. example: '' updated_at: type: string description: The date and time of when the persona was last updated. total_count: type: integer description: The total number of personas given the filters provided. '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid access token security: - apiKey: [] /v2/personas/{persona_id}: parameters: - name: persona_id in: path required: true description: The unique identifier of the persona. schema: type: string example: pcb7a34da5fe get: tags: - Personas summary: Get Persona description: 'This endpoint returns a single persona by its unique identifier. ' operationId: getPersona responses: '200': description: '' content: application/json: schema: type: object properties: data: type: array items: type: object properties: persona_id: type: string description: A unique identifier for the persona. example: pcb7a34da5fe persona_name: type: string description: A name for the persona. example: Life Coach system_prompt: type: string description: The system prompt that will be used by the llm. example: As a Life Coach, you are a dedicated professional who specializes in... default_replica_id: type: string example: r90bbd427f71 description: The default replica_id associated with this persona if one exists. document_ids: type: array description: Array of document IDs that the persona has access to. These documents will be available to the persona in all their conversations. The document_ids are returned in the response of the [Get Document](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints. items: type: string example: - d1234567890 - d2468101214 document_tags: type: array description: Array of document tags that the persona has access to. Documents matching these tags will be available to the persona in all their conversations. items: type: string example: - product_info - company_policies layers: type: object properties: llm: type: object properties: model: type: string description: The model name that will be used by the llm. base_url: type: string description: The base URL for the OpenAI compatible endpoint if you are using your own llm. example: your-base-url api_key: type: string description: The API key for the OpenAI compatible endpoint if you are using your own llm. example: your-api-key tools: type: array description: 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 headers: type: object description: Optional headers to provide to your custom LLM example: Authorization: Bearer your-api-key extra_body: type: object description: "Optional parameters to customize the LLM request. \n\nFor Tavus-hosted models, you can pass `temperature` and `top_p`:\n- `temperature`: Controls randomness in the model's output. Range typically 0.0 to 2.0. Lower values make output more deterministic and focused, higher values make it more creative and varied.\n- `top_p`: Controls diversity via nucleus sampling. Range 0.0 to 1.0. Lower values make output more focused on high-probability tokens, higher values allow more diverse token selection.\n\nFor custom LLMs, you can pass any parameters that your LLM provider supports (e.g., `temperature`, `top_p`, `frequency_penalty`, etc.).\n" example: temperature: 0.7 top_p: 0.9 tts: type: object properties: api_key: type: string description: 'The API key for the chosen TTS provider. Only required when using private voices. **ElevenLabs:** When using pronunciation dictionaries with your own ElevenLabs key, the key must have the `pronunciation_dictionaries_write` scope (or full account access). See [ElevenLabs API key scopes](https://elevenlabs.io/docs/api-reference/service-accounts/api-keys/create). ' example: your-api-key tts_engine: type: string description: The TTS engine that will be used. enum: - cartesia - elevenlabs external_voice_id: type: string description: 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](https://docs.cartesia.ai/api-reference/voices/list), or if you want more options you can consider [ElevenLabs](https://elevenlabs.io/docs/api-reference/voices/get-all). example: external-voice-id voice_settings: type: object description: 'Optional voice settings to customize TTS behavior. For Cartesia we support inline Cartesia SSML settings (https://docs.cartesia.ai/build-with-cartesia/sonic-3/ssml-tags). For ElevenLabs we support: speed (0.7–1.2), stability (0.0–1.0), similarity_boost (0.0–1.0), style (0.0–1.0), use_speaker_boost (boolean). See https://elevenlabs.io/docs/api-reference/voices/settings/get. ' example: speed: 0.5 emotion: - positivity:high - curiosity tts_emotion_control: type: boolean description: If true, the TTS engine will be able to control the emotion of the voice. Defaults to true. example: true default: true tts_model_name: type: string description: 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-3 pronunciation_dictionary_id: type: string description: The unique identifier of the Tavus pronunciation dictionary attached to this persona, if any. Provider-specific dictionary IDs are managed internally and are not exposed. example: pd_abc123def456 perception: type: object properties: perception_model: type: string description: The perception model to use. `raven-1` (default and recommended) provides real-time emotional understanding from user audio, more natural and human-like interactions, plus all visual capabilities from raven-0. `raven-0` (legacy settings [here](/sections/troubleshooting#migration-from-legacy-perception-to-raven-1)) offers advanced visual perception only. `off` disables all perception. enum: - raven-1 - raven-0 - 'off' default: raven-1 example: raven-1 visual_awareness_queries: type: array description: Custom queries that Raven continuously monitors in the visual stream. These provide ambient visual context without requiring explicit prompting. items: type: string example: - Is the user showing an ID card? - Does the user appear distressed or uncomfortable? visual_tool_prompt: type: string description: A prompt that details how and when to use visual tools based on what Raven sees. This helps the replica understand the context of the visual tools. 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. visual_tools: type: array description: Tools that can be triggered based on visual context, enabling automated actions in response to visual cues. items: type: object properties: name: type: string description: The name of the tool to be called. description: type: string description: A description of what the tool does and when it should be called. 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 audio_awareness_queries: type: array description: Custom queries that Raven-1 continuously monitors in the audio stream. These provide ambient audio context such as user tone and emotional state. Only available with `raven-1`. items: type: string example: - Does the user sound frustrated or confused? - Is the user speaking quickly as if in a hurry? audio_tool_prompt: type: string description: A prompt that details how and when to use audio tools based on what Raven-1 hears. Only available with `raven-1`. example: You have a tool to escalate to a human agent when the user sounds very frustrated, named `escalate_to_human`. Use this tool when detecting sustained frustration. audio_tools: type: array description: Tools that can be triggered based on audio analysis, enabling automated actions in response to user tone and emotion. Only available with `raven-1`. items: type: object properties: name: type: string description: The name of the tool to be called. description: type: string description: A description of what the tool does and when it should be called. example: - type: function function: name: escalate_to_human description: Escalate the conversation to a human agent when user frustration is detected parameters: type: object properties: reason: type: string description: The reason for escalation required: - reason stt: type: object description: '**Note**: Turn-taking is now configured on the [Conversational Flow layer](/sections/conversational-video-interface/persona/conversational-flow). ' properties: stt_engine: type: string description: The STT engine used for transcription. `tavus-auto` (default, recommended) automatically selects the best model. `tavus-parakeet` offers highest throughput for English and European languages. `tavus-soniox` is purpose-built for Indian languages. `tavus-whisper` provides broad multilingual coverage. `tavus-deepgram-medical` is optimized for clinical vocabulary (English only). `tavus-advanced` is deprecated. enum: - tavus-auto - tavus-parakeet - tavus-soniox - tavus-whisper - tavus-deepgram-medical - tavus-advanced default: tavus-auto example: tavus-auto hotwords: type: string description: The hotwords that will be used for the STT engine. example: This is a hotword example created_at: type: string description: The date and time the persona was created. example: '' updated_at: type: string description: The date and time of when the persona was last updated. '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid persona_id '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid access token security: - apiKey: [] delete: tags: - Personas summary: Delete Persona description: 'This endpoint deletes a single persona by its unique identifier. ' operationId: deletePersona parameters: - name: persona_id in: path required: true description: The unique identifier of the persona. schema: type: string example: pcb7a34da5fe responses: '204': description: NO CONTENT '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid persona_id '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid access token security: - apiKey: [] patch: tags: - Personas summary: Patch Persona description: This endpoint allows you to update specific fields of a persona using JSON Patch operations. operationId: patchPersona requestBody: content: application/json: schema: type: array items: type: object properties: op: type: string description: 'The operation to perform. Must be one of: add, remove, replace, copy, move, test' enum: - add - remove - replace - copy - move - test example: add path: type: string description: 'JSON Pointer (RFC 6901) to a location in the persona document. Paths must match the **current** document shape—compare the response from [Get Persona](/api-reference/personas/get-persona) (`GET /v2/personas/{persona_id}`) before patching. ' example: /layers/llm/model value: type: string description: The value to be used within the operation. **This field is not required for the `remove` operation**. example: tavus-llama-4 required: - op - path - value examples: Replace Persona System Prompt: value: - op: replace path: /system_prompt value: As a Life Coach, you are a dedicated professional who specializes in... Remove STT Hotwords: value: - op: remove path: /layers/stt/hotwords responses: '200': description: OK '304': description: No changes were made to the persona content: application/json: schema: type: object properties: message: type: string description: The error message. example: No changes were made to the persona '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid persona_id '422': description: Invalid JSON patch format content: application/json: schema: type: object properties: message: type: string description: The error message. example: Invalid JSON patch format security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key