> ## Documentation Index > Fetch the complete documentation index at: https://anam.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # create session token > Create a new session token used to initialise Anam client side SDKs ## OpenAPI ````yaml https://api.anam.ai/swagger.json post /v1/auth/session-token openapi: 3.1.0 info: title: Anam AI API version: '1.0' servers: - url: https://api.anam.ai description: Anam API security: - BearerAuth: [] tags: - name: Sessions - name: Avatar Videos - name: Meetings - name: Personas - name: Avatars - name: Voices - name: LLMs - name: Knowledge - name: Tools - name: Share Links - name: Engine paths: /v1/auth/session-token: post: tags: - Sessions summary: create session token description: Create a new session token used to initialise Anam client side SDKs operationId: createSessionToken requestBody: description: > Configuration for the session to be created. Supply `personaConfig.personaId` to use a persona you've already created (stateful), or the set `avatarId`/`voiceId`/`llmId`/`systemPrompt` to configure the persona at run time (ephemeral). The returned token is valid for one hour and bound to this exact config. Server-side SDKs in a secure context can skip this exchange and start a session directly by calling `POST /v1/engine/session` with their API key and the same configuration in the request body. required: true content: application/json: examples: default: $ref: '#/components/examples/SessionTokenCreate' schema: type: object properties: clientLabel: type: string description: The client label for the session personaConfig: description: >- Persona configuration. An avatar-only config (avatarId without voiceId and without enableAudioPassthrough: true) is only accepted together with a LiveKit, Agora or ElevenLabs Agent integration `environment`; on the default Anam WebRTC transport send an ephemeral config with voiceId and llmId (llmId "CUSTOMER_CLIENT_V1" for a client-side LLM) or set enableAudioPassthrough to true. Otherwise the request fails with 400 `avatar_only_requires_integration`. oneOf: - type: object properties: name: type: string example: Cara avatarId: type: string example: 071b0286-4cce-4808-bee2-e642f1062de3 avatarModel: type: string example: cara-4 description: >- Avatar model version. `cara-3` and `cara-4` are generally available; models with the '-latest' suffix are invite only and require organization-level access. enum: - cara-3 - cara-4 - cara-4-latest voiceId: type: string example: de23e340-1416-4dd8-977d-065a7ca11697 llmId: type: string example: a7cf662c-2ace-4de1-a21e-ef0fbf144bb7 systemPrompt: type: string example: You are a helpful assistant maxSessionLengthSeconds: type: number example: 600 skipGreeting: type: boolean example: false uninterruptibleGreeting: type: boolean description: >- When true, the greeting message cannot be interrupted by the user. example: false initialMessage: type: string nullable: true description: >- Custom first message the persona speaks to open the conversation. If empty or not provided, the persona generates its own greeting. example: Hi there! I'm excited to chat with you today. voiceDetectionOptions: $ref: '#/components/schemas/VoiceDetectionOptions' languageCode: type: string description: >- ISO 639-1 formatted language code override for transcription, replaces organisation level settings and multilingual (default) mode. voiceGenerationOptions: description: Configuration options for voice generation. oneOf: - $ref: >- #/components/schemas/ElevenLabsV1VoiceGenerationOptions - $ref: >- #/components/schemas/ElevenLabsV2VoiceGenerationOptions - $ref: >- #/components/schemas/CartesiaSonic3VoiceGenerationOptions - $ref: >- #/components/schemas/FishAudioVoiceGenerationOptions directorNotes: type: object description: >- 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. properties: presetStyle: type: string enum: - happy - warm - playful - supportive - sad - angry - distressed description: >- 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. example: warm customStylePrompt: type: string maxLength: 2000 description: >- 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. example: >- Warm smile, composed, slightly amused, looking directly at camera expressivity: type: number minimum: 0 maximum: 1 description: >- 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. example: 0.5 tools: type: array description: >- 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). items: type: object required: - type - name additionalProperties: true properties: type: type: string enum: - client - server - system description: >- Tool kind. `server` tools additionally set `subtype` (`knowledge` or `webhook`). name: type: string description: Unique tool name the LLM calls. description: type: string maxLength: 1024 parameters: type: object description: >- JSON Schema for the arguments the LLM provides (client and webhook tools). Must serialize to 10,000 bytes or less. example: - type: client name: open_calendar description: Open the calendar UI in the client app. parameters: type: object properties: date: type: string description: Date to jump to, in YYYY-MM-DD format. toolIds: type: array description: >- IDs of tools pre-created via `/v1/tools` to make available to the persona for this session. items: type: string format: uuid - type: object description: Avatar-only rendering with audio supplied by the client. required: - avatarId - enableAudioPassthrough properties: avatarId: type: string format: uuid example: 071b0286-4cce-4808-bee2-e642f1062de3 enableAudioPassthrough: type: boolean enum: - true description: >- Must be true; the client supplies audio for the avatar. avatarModel: type: string description: Public avatar model version. directorNotes: type: object nullable: true properties: presetStyle: type: string enum: - happy - warm - playful - supportive - sad - angry - distressed customStylePrompt: type: string maxLength: 2000 expressivity: type: number minimum: 0 maximum: 1 zeroDataRetention: type: boolean enum: - false - type: object properties: personaId: type: string environment: type: object description: >- Optional engine routing or transport integration environment. The integration type may be supplied explicitly or inferred from the LiveKit, Agora, or ElevenLabs Agent settings. properties: type: type: string enum: - normal - livekit - agora - elevenlabs_agent namespace: type: string minLength: 1 maxLength: 63 pattern: >- ^(?:anam-engine-preview-\d+|devspace-[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$ podName: type: string engineVersion: type: string livekitUrl: type: string livekitToken: type: string agoraSettings: type: object required: - appId - token - channel - uid - quality - videoEncoding - enableStringUids properties: appId: type: string minLength: 1 token: type: string minLength: 1 channel: type: string minLength: 1 uid: type: string minLength: 1 quality: type: string videoEncoding: type: string enableStringUids: type: boolean activityIdleTimeout: type: number audioSampleRate: type: number showAIAvatarDisclosure: type: boolean width: type: integer minimum: 1 height: type: integer minimum: 1 dependentRequired: width: - height height: - width elevenLabsAgentSettings: type: object required: - signedUrl - agentId properties: signedUrl: type: string agentId: type: string conversationConfigOverride: type: object additionalProperties: true dynamicVariables: type: object additionalProperties: true userId: type: string customLlmExtraBody: type: object additionalProperties: true oneOf: - description: >- Default Anam WebRTC transport with optional engine routing. properties: type: type: string enum: - normal not: anyOf: - required: - livekitUrl - required: - livekitToken - required: - agoraSettings - required: - elevenLabsAgentSettings - description: LiveKit transport integration. required: - livekitUrl - livekitToken properties: type: type: string enum: - livekit - description: Agora transport integration. required: - agoraSettings properties: type: type: string enum: - agora - description: ElevenLabs Agent integration. required: - elevenLabsAgentSettings properties: type: type: string enum: - elevenlabs_agent sessionOptions: type: object properties: sessionReplay: type: object properties: enableSessionReplay: type: boolean description: >- Record the session for replay. Must be false or omitted when Zero Data Retention is enabled. example: true default: true videoQuality: type: string enum: - high - auto description: >- 'high' pins highest bitrate, 'auto' enables adaptive bitrate. example: high showAIAvatarDisclosure: type: boolean description: >- Show the AI avatar disclosure during the session. Defaults to false; set true to opt in. Agora sessions ignore this field. example: true region: type: string enum: - eu - us description: >- Requested engine region. This explicit choice is honored independently of automatic geographic routing. regionPolicy: type: string enum: - preferred - strict default: preferred description: >- `preferred` allows cross-region capacity failover. `strict` keeps the session in the requested region and requires `region`. videoWidth: type: integer description: >- 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). example: 1152 videoHeight: type: integer description: >- Output video frame height in pixels. Supply together with `videoWidth` (both or neither). See `videoWidth`. example: 768 egress: type: object description: > 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`. required: - mode properties: mode: type: string enum: - daily description: Egress provider. Only `daily` is supported today. example: daily daily: type: object description: Required when `mode` is `daily`. required: - roomUrl properties: roomUrl: type: string format: uri description: >- Daily room URL the avatar should join as a publisher. example: https://your-domain.daily.co/avatar-room token: type: string description: >- Optional Daily meeting token. Omit for public rooms. userName: type: string description: >- Optional display name for the avatar participant. Defaults to "anam-avatar". responses: '200': description: Successfully started session content: application/json: schema: $ref: '#/components/schemas/SessionToken' examples: default: $ref: '#/components/examples/SessionTokenResponse' '400': description: >- 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`. Avatar-only persona configs (avatarId without voiceId and without enableAudioPassthrough: true) are rejected with `avatar_only_requires_integration` unless a LiveKit, Agora or ElevenLabs Agent integration `environment` is supplied. '401': description: Unauthorized - Invalid or missing API key '403': description: >- 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. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string examples: sessionRegionNotAvailable: value: error: session_region_not_available message: >- Session region selection is not available for this organization '500': description: >- 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. components: examples: SessionTokenCreate: summary: Mint a token for an ephemeral persona value: personaConfig: name: Cara avatarId: 071b0286-4cce-4808-bee2-e642f1062de3 voiceId: de23e340-1416-4dd8-977d-065a7ca11697 llmId: a7cf662c-2ace-4de1-a21e-ef0fbf144bb7 systemPrompt: You are a helpful assistant. SessionTokenResponse: summary: A freshly minted session token value: sessionToken: >- eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.signature schemas: VoiceDetectionOptions: type: object description: Options for voice activity detection during user speech input. properties: endOfSpeechSensitivity: type: number description: >- Sensitivity for detecting end of speech, between 0 (least sensitive) and 1 (most sensitive). example: 0.5 minimum: 0 maximum: 1 silenceBeforeSkipTurnSeconds: type: number description: >- Duration of silence (in seconds) before the current user turn is skipped. example: 5 minimum: 0 maximum: 900 silenceBeforeSessionEndSeconds: type: number description: >- Duration of silence (in seconds) before the session is automatically ended. example: 60 minimum: 0 maximum: 7200 silenceBeforeAutoEndTurnSeconds: type: number description: >- Duration of silence (in seconds) before the user turn is automatically ended. example: 5 minimum: 0.5 maximum: 10 speechEnhancementLevel: type: number description: >- Level of speech enhancement to apply, 0 (no speech enhancement) 1 (max speech enhancement) example: 0.8 minimum: 0 maximum: 1 sttProvider: type: string enum: - anam - deepgram description: >- Speech-to-text provider to use. Defaults to the platform default when unset. The deepgram provider supports only these languageCode values: en, es, fr, de, hi, ru, pt, ja, it, nl. example: anam ElevenLabsV1VoiceGenerationOptions: title: ElevenLabs V1 type: object description: Voice generation options for ElevenLabs V1 models. properties: stability: type: number description: >- Controls how stable the generated voice is between each generation, between 0 (more varied/higher emotional range) and 1 (more stable/less emotional range). example: 0.5 minimum: 0 maximum: 1 similarityBoost: type: number description: >- Controls how close the generated voice is to the original speaker, between 0 (more varied) and 1 (more similar). example: 0 minimum: 0 maximum: 1 speed: type: number description: >- Controls the speed of the spoken voice as a multiplier, between 0.7 (slower) and 1.2 (faster). example: 1 minimum: 0.7 maximum: 1.2 ElevenLabsV2VoiceGenerationOptions: title: ElevenLabs V2 type: object description: Voice generation options for ElevenLabs V2 models. properties: stability: type: number description: >- Controls how stable the generated voice is between each generation, between 0 (more varied/higher emotional range) and 1 (more stable/less emotional range). example: 0.5 minimum: 0 maximum: 1 similarityBoost: type: number description: >- Controls how close the generated voice is to the original speaker, between 0 (more varied) and 1 (more similar). example: 0.75 minimum: 0 maximum: 1 style: type: number description: >- Amplifies the style of the original speaker, between 0 and 1, it is recommended to keep this value low (0) to reduce latency. example: 0 minimum: 0 maximum: 1 useSpeakerBoost: type: boolean description: >- Whether to use speaker boost for the generated voice, enhancing the similarity to the original speaker. example: true speed: type: number description: >- Controls the speed of the spoken voice as a multiplier, between 0.7 (slower) and 1.2 (faster). example: 1 minimum: 0.7 maximum: 1.2 model: type: string description: The ElevenLabs model ID to use for voice generation. CartesiaSonic3VoiceGenerationOptions: title: Cartesia Sonic-3 type: object description: Voice generation options for Cartesia Sonic-3 models. properties: volume: type: number description: >- Controls the volume level of the generated voice as a multiplier, between 0.5 (quieter) and 2.0 (louder). example: 1 minimum: 0.5 maximum: 2 speed: type: number description: >- Controls the speed of the spoken voice as a multiplier, between 0.6 (slower) and 1.5 (faster). example: 1 minimum: 0.6 maximum: 1.5 emotion: type: string description: >- Sets the emotional tone of the generated voice. Supported emotions are: neutral, calm, angry, content, sad, scared. example: neutral oneOf: - type: string enum: - neutral - calm - angry - content - sad - scared FishAudioVoiceGenerationOptions: title: Fish Audio type: object description: Voice generation options for Fish Audio models. properties: volume: type: number description: >- Controls the volume level of the generated voice as a multiplier, between 0.5 (quieter) and 2.0 (louder). example: 1 minimum: 0.5 maximum: 2 speed: type: number description: >- Controls the speed of the spoken voice as a multiplier, between 0.5 (slower) and 2.0 (faster). example: 1 minimum: 0.5 maximum: 2 SessionToken: type: object description: >- Short-lived credential used by a client to connect to a live persona. Valid for one hour. properties: sessionToken: type: string description: >- Signed JWT the client passes to the Anam SDK to open a WebRTC connection. securitySchemes: BearerAuth: type: http scheme: bearer ````