Create Persona

Create and customize a persona’s behavior and capabilities for CVI.

POST /v2/personas

cURL

Required Parameters Only

curl --request POST \
  --url https://tavusapi.com/v2/personas \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "pipeline_mode": "full",
  "system_prompt": "As a Life Coach, you are a dedicated professional who specializes in..."
}
'

200

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

This endpoint creates and customizes a digital replica’s behavior and capabilities for Conversational Video Interface (CVI).

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
  • Perception - Multimodal vision and understanding settings (Raven)
  • STT - Transcription and turn taking settings (Sparrow)
  • Conversational Flow - Turn-taking, interruption handling, and active listening settings
  • LLM - Language model settings
  • TTS - Text-to-Speech settings

For detailed guides on each layer of the Conversational Video Interface, click here.

When using full pipeline mode, the system_prompt field is required.

Authorizations

x-api-key · string · header · required

Body

application/json

persona_name · string

A name for the persona.

Example:

"Life Coach"

system_prompt · string

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 · enum<string>

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.

Available options: full, echo

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.

Example:

"rf4e9d9790f0"

document_ids · string[]

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 and the Create Document endpoints.

Example:

["d1234567890", "d2468101214"]

document_tags · string[]

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 endpoint. As soon as one document has the tag, you will be able to pass the tags in this parameter..

Example:

["product_info", "company_policies"]

objectives_id · string

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 endpoint.

Example:

"o12345"

guardrails_id · string

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 endpoint.

Example:

"g12345"

layers · object

Show child attributes

Response

200

application/json

persona_id · string

A unique identifier for the persona.

Example:

"pcb7a34da5fe"

persona_name · string

The name of the persona.

Example:

"Life Coach"

created_at · string

The date and time the persona was created.