--- title: "Create Session Token" method: POST path: "/v1/sessions/token" tags: ["Sessions"] --- # Create Session Token `POST /v1/sessions/token` Create session token for an API-key-authenticated user. Minting a session token is only doable via an API key (``APIUserDep``) — a session JWT (``SessionUser``) cannot mint a token for another participant. ## Request body - union - FullSDKSessionTokenConfigDataSchema - `mode` 'FULL' - `avatar_id` string, uuid, required - `is_sandbox` boolean - `video_settings` VideoSettings — Video encoding settings for session configuration - `quality` 'very_high' | 'high' | 'medium' | 'low' - `encoding` 'VP8' | 'H264' - `max_session_duration` integer — Maximum session duration in seconds. Must be <= the configured limit for your subscription tier. - `avatar_persona` AvatarPersonaSchema - `voice_id` string, uuid — Voice ID. If empty use default avatar voice - `context_id` string, uuid — Context ID - `language` string — Language - `voice_settings` union — Additional voice settings (provider-specific, discriminated by 'provider' field) - ElevenLabsVoiceSettings — ElevenLabs-specific voice settings for TTS configuration. - `provider` 'elevenLabs' - `speed` number - `stability` number - `similarity_boost` number - `style` number - `use_speaker_boost` boolean - `model` 'eleven_flash_v2_5' | 'eleven_multilingual_v2' - `apply_language_text_normalization` boolean — Apply ElevenLabs language-specific text normalization. Improves pronunciation for languages with complex orthography — currently only Japanese ('ja') is supported. Enabling this adds latency, so it is opt-in and only valid when the session language is set to 'ja'. - FishAudioVoiceSettings — Fish Audio-specific voice settings for TTS configuration. - `provider` 'fish' - `speed` number - `model` 's1' | 's2' - `latency_mode` 'normal' | 'balanced' — Latency mode: 'normal' (~500ms) or 'balanced' (~300ms). - `stt_config` STTConfigSchema — User-provided STT configuration for sessions. - `provider` 'deepgram' | 'assembly_ai' | 'gladia' | 'elevenlabs', required - `voice_agent` VoiceAgentRef — Reference to a stored voice_agent, plus optional per-session overrides. The caller passes only the agent ``id``; the server resolves the stored agent's ``agent_type`` and decides how the session is built. The override fields below are NOT universal — which ones are accepted depends on the resolved type, and an override that doesn't apply is rejected (400) rather than silently ignored: * ``liveavatar_agent`` (managed STT -> LLM -> TTS pipeline): ``language`` and ``dynamic_variables`` are honored, layered over the stored agent's config for this session only. * ``elevenlabs_agent`` (ElevenLabs-hosted): the stored agent is used as-is; passing ``language`` or ``dynamic_variables`` is rejected with a 400. Overrides are per-session-at-creation choices, not properties of the stored agent — the same agent is reused across sessions with different values each time, and the resolved result is what gets frozen into the session snapshot. Shared across the SDK and app token requests. ``dynamic_variables`` is typed as the bounded union for forward-compatibility (a single wire type across agent types); the server narrows or rejects it per the resolved ``agent_type`` as described on the field. - `id` string, uuid, required — Stored voice_agent id. Its server-resolved agent_type determines which of the override fields below are accepted. - `language` string — Per-session language override, layered over the agent's stored language. Accepted only for a liveavatar_agent; rejected with a 400 for an elevenlabs_agent. - `dynamic_variables` object — Per-session dynamic_variables override. Accepted only for a liveavatar_agent, where values must be strings (substituted as text into the context's ${var} placeholders; non-string values are rejected with a 400). Rejected with a 400 for an elevenlabs_agent. Mutually exclusive with the top-level dynamic_variables (400 if both set). At most 50 entries; keys <= 64 chars; string values <= 1000 chars. - `interactivity_type` 'CONVERSATIONAL' | 'PUSH_TO_TALK' - `llm_configuration_id` string, uuid — Optional custom LLM configuration ID - `dynamic_variables` object — Values for ${var} placeholders in the context's opening_text and prompt. Required keys are derived from the context; extra keys are ignored. At most 50 entries; keys <= 64 chars; values <= 1000 chars. - `memory` MemoryRef — Session-memory attach request. Either field may be set. If both are set, they must resolve to the same memory_id; mismatch -> 400. - `prev_session_id` string, uuid — Seed memory from a prior FULL-mode session. Reused if a session-memory already exists for that session; otherwise sync-bootstrapped. - `session_memory_id` string, uuid — Attach an existing session-typed memory by id (must belong to caller's space). - LiteSDKSessionTokenConfigDataSchema - `mode` 'LITE' - `avatar_id` string, uuid, required - `is_sandbox` boolean - `video_settings` VideoSettings — Video encoding settings for session configuration - `quality` 'very_high' | 'high' | 'medium' | 'low' - `encoding` 'VP8' | 'H264' - `max_session_duration` integer — Maximum session duration in seconds. Must be <= the configured limit for your subscription tier. - `livekit_config` LiveKitConfigSchema - `livekit_url` string, required - `livekit_room` string, required - `livekit_client_token` string, required - `agora_config` AgoraConfigSchema - `agora_app_id` string, required - `agora_token` string, required - `agora_channel` string, required - `agora_uid` string, required - `elevenlabs_agent_config` ElevenLabsAgentConfigSchema — Config for ElevenLabs Agent mode in LITE sessions. All fields required when present. - `secret_id` string, uuid, required — Secret ID for ELEVENLABS_API_KEY - `agent_id` string, required — ElevenLabs Agent ID - `voice_id` string — Optional ElevenLabs voice ID override. When set, sent to the ElevenLabs Agent WebSocket as `conversation_config_override.tts.voice_id`, overriding the agent's default voice for this session. When omitted, the agent's configured default voice is used. See https://elevenlabs.io/docs/eleven-agents/api-reference/eleven-agents/websocket - `dynamic_variables` object — ElevenLabs Agent dynamic variables injected into prompts and tools. See https://elevenlabs.io/docs/eleven-agents/customization/personalization/dynamic-variables - `openai_realtime_config` OpenAIRealtimeConfigSchema — Config for OpenAI Realtime Agent mode in LITE sessions. - `secret_id` string, uuid, required — Secret ID referencing OPENAI_API_KEY secret - `context_id` string, uuid — Context ID. - `voice` 'alloy' | 'ash' | 'ballad' | 'coral' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer' | 'sage' | 'verse' | 'marin' | 'cedar' - `temperature` number — Sampling temperature - `model` string — OpenAI Realtime model - `gemini_realtime_config` GeminiRealtimeConfigSchema — Config for Gemini Realtime Agent mode in LITE sessions. - `secret_id` string, uuid, required — Secret ID referencing GEMINI_API_KEY secret - `context_id` string, uuid — Context ID. - `voice` 'Achernar' | 'Achird' | 'Algenib' | 'Algieba' | 'Alnilam' | 'Aoede' | 'Autonoe' | 'Callirrhoe' | 'Charon' | 'Despina' | 'Enceladus' | 'Erinome' | 'Fenrir' | 'Gacrux' | 'Iapetus' | 'Kore' | 'Laomedeia' | 'Leda' | 'Orus' | 'Pulcherrima' | 'Puck' | 'Rasalgethi' | 'Sadachbia' | 'Sadaltager' | 'Schedar' | 'Sulafat' | 'Umbriel' | 'Vindemiatrix' | 'Zephyr' | 'Zubenelgenubi' - `temperature` number — Sampling temperature - `model` 'gemini-2.5-flash-native-audio-preview-12-2025' | 'gemini-3.1-flash-live-preview' ## Response `200` Successful Response - ResponseSDKSessionTokenSchema - `code` integer - `data` SDKSessionTokenSchema - `session_id` string, uuid, required - `session_token` string, required - `message` string ## Other responses - `422` — Validation Error --- [API](https://skmtc.dev/liveavatar/apis/live-avatar-api.md) · [All operations](https://skmtc.dev/liveavatar/apis/live-avatar-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/liveavatar/live-avatar-api/revisions/fbfa5cdbd7f9/schema)