---
title: "Create Session"
method: POST
path: "/api/v1/sessions"
---

# Create Session

`POST /api/v1/sessions`

## Request

- Base URL: `https://api.avaturn.live`
- URL: `https://api.avaturn.live/api/v1/sessions`
- Auth: HTTP bearer

Initiates a session.

<Warning>
  Call this endpoint from your backend.
  You must not expose your API Key in your frontend code.
</Warning>

Upon successful creation, the API returns a session token that can be safely used in Web SDK.

There are a few ways to process what a user says and what avatar says.

It's configured via the conversation engine. Supported types:

- `openai-realtime` — Avaturn Live talks directly to OpenAI
  Realtime on your behalf.
- `cartesia` — [Cartesia Line](https://docs.cartesia.ai/line/integrations/calls-api)
- `external` — Avaturn Live opens a WebSocket to a URL you
  provide and exchanges raw audio plus segment events with it.
  The reference integration uses [Pipecat](https://docs.pipecat.ai);
  see the open-source `pipecat-avaturn-live-demo` repo for a
  working end-to-end example.
- `text-echo` — legacy text-driven TTS playback.

Reach out to us if you want to integrate with something else.

## Request body

- CreateSessionConfig
  - `avatar_id` string: Avatar ID
  - `conversation_engine` union: Configures how avatar listens and responds
    - TextEchoConversationEngineConfig: Text-based echo conversation engine. Allows controlling what avatar says with text. The text is converted into audio using TTS engine. Multiple TTS engines are supported.
      - `type` 'text-echo'
      - `tts` TTSConfig, required: Configures text-to-speech synthesis.
        - `engine` 'elevenlabs'
        - `voice_id` string, required: ID of the voice from the dashboard
    - OpenAIRealtimeAPIConversationEngineConfig
      - `type` 'openai-realtime'
      - `client_secret` string, nullable
    - CartesiaConversationEngineConfig
      - `type` 'cartesia'
      - `access_token` string, required
      - `agent_id` string, required
    - ExternalConversationEngineConfig
      - `type` 'external'
      - `url` string, required: WebSocket URL Avaturn Live opens to your conversation engine. Use a `wss://` URL in production.
      - `audio` ExternalAudioConfig
        - `user` ExternalAudioUserConfig
          - `sample_rate` 16000 | 24000
      - `headers` object, nullable: Optional headers Avaturn Live forwards on the WebSocket upgrade request. Use this to authenticate the upgrade against your engine, e.g. {"Authorization": "Bearer <token>"}.
    - LiveKitConversationEngineConfig: LiveKit-Agents-based conversation engine. Collapses transport + CE into a single worklet (``LiveKitWorklet``): the agent runs in a LiveKit room and we both publish avatar AV and consume agent TTS audio over the same room. The caller supplies ``url`` and a pre-minted avatar join token.
      - `type` 'livekit'
      - `url` string, required
      - `token` string, required
      - `agent_identity` string, required
  - `background` 'transparent' | 'default': Background type for the avatar. 'transparent' removes the background, 'default' uses the avatar's default background
  - `model` 'delta' | 'golf'
  - `user_absent_timeout` integer: Seconds to wait before terminating the session if no user is connected
  - `max_duration` integer: Maximum session duration in seconds (max 24 hours)

## Response `200`

Successful Response

- CreateSessionResponse
  - `session_id` string, required: Session ID
  - `token` string, required: Session token for Web SDK

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/avaturn-live/apis/avaturn-live-api.md) - [All operations](https://skmtc.dev/avaturn-live/apis/avaturn-live-api/llms.txt) - [OpenAPI document](https://skmtc.dev/avaturn-live/apis/avaturn-live-api/revisions/e142c11ac753?raw)