Skip to main content
POST
/
liveai
/
sessions
curl --request POST \
  --url https://lemonslice.com/api/liveai/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "agent_image_url": "https://cdn.lemonslice.com/agents/custom_agent.png",
  "agent_prompt": "a person talking",
  "transport_type": "livekit",
  "properties": {
    "livekit_url": "wss://lemonslice-pb123.livekit.cloud",
    "livekit_token": "eyJhbGciOiJIUzI1NiIsInR5a..."
  }
}
'
{
  "session_id": "livekit-3f7c2b91-9e1f-4a6a-8e9d-2c7c3e7d9b5a"
}

Authorizations

​
X-API-Key
string
header
required

Your LemonSlice API token.

Body

application/json

The properties used to create an agent session.

Input to create an agent session. Exactly one of agent_id or agent_image_url must be provided.

​
agent_image_url
string<uri>
required

A URL to an agent image to use. The image should be 368x560 pixels. LemonSlice will automatically center-crop your image to the target aspect ratio if the dimensions do not match the expected values. Provide either agent_image_url or agent_id, but not both.

Example:

"https://example.com/custom_agent.png"

​
transport_type
enum<string>
required

The interface type for how the audio is sent and how the A/V is returned.

Available options:
livekit,
daily
Example:

"livekit"

​
agent_id
string

The ID of the LemonSlice agent. Provide either agent_id or agent_image_url, but not both.

Example:

"agent_abc123"

​
agent_prompt
string
default:a person talking

A high-level system prompt that subtly influences the avatar's movements, expressions, and emotional demeanor. This prompt is best used to suggest general affect or demeanor (for example, 'feel excited' or 'look sad') rather than precise or deterministic actions.

Example:

"a person talking"

​
agent_idle_prompt
string
default:a serious person

A high-level system prompt that influences the avatar's movements, expressions, and emotional demeanor during the idle state.

Example:

"a serious person"

​
idle_timeout
integer
default:60

Idle timeout in seconds. Defaults to 60. If a negative number is provided, the session will have no idle timeout.

Example:

60

​
response_done_timeout
number

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 in a timely manner. This parameter enables detection of response completion when such events are missing or delayed.

Example:

0.5

​
properties
object

Additional properties needed to connect to the transport layer

Example:
{
  "livekit_url": "wss://lemonslice-pb123.livekit.cloud",
  "livekit_token": "eyJhbGciOiJIUzI1NiIsInR5a..."
}

Response

Session created successfully.

​
session_id
string
required

The ID of the session.

Example:

"livekit-3f7c2b91-9e1f-4a6a-8e9d-2c7c3e7d9b5a"