---
title: "Create PAL"
method: POST
path: "/v2/pals"
tags: ["PALs"]
---

# Create PAL

`POST /v2/pals`

Creates a PAL and configures how it behaves in CVI for every conversation that uses that PAL.

**`default_face_id` is required** on `POST /v2/pals` (unlike the legacy `POST /v2/personas` path, where `default_replica_id` was optional).

**Legacy:** `/v2/personas` and `persona_id` / `default_replica_id` remain supported as aliases.

## Request body

- object
  - `pal_name` string — A name for the PAL.
  - `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**.
  - `pipeline_mode` 'full' | 'echo' — The pipeline mode to use for the PAL. Possible values: `full`, `echo`. `full` will provide the default end-to-end experience. `echo` will turn off most steps, and allow the PAL to sync video with audio passed in through Echo events, which it will speak out.
  - `default_face_id` string — **Required.** The default face associated with this PAL. When creating a conversation, a `pal_id` with a `default_face_id` can be used without specifying a separate `face_id`. Also **required** when `layers.conferencing` is set - see [Google Meet](/sections/conversational-video-interface/pal/meetings).
  - `document_ids` string[] — Array of document IDs that the PAL will have access to. These documents will be available to the PAL 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.
  - `document_tags` string[] — Array of document tags that the PAL will have access to. Documents matching these tags will be available to the PAL 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..
  - `objectives_id` string — The unique identifier of the objectives to attach to this PAL. Objectives provide goal-oriented instructions that help guide conversations toward specific outcomes. Create objectives using the [Create Objectives](/api-reference/objectives/create-objectives) endpoint.
  - `guardrail_ids` string[] — Array of guardrail IDs enforced during this PAL's conversations. Up to 50 per PAL. Guardrail IDs are returned by [Create Guardrails](/api-reference/guardrails/create-guardrails) and [Get Guardrails](/api-reference/guardrails/get-guardrails).
  - `guardrail_tags` string[] — Array of guardrail tags. Any guardrail you own with a matching tag is attached to this PAL dynamically. Up to 50 tags per PAL, and a PAL can have at most 50 guardrails total.
  - `guardrails_id` string — **Deprecated.** The unique identifier of a guardrail set to attach to this PAL. New integrations should use `guardrail_ids` / `guardrail_tags` instead - see [Deprecated guardrail sets](/api-reference/guardrails/legacy-guardrail-sets).
  - `layers` object — Optional nested settings for each CVI pipeline layer (perception, STT, conversational flow, LLM, TTS, conferencing). For an overview of what each layer controls, see [PAL overview - CVI layers](/sections/conversational-video-interface/pal/overview#cvi-layer).
    - `perception` object
      - `perception_model` 'raven-1' | 'raven-0' | 'off' — 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.
      - `visual_awareness_queries` string[] — Custom queries that Raven continuously monitors in the visual stream. These provide ambient visual context without requiring explicit prompting.
      - `visual_tool_prompt` string — A prompt that details how and when to use visual tools based on what Raven sees. This helps the PAL understand the context of the visual tools.
      - `visual_tools` object[] — **Legacy.** Inline vision tools on the PAL (OpenAI function shape). Deprecated - create tools with `origin: vision` via [Create Tool](/api-reference/tools/create-tool) and attach to the PAL. Still supported at runtime; see [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling).
        - `name` string — The name of the tool to be called.
        - `description` string — A description of what the tool does and when it should be called.
      - `audio_awareness_queries` string[] — 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`.
      - `audio_tool_prompt` string — A prompt that details how and when to use audio tools based on what Raven-1 hears. Only available with `raven-1`.
      - `audio_tools` object[] — **Legacy.** Inline audio tools on the PAL (OpenAI function shape). Deprecated - create tools with `origin: audio` via [Create Tool](/api-reference/tools/create-tool) and attach to the PAL. Raven-1 only. See [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling).
        - `name` string — The name of the tool to be called.
        - `description` string — A description of what the tool does and when it should be called.
    - `stt` object — **Note**: Turn-taking is now configured on the [Conversational Flow layer](/sections/conversational-video-interface/pal/conversational-flow).
      - `stt_engine` 'tavus-auto' | 'tavus-parakeet' | 'tavus-soniox' | 'tavus-whisper' | 'tavus-deepgram-medical' | 'tavus-advanced' — 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/pal/stt) for details.
      - `hotwords` string — 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."
    - `conversational_flow` object — Controls conversational flow dynamics for the PAL. When omitted or partially configured, unspecified fields use sensible defaults (`sparrow-1`, `medium` patience/interruptibility, etc.). See more details [here](/sections/conversational-video-interface/pal/conversational-flow).
      - `turn_detection_model` 'sparrow-1' | 'sparrow-0' — 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`.
      - `turn_taking_patience` 'low' | 'medium' | 'high' — Controls how eagerly and quickly the PAL 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.
      - `pal_interruptibility` 'low' | 'medium' | 'high' — Controls how sensitive the PAL is to user speech while the PAL is talking. Determines whether the PAL stops to listen or keeps speaking. `low` = keeps talking, less interruptible; `medium` (default) = balanced; `high` = stops easily, more interruptible.
      - `replica_interruptibility` 'low' | 'medium' | 'high' — **Legacy alias** for `pal_interruptibility`. Still accepted at runtime; existing integrations do not need to change.
      - `voice_isolation` 'off' | 'near' — 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`.
      - `wake_phrase` string — A specific phrase the PAL listens for before responding. When set, the PAL remains silent until it hears the wake phrase, similar to a voice assistant. The PAL 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).
      - `sleep_phrase` string — A specific phrase that puts the persona back to sleep after it has been woken with the `wake_phrase`. When the persona hears the sleep phrase, it stops responding and returns to the silent state, listening again for the wake phrase before it will respond. The persona still records all user utterances in the transcript while asleep. Choose a phrase that is unique enough to avoid over-triggering. Default is `None` (disabled).
      - `idle_engagement` 'off' | 'patient' | 'eager' — Controls whether the PAL proactively re-engages the user after a stretch of silence, and how eagerly. `off` (default) = the PAL 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.
    - `llm` object
      - `model` string — The model name that will be used by the LLM. **tavus-gemma-4** is recommended as the default. Other Tavus-hosted options include tavus-gemma-4-thinking, tavus-gpt-5.6-sol, tavus-gpt-5.6-terra, and tavus-gemini-2.5-flash. See the [LLM layer documentation](/sections/conversational-video-interface/pal/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. Context limits vary by model. Tip: 1 token ≈ 4 characters.
      - `base_url` string — The base url for your OpenAI compatible endpoint.
      - `api_key` string — The API key for the OpenAI compatible endpoint.
      - `speculative_inference` boolean — When set to `true`, the LLM begins processing speech transcriptions before user input ends, improving responsiveness. Default is `true`.
      - `tools` unknown[] — **Legacy.** Inline OpenAI-style function tools on the PAL. Deprecated - create tools via [Create Tool](/api-reference/tools/create-tool) and attach with [Attach Tools to PAL](/api-reference/pal-tools/attach-tools-to-pal). Still supported at runtime; see [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling).
        - unknown
      - `headers` object — Optional headers to provide to your custom LLM
      - `extra_body` object — Optional parameters to customize the LLM request. For Tavus-hosted models, you can pass `temperature` and `top_p`: - `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. - `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. For custom LLMs, you can pass any parameters that your LLM provider supports (e.g., `temperature`, `top_p`, `frequency_penalty`, etc.).
    - `tts` object
      - `api_key` string — 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.
      - `tts_engine` 'tavus-auto' | 'cartesia' | 'elevenlabs' | 'azure' — The TTS engine that will be used. `tavus-auto` automatically selects the best TTS model for each conversation (recommended). See the [TTS layer documentation](/sections/conversational-video-interface/pal/tts) for details.
      - `external_voice_id` string — The voice ID used for the TTS engine when you want to customize your face'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).
      - `voice_settings` object — 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).
      - `tts_emotion_control` boolean — When true, Tavus automatically handles LLM prompting for emotion tags, enabling expressive vocal delivery and natural emotional facial movements (only available with Phoenix-4 faces). Defaults to true.
      - `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.
      - `pronunciation_dictionary_id` string — The unique identifier of a Tavus pronunciation dictionary to attach to this PAL. 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.
    - `conferencing` ConferencingLayer — [Conferencing layer](/sections/conversational-video-interface/pal/meetings) settings. Provisions a `@tavusinvite.com` email identity so the PAL can be invited to Google Calendar events with Google Meet links and join automatically. Requires `default_face_id` on the PAL.
      - `username` string, required — Local part of the PAL's meeting email (`<username>@tavusinvite.com`). Stored lowercase. Must start and end with an alphanumeric character; `.`, `_`, and `-` are allowed in between. Usernames matching `botN` (for example `bot1`, `bot42`) are reserved. Globally unique across `tavusinvite.com`.
      - `allowlist` string[] — Controls who may invite this PAL via calendar. Each entry is an exact email address or a regex matched against the organizer's email. Empty or omitted allows any sender.

## Response `200`

- object
  - `pal_id` string — A unique identifier for the PAL.
  - `pal_name` string — The name of the PAL.
  - `conferencing_email` string, nullable — The PAL's invitable meeting email on `tavusinvite.com`, derived from `layers.conferencing.username`. Present when conferencing is configured. See [Google Meet](/sections/conversational-video-interface/pal/meetings).
  - `created_at` string — The date and time the PAL was created.

## Other responses

- `400` — Bad Request
- `401` — UNAUTHORIZED

---

[API](https://skmtc.net/tavus/apis/tavus-developer-api-collection.md) · [All operations](https://skmtc.net/tavus/apis/tavus-developer-api-collection/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tavus/tavus-developer-api-collection/versions/c878e2f6508d/schema)