> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avaturn.live/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Session
> Initiates a session.
Call this endpoint from your backend.
You must not expose your API Key in your frontend code.
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.
## OpenAPI
````yaml https://api.avaturn.live/api/v1/openapi.json post /api/v1/sessions
openapi: 3.1.0
info:
title: API
version: 0.1.0
servers:
- url: https://api.avaturn.live
security: []
paths:
/api/v1/sessions:
post:
summary: Create Session
description: >-
Initiates a session.
Call this endpoint from your backend.
You must not expose your API Key in your frontend code.
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.
operationId: post_create_session_api_v1_sessions_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionConfig'
default:
avatar_id: jane_20240829
background: default
model: delta
user_absent_timeout: 60
max_duration: 3600
examples:
text-echo-elevenlabs:
summary: Text-Echo engine with elevenlabs TTS
description: >-
Example shows default background. To use transparent
background, set background='transparent'
value:
avatar_id: jane_20240829
conversation_engine:
type: text-echo
tts:
engine: elevenlabs
voice_id:
background: default
model: delta
user_absent_timeout: 60
max_duration: 3600
external-pipecat:
summary: External conversation engine (Pipecat over WebSocket)
description: >-
Points Avaturn Live at a Pipecat agent reachable at
wss://your-engine.example.com/avaturn-live/ws. Headers are
forwarded on the WS upgrade so your engine can authenticate
the connection.
value:
avatar_id: jane_20240829
conversation_engine:
type: external
url: wss://your-engine.example.com/avaturn-live/ws
audio:
user:
sample_rate: 24000
headers:
Authorization: Bearer
background: default
model: delta
user_absent_timeout: 60
max_duration: 3600
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
CreateSessionConfig:
properties:
avatar_id:
type: string
title: Avatar Id
description: Avatar ID
default: jane_20240829
conversation_engine:
anyOf:
- oneOf:
- $ref: '#/components/schemas/TextEchoConversationEngineConfig'
- $ref: >-
#/components/schemas/OpenAIRealtimeAPIConversationEngineConfig
- $ref: '#/components/schemas/CartesiaConversationEngineConfig'
- $ref: '#/components/schemas/ExternalConversationEngineConfig'
discriminator:
propertyName: type
mapping:
cartesia:
$ref: '#/components/schemas/CartesiaConversationEngineConfig'
external:
$ref: '#/components/schemas/ExternalConversationEngineConfig'
openai-realtime:
$ref: >-
#/components/schemas/OpenAIRealtimeAPIConversationEngineConfig
text-echo:
$ref: '#/components/schemas/TextEchoConversationEngineConfig'
- type: 'null'
title: Conversation Engine
description: Configures how avatar listens and responds
background:
type: string
enum:
- transparent
- default
title: Background
description: >-
Background type for the avatar. 'transparent' removes the
background, 'default' uses the avatar's default background
default: default
model:
type: string
enum:
- delta
- golf
title: Model
default: delta
user_absent_timeout:
type: integer
minimum: 10
title: User Absent Timeout
description: >-
Seconds to wait before terminating the session if no user is
connected
default: 60
max_duration:
type: integer
maximum: 86400
minimum: 60
title: Max Duration
description: Maximum session duration in seconds (max 24 hours)
default: 3600
additionalProperties: true
type: object
title: CreateSessionConfig
CreateSessionResponse:
properties:
session_id:
type: string
title: Session Id
description: Session ID
token:
type: string
title: Token
description: Session token for Web SDK
type: object
required:
- session_id
- token
title: CreateSessionResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
TextEchoConversationEngineConfig:
properties:
type:
type: string
const: text-echo
title: Type
default: text-echo
tts:
$ref: '#/components/schemas/TTSConfig'
type: object
required:
- tts
title: TextEchoEngineConfig
description: >-
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.
OpenAIRealtimeAPIConversationEngineConfig:
properties:
type:
type: string
const: openai-realtime
title: Type
default: openai-realtime
client_secret:
anyOf:
- type: string
- type: 'null'
title: Client Secret
type: object
title: OpenAIRealtimeAPICEConfig
CartesiaConversationEngineConfig:
properties:
type:
type: string
const: cartesia
title: Type
default: cartesia
access_token:
type: string
title: Access Token
agent_id:
type: string
title: Agent Id
type: object
required:
- access_token
- agent_id
title: CartesiaCEConfig
ExternalConversationEngineConfig:
properties:
type:
type: string
const: external
title: Type
default: external
url:
type: string
title: Url
description: >-
WebSocket URL Avaturn Live opens to your conversation engine. Use a
`wss://` URL in production.
audio:
$ref: '#/components/schemas/ExternalAudioConfig'
headers:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Headers
description: >-
Optional headers Avaturn Live forwards on the WebSocket upgrade
request. Use this to authenticate the upgrade against your engine,
e.g. {"Authorization": "Bearer "}.
type: object
required:
- url
title: ExternalCEConfig
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
TTSConfig:
properties:
engine:
type: string
const: elevenlabs
title: Engine
default: elevenlabs
voice_id:
type: string
title: Voice Id
description: ID of the voice from the dashboard
type: object
required:
- voice_id
title: TTSConfig
description: Configures text-to-speech synthesis.
ExternalAudioConfig:
properties:
user:
$ref: '#/components/schemas/ExternalAudioUserConfig'
type: object
title: ExternalAudioConfig
ExternalAudioUserConfig:
properties:
sample_rate:
type: integer
enum:
- 16000
- 24000
title: Sample Rate
default: 24000
type: object
title: ExternalAudioUserConfig
securitySchemes:
HTTPBearer:
type: http
description: avaturn.live API key
scheme: bearer
````