> ## Documentation Index
> Fetch the complete documentation index at: https://lemonslice.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Agora session
> Starts a LemonSlice avatar session for Agora Conversational AI Engine. Agora's generic avatar vendor calls this endpoint when you start an agent with LemonSlice configured as the avatar provider.
**Do not call this endpoint directly from your app.** Configure LemonSlice in Agora's `join` request via the [Agora integration](/docs/agora) (`vendor: "generic"`). Agora's backend calls this endpoint to open the avatar session.
## OpenAPI
````yaml /openapi.json post /liveai/agora/session/start
openapi: 3.1.0
info:
title: LemonSlice
description: An API that gives access to a LemonSlice agent via a Daily room.
license:
name: MIT
identifier: MIT
version: 1.0.0
servers:
- url: https://lemonslice.com/api
security:
- apiKeyAuth: []
paths:
/liveai/agora/session/start:
post:
summary: Create Agora session
description: >-
Starts a LemonSlice avatar session for Agora Conversational AI Engine.
Agora's generic avatar vendor calls this endpoint when you start an
agent with LemonSlice configured as the avatar provider.
operationId: createAgoraSession
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgoraSessionInput'
example:
avatar_id: lemonslice
agent_image_url: https://cdn.lemonslice.com/agents/custom_agent.png
video_encoding: H264
activity_idle_timeout: 120
agora_settings:
app_id:
token:
channel: demo-room
uid: '3000'
enable_string_uid: false
responses:
'201':
description: Session started successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/AgoraSessionStartResponse'
example:
session_id: 3f7c2b91-9e1f-4a6a-8e9d-2c7c3e7d9b5a
websocket_address: wss://example.modal.host/tunnel
session_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/AgoraError'
example:
error: Invalid request
message: 'Missing required field: video_encoding'
code: VALIDATION_ERROR
'401':
description: Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/AgoraError'
example:
error: Unauthorized
message: Invalid API key
code: INVALID_API_KEY
'402':
description: Insufficient funds
content:
application/json:
schema:
$ref: '#/components/schemas/AgoraError'
example:
error: Unauthorized
message: User has insufficient funds
code: INSUFFICIENT_FUNDS
'403':
description: Missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/AgoraError'
example:
error: Forbidden
message: API key header missing
code: MISSING_API_KEY
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/AgoraError'
example:
error: Internal Server Error
message: Failed to join session
code: INTERNAL_ERROR
'504':
description: Timed out waiting for the WebSocket tunnel
content:
application/json:
schema:
$ref: '#/components/schemas/AgoraError'
example:
error: Gateway Timeout
message: Timed out waiting for tunnel to become ready
code: TUNNEL_TIMEOUT
components:
schemas:
AgoraSessionInput:
description: >-
Body for starting a LemonSlice Agora session. Exactly one of `agent_id`,
`agent_image_url`, or `agent_image_base64` must be provided.
type: object
required:
- video_encoding
- agora_settings
properties:
avatar_id:
type: string
description: >-
Pass in `lemonslice` for this field. The avatar's appearance is
taken from `agent_id`, `agent_image_url`, or `agent_image_base64`.
example: lemonslice
agent_id:
type: string
description: >-
The ID of a LemonSlice agent. Exactly one of `agent_id`,
`agent_image_url`, or `agent_image_base64` is required.
example: agent_abc123
agent_image_url:
type: string
format: uri
description: >-
A publicly accessible URL to the avatar image. Exactly one of
`agent_id`, `agent_image_url`, or `agent_image_base64` is required.
example: https://cdn.lemonslice.com/agents/custom_agent.png
agent_image_base64:
type: string
description: >-
Base64-encoded avatar image bytes. Exactly one of `agent_id`,
`agent_image_url`, or `agent_image_base64` is required.
video_encoding:
type: string
enum:
- H264
- VP8
- AV1
description: >-
Video codec used for the avatar stream. `H264` provides the widest
client compatibility.
activity_idle_timeout:
type: number
default: 120
description: >-
Seconds of inactivity before the session is automatically
terminated. Set to `0` to disable the idle timeout. If no idle
timeout is configured, you must terminate the call explicitly.
agora_settings:
$ref: '#/components/schemas/AgoraSettings'
agent_prompt:
type: string
default: a person talking
description: >-
A high-level system prompt that subtly influences the avatar's
movements, expressions, and emotional demeanor while speaking. Best
used for general affect (for example, "feel excited" or "look sad")
rather than precise actions.
agent_idle_prompt:
description: >-
A high-level system prompt that influences the avatar's movements,
expressions, and emotional demeanor during the idle state.
type: string
default: a serious person
model:
type:
- string
- 'null'
enum:
- lite
- flash
- pro
- null
default: null
description: Model variant. Leave unset to use the normal flagship model.
x-mint:
post:
- 'default: null'
aspect_ratio:
description: Output aspect ratio for the avatar video.
type: string
enum:
- 2x3
- 9x16
- 1x1
default: 2x3
response_done_timeout:
type:
- number
- 'null'
default: null
description: >-
Time in seconds to wait without receiving new audio bytes before
marking the response as complete. Some TTS models do not send an
end-response event, or do not send it promptly. This parameter
enables completion detection when such events are missing or
delayed.
x-mint:
post:
- 'default: null'
AgoraSessionStartResponse:
type: object
required:
- session_id
- websocket_address
- session_token
properties:
session_id:
type: string
description: Unique identifier for this LemonSlice session.
websocket_address:
type: string
description: WebSocket URL Agora uses for the avatar audio/video tunnel.
session_token:
type: string
description: >-
Token used to authenticate the WebSocket tunnel and session stop
requests.
AgoraError:
type: object
properties:
error:
type: string
message:
type: string
code:
type: string
AgoraSettings:
type: object
description: >-
Agora RTC connection settings for the LemonSlice avatar participant.
Populated by Agora when using the generic avatar vendor.
required:
- app_id
- token
- channel
- uid
- enable_string_uid
properties:
app_id:
type: string
description: Agora application identifier.
token:
type: string
description: >-
Agora RTC token that authorizes the avatar UID to join the channel
with publish permission.
channel:
type: string
description: Name of the Agora RTC channel to join.
uid:
type: string
description: >-
RTC UID the LemonSlice avatar publishes under. Must be distinct from
the Agora agent UID and end-user UID.
enable_string_uid:
type: boolean
description: Whether `uid` should be treated as a string UID.
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your LemonSlice API token.
````