---
title: "create session token"
method: POST
path: "/v1/auth/session-token"
tags: ["Sessions"]
---

# create session token

`POST /v1/auth/session-token`

Create a new session token used to initialise Anam client side SDKs

## Request body

- object
  - `clientLabel` string — The client label for the session
  - `personaConfig` union
    - object
      - `name` string
      - `avatarId` string
      - `avatarModel` 'cara-3' | 'cara-4' | 'cara-4-latest' — Avatar model version. `cara-3` and `cara-4` are generally available; models with the '-latest' suffix are invite only and require organization-level access.
      - `voiceId` string
      - `llmId` string
      - `systemPrompt` string
      - `maxSessionLengthSeconds` number
      - `skipGreeting` boolean
      - `uninterruptibleGreeting` boolean — When true, the greeting message cannot be interrupted by the user.
      - `initialMessage` string, nullable — Custom first message the persona speaks to open the conversation. If empty or not provided, the persona generates its own greeting.
      - `voiceDetectionOptions` VoiceDetectionOptions — Options for voice activity detection during user speech input.
        - `endOfSpeechSensitivity` number — Sensitivity for detecting end of speech, between 0 (least sensitive) and 1 (most sensitive).
        - `silenceBeforeSkipTurnSeconds` number — Duration of silence (in seconds) before the current user turn is skipped.
        - `silenceBeforeSessionEndSeconds` number — Duration of silence (in seconds) before the session is automatically ended.
        - `silenceBeforeAutoEndTurnSeconds` number — Duration of silence (in seconds) before the user turn is automatically ended.
        - `speechEnhancementLevel` number — Level of speech enhancement to apply, 0 (no speech enhancement) 1 (max speech enhancement)
      - `languageCode` string — ISO 639-1 formatted language code override for transcription, replaces organisation level settings and multilingual (default) mode.
      - `voiceGenerationOptions` union — Configuration options for voice generation.
        - ElevenLabsV1VoiceGenerationOptions — Voice generation options for ElevenLabs V1 models.
          - `stability` number — Controls how stable the generated voice is between each generation, between 0 (more varied/higher emotional range) and 1 (more stable/less emotional range).
          - `similarityBoost` number — Controls how close the generated voice is to the original speaker, between 0 (more varied) and 1 (more similar).
          - `speed` number — Controls the speed of the spoken voice as a multiplier, between 0.7 (slower) and 1.2 (faster).
        - ElevenLabsV2VoiceGenerationOptions — Voice generation options for ElevenLabs V2 models.
          - `stability` number — Controls how stable the generated voice is between each generation, between 0 (more varied/higher emotional range) and 1 (more stable/less emotional range).
          - `similarityBoost` number — Controls how close the generated voice is to the original speaker, between 0 (more varied) and 1 (more similar).
          - `style` number — Amplifies the style of the original speaker, between 0 and 1, it is recommended to keep this value low (0) to reduce latency.
          - `useSpeakerBoost` boolean — Whether to use speaker boost for the generated voice, enhancing the similarity to the original speaker.
          - `speed` number — Controls the speed of the spoken voice as a multiplier, between 0.7 (slower) and 1.2 (faster).
          - `model` string — The ElevenLabs model ID to use for voice generation.
        - CartesiaSonic3VoiceGenerationOptions — Voice generation options for Cartesia Sonic-3 models.
          - `volume` number — Controls the volume level of the generated voice as a multiplier, between 0.5 (quieter) and 2.0 (louder).
          - `speed` number — Controls the speed of the spoken voice as a multiplier, between 0.6 (slower) and 1.5 (faster).
          - `emotion` 'neutral' | 'calm' | 'angry' | 'content' | 'sad' | 'scared' — Sets the emotional tone of the generated voice. Supported emotions are: neutral, calm, angry, content, sad, scared.
        - FishAudioVoiceGenerationOptions — Voice generation options for Fish Audio models.
          - `volume` number — Controls the volume level of the generated voice as a multiplier, between 0.5 (quieter) and 2.0 (louder).
          - `speed` number — Controls the speed of the spoken voice as a multiplier, between 0.5 (slower) and 2.0 (faster).
      - `directorNotes` object — Per-session performance overrides for the avatar. Only applied on cara-4 avatars (avatarModel `cara-4` or `cara-4-latest`); if set on a cara-3 avatar they are ignored (silently stripped) and the session proceeds without them. `presetStyle` and `customStylePrompt` are mutually exclusive. These work best when the selected voice matches the intended performance.
        - `presetStyle` 'happy' | 'warm' | 'playful' | 'supportive' | 'sad' | 'angry' | 'distressed' — Built-in performance style for the avatar to follow. Mutually exclusive with customStylePrompt. Works best with a matching voice, which we've labelled as expressive.
        - `customStylePrompt` string — Free-form performance style prompt for the avatar to follow. Mutually exclusive with presetStyle. Works best with a matching voice, which we've labelled as expressive.
        - `expressivity` number — Controls how closely the avatar follows the selected style or cue. 0 is subtle, 1 follows it most strongly and can become unstable; omit the field to use the default. Works best with a matching voice, which we've labelled as expressive.
      - `tools` object[] — Runtime tool definitions made available to the persona for this session. Each item is one of a client tool, a server knowledge tool, a server webhook tool, or a system tool. For client and webhook tools, `parameters` (and, for webhook tools, `queryParameters`) is a JSON Schema object the LLM fills at call time; each such object must serialize to 10,000 bytes or less (UTF-8), otherwise the request is rejected. Use `toolIds` instead to reference tools you've pre-created via `/v1/tools` (those are not subject to this inline size limit).
        - `type` 'client' | 'server' | 'system', required — Tool kind. `server` tools additionally set `subtype` (`knowledge` or `webhook`).
        - `name` string, required — Unique tool name the LLM calls.
        - `description` string
        - `parameters` object — JSON Schema for the arguments the LLM provides (client and webhook tools). Must serialize to 10,000 bytes or less.
      - `toolIds` string[] — IDs of tools pre-created via `/v1/tools` to make available to the persona for this session.
    - object
      - `personaId` string
  - `sessionOptions` object
    - `sessionReplay` object
      - `enableSessionReplay` boolean — Record the session for replay. Must be false or omitted when Zero Data Retention is enabled.
    - `videoQuality` 'high' | 'auto' — 'high' pins highest bitrate, 'auto' enables adaptive bitrate.
    - `showAIAvatarDisclosure` boolean — Show the AI avatar disclosure during the session. Defaults to false; set true to opt in. Agora sessions ignore this field.
    - `region` 'eu' | 'us' — Requested engine region. This explicit choice is honored independently of automatic geographic routing.
    - `regionPolicy` 'preferred' | 'strict' — `preferred` allows cross-region capacity failover. `strict` keeps the session in the requested region and requires `region`.
    - `videoWidth` integer — Output video frame width in pixels. Supply together with `videoHeight` (both or neither). Omit to use the avatar model's default. Supported pairs depend on the avatar model — cara-3: `720x480`; cara-4: `1152x768`. Unsupported pairs are rejected (the session is not silently downgraded).
    - `videoHeight` integer — Output video frame height in pixels. Supply together with `videoWidth` (both or neither). See `videoWidth`.
    - `egress` object — Set egress to an alternative egress transport mode. The avatar's audio/video are published to a 3rd party transport and not delivered over the native webRTC channel. The WebRTC peer connection still exists for signalling and the data channel (interrupts, status). Requires `personaConfig.enableAudioPassthrough=true`. Discriminated on `mode`.
      - `mode` 'daily', required — Egress provider. Only `daily` is supported today.
      - `daily` object — Required when `mode` is `daily`.
        - `roomUrl` string, uri, required — Daily room URL the avatar should join as a publisher.
        - `token` string — Optional Daily meeting token. Omit for public rooms.
        - `userName` string — Optional display name for the avatar participant. Defaults to "anam-avatar".

## Response `200`

Successfully started session

- SessionToken — Short-lived credential used by a client to connect to a live persona. Valid for one hour.
  - `sessionToken` string — Signed JWT the client passes to the Anam SDK to open a WebRTC connection.

## Other responses

- `400` — Invalid request body or incompatible Zero Data Retention configuration. ZDR requests are rejected when the selected voice or LLM does not support ZDR, compatibility cannot be verified, or session replay is enabled. Region values must be `eu` or `us`, and `regionPolicy: strict` requires an explicit `region`.
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - API key lacks the required permission, the session config is not authorized for the organization, or the plan does not permit the requested option, including Zero Data Retention or session region selection.
- `500` — Server error. Note: currently any non-validation error is returned as a 500, eventhough the error might be due to joining the room or related to token validation.

---

[API](https://skmtc.net/anam/apis/anam-ai-api.md) · [All operations](https://skmtc.net/anam/apis/anam-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/anam/anam-ai-api/revisions/67afd1c5db59/schema)