LemonSlice

https://lemonslice.com/docs
Admin
LemonSlice is a conversational AI service that enables developers to add interactive video avatars...
Tokens:30,667
Snippets:269
Trust Score:8.2
Update:4 months ago
Show doc for...
Tokens:
Raw
### Create Room Authentication Example

Source: https://lemonslice.com/docs/hosted/endpoint/authentication

This example demonstrates how to authenticate a request to create a room using an API key in the request header.

```APIDOC
## POST /api/liveai/rooms

### Description
Creates a new room for live AI interaction.

### Method
POST

### Endpoint
/api/liveai/rooms

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent to use for the room.

### Request Example
```json
{
  "agent_id": "YOUR_AGENT_ID"
}
```

### Headers
- **X-API-Key** (string) - Required - Your API key for authentication.
- **Content-Type** (string) - Required - Set to application/json.
```

--------------------------------

### OpenAPI Schema Examples

Source: https://lemonslice.com/docs/api-reference/get-hosted-session

Examples of OpenAPI schema components, including Error and ServerError schemas, and an example of an API key authentication scheme.

```yaml
components:
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
          example: Agent not found
    ServerError:
      type: object
      properties:
        detail:
          type: string
          example: Internal server error
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your LemonSlice API token.
```

--------------------------------

### Example: Completed Session Status with Cost

Source: https://lemonslice.com/docs/api-reference/get-self-managed-session

This example shows the JSON response when a session has successfully completed. It includes the total cost in credits.

```json
{
  "session_status": "COMPLETED",
  "cost": 10.5
}
```

--------------------------------

### Install Pipecat with LemonSlice

Source: https://lemonslice.com/docs/self-managed/integrations/pipecat-integration

Install the Pipecat AI package with the LemonSlice extra dependency using pip.

```shell
pip install "pipecat-ai[lemonslice]"
```

--------------------------------

### OpenAPI Example: Self-Managed Session Configuration

Source: https://lemonslice.com/docs/api-reference/create-self-managed-session

This example shows the structure for configuring a self-managed session, including recording bucket details and API authentication.

```yaml
openapi: 3.0.0
info:
  title: LemonSlice API
  version: 1.0.0
servers:
  - url: https://api.lemonslice.com/v1
paths:
  /sessions/self-managed:
    post:
      summary: Create a self-managed session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enable_recording:
                  description: >-
                    Whether to enable recording for the session.
                  type: boolean
                recordings_bucket:
                  description: >-
                    The S3 bucket configuration where recordings will be saved.
                    Follows the Daily recording bucket specification.
                  type: object
                  properties:
                    bucket_name:
                      description: The name of the S3 bucket.
                      type: string
                    bucket_region:
                      description: The AWS region of the S3 bucket.
                      type: string
                    assume_role_arn:
                      description: The ARN of the IAM role for Daily to assume for storage.
                      type: string
                    allow_api_access:
                      description: >-
                        Whether Daily's recording access link API should allow
                        downloading the recording.
                      type: boolean
                  required:
                    - bucket_name
                    - bucket_region
                    - assume_role_arn
      dependentRequired:
        enable_recording:
          - recordings_bucket
      additionalProperties: true
      example:
        daily_room_url: https://your-domain.daily.co/your-room
        daily_token: eyJhbGciOiJIUzI1NiIsInR5c...
security:
  - apiKeyAuth:
    - "read:session"
securitySchemes:
  apiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key
    description: Your LemonSlice API token.
```

--------------------------------

### Example: Custom Widget Sizes

Source: https://lemonslice.com/docs/widget/customization

Illustrates setting custom dimensions for both the active and minimized states of the widget.

```html
<lemon-slice-widget
  agent-id="agent_id"
  custom-active-width="400"
  custom-active-height="600"
  custom-minimized-width="120"
  custom-minimized-height="120"
></lemon-slice-widget>
```

--------------------------------

### Example: Active Session Status

Source: https://lemonslice.com/docs/api-reference/get-self-managed-session

This example shows the JSON response when a session is actively running. The 'cost' field is not present in this state.

```json
{
  "session_status": "ACTIVE"
}
```

--------------------------------

### Example: Queued Session Status

Source: https://lemonslice.com/docs/api-reference/get-self-managed-session

This example shows the JSON response when a session is in the QUEUED state. It indicates that the session is waiting for resources.

```json
{
  "session_status": "QUEUED"
}
```

--------------------------------

### Add AvatarSession to AgentSession (Python)

Source: https://lemonslice.com/docs/self-managed/integrations/livekit-agent-integration

Integrate a LemonSlice AvatarSession into your LiveKit AgentSession in Python. This example shows how to initialize and start the avatar session.

```python
from livekit import agents
from livekit.agents import AgentSession, RoomOutputOptions
from livekit.plugins import lemonslice

async def entrypoint(ctx: agents.JobContext):
    await ctx.connect()

    session = AgentSession(
        # Add STT, LLM, TTS, and other components here
    )

    avatar = lemonslice.AvatarSession(
        # Publicly accessible image URL for the avatar
        agent_image_url="...",
        # Prompt to guide the avatar's demeanor
        agent_prompt="a person talking"
    )

    # Start the avatar and wait for it to join
    session_id = await avatar.start(session, room=ctx.room)

    # Start your agent session with the user
    await session.start(
        # ... room, agent, room_options, etc....
    )
```

--------------------------------

### Example: Failed Session Status

Source: https://lemonslice.com/docs/api-reference/get-self-managed-session

This example shows the JSON response when a session has ended with an error. The 'cost' field is not included.

```json
{
  "session_status": "FAILED"
}
```

--------------------------------

### Example: Custom Button Color

Source: https://lemonslice.com/docs/widget/customization

Shows how to customize both the hex color and opacity of the video chat button.

```html
<lemon-slice-widget
  agent-id="agent_id"
  video-button-color-hex="#FF4FD8"
  video-button-color-opacity="0.8"
></lemon-slice-widget>
```

--------------------------------

### Successful Session Creation Response

Source: https://lemonslice.com/docs/api-reference/create-self-managed-session

Example response when a session is created successfully, including the session ID.

```json
{
  "session_id": "livekit-3f7c2b91-9e1f-4a6a-8e9d-2c7c3e7d9b5a"
}
```

--------------------------------

### Example: Timed Out Session Status

Source: https://lemonslice.com/docs/api-reference/get-self-managed-session

This example shows the JSON response when a session has timed out. The 'cost' field is not included.

```json
{
  "session_status": "TIMED_OUT"
}
```

--------------------------------

### Add AvatarSession to AgentSession (Node.js)

Source: https://lemonslice.com/docs/self-managed/integrations/livekit-agent-integration

Integrate a LemonSlice AvatarSession into your LiveKit AgentSession in JavaScript. This example demonstrates initializing and starting the avatar session.

```javascript
import { voice } from '@livekit/agents';
import * as lemonslice from '@livekit/agents-plugin-lemonslice';

const session = new voice.AgentSession({
    // Add STT, LLM, TTS, and other components here
});

const avatar = new lemonslice.AvatarSession({
    // Publicly accessible image URL for the avatar
    agentImageUrl: "...",
    // Prompt to guide the avatar's demeanor
    agentPrompt: "a person talking",
});

// Start the avatar and wait for it to join
const sessionId = await avatar.start(session, room);

// Start your agent session with the user
await session.start(
    // ... room, agent, room_options, etc.
);
```

--------------------------------

### Install LiveKit Agents LemonSlice Plugin (Python)

Source: https://lemonslice.com/docs/self-managed/integrations/livekit-agent-integration

Install the LiveKit Agents LemonSlice plugin using pip. This command adds the necessary dependencies for using LemonSlice features.

```shell
# When using PIP
pip install "livekit-agents[lemonslice]"

# When using UV
uv add "livekit-agents[lemonslice]"
```

--------------------------------

### Error Response: Agent Not Found

Source: https://lemonslice.com/docs/api-reference/create-self-managed-session

Example error response when the specified agent cannot be found.

```json
{
  "detail": "Agent not found"
}
```

--------------------------------

### Create Session using Agent Image URL

Source: https://lemonslice.com/docs/api-reference/create-self-managed-session

Example of creating a self-managed session by providing an agent image URL. Requires agent_image_url, agent_prompt, transport_type, and LiveKit properties.

```json
{
  "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..."
  }
}
```

--------------------------------

### Install LiveKit Agents LemonSlice Plugin (Node.js)

Source: https://lemonslice.com/docs/self-managed/integrations/livekit-agent-integration

Add the LiveKit Agents LemonSlice plugin to your Node.js project using pnpm. This installs the package required for LemonSlice integration.

```shell
pnpm add @livekit/agents-plugin-lemonslice
```

--------------------------------

### API Error Response Examples

Source: https://lemonslice.com/docs/api-reference/get-hosted-session

Examples of common API error responses, including authentication denial, room ownership issues, room not found, and internal server errors.

```yaml
'401':
  description: Authentication denied
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Error'
      example:
        detail: Invalid API key
'403':
  description: Room does not belong to this account
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Error'
      example:
        detail: Room does not belong to this account
'404':
  description: Room not found
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Error'
      example:
        detail: Room not found
'500':
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ServerError'
      example:
        detail: Internal server error
```

--------------------------------

### Error Response: Insufficient Funds

Source: https://lemonslice.com/docs/api-reference/create-self-managed-session

Example error response when the agent owner has insufficient funds.

```json
{
  "detail": "Agent agent_123abc owner has insufficient funds"
}
```

--------------------------------

### Error Response: Authentication Denied

Source: https://lemonslice.com/docs/api-reference/create-self-managed-session

Example error response when authentication fails due to an invalid API key.

```json
{
  "detail": "Invalid API key"
}
```

--------------------------------

### Create Session using Agent ID

Source: https://lemonslice.com/docs/api-reference/create-self-managed-session

Example of creating a self-managed session by providing an agent ID. Requires agent_id, transport_type, and LiveKit properties.

```json
{
  "agent_id": "agent_abc123",
  "transport_type": "livekit",
  "properties": {
    "livekit_url": "wss://lemonslice-pb123.livekit.cloud",
    "livekit_token": "eyJhbGciOiJIUzI1NiIsInR5a..."
  }
}
```

--------------------------------

### Create Session using Daily Transport

Source: https://lemonslice.com/docs/api-reference/create-self-managed-session

Example of creating a self-managed session using the Daily transport. Requires agent_id, transport_type, and Daily room/token properties.

```json
{
  "agent_id": "agent_abc123",
  "transport_type": "daily",
  "properties": {
    "daily_room_url": "https://your-domain.daily.co/your-room",
    "daily_token": "eyJhbGciOiJIUzI1NiIsInR5a..."
  }
}
```

--------------------------------

### Error Response: Invalid Arguments

Source: https://lemonslice.com/docs/api-reference/create-self-managed-session

Example error response when invalid arguments are provided during session creation.

```json
{
  "detail": "Missing required fields"
}
```

--------------------------------

### Handle LemonSlice Events in Daily App

Source: https://lemonslice.com/docs/hosted/integrations/daily-room-integration

Listen for 'app-message' events from Daily to receive agent status updates. This example shows how to log when the agent is ready or if an error occurs.

```javascript
useDailyEvent("app-message", (ev) => {
  if (ev?.data?.type === "bot_ready") {
    console.log("Agent is ready!");
  }
  if (ev?.data?.type === "daily_error") {
    console.log("An error occurred. ", ev?.data?.err_msg);
  }
});
```

--------------------------------

### Pose Trigger Example

Source: https://lemonslice.com/docs/api-reference/control-self-managed-session

Use this event to trigger a specific action sequence on the active avatar. Replace `<ACTION_NAME>` with the desired action.

```json
{
  "event": "pose-trigger",
  "pose_trigger": {
    "name": "<ACTION_NAME>"
  }
}
```

--------------------------------

### Update Image Example

Source: https://lemonslice.com/docs/api-reference/control-self-managed-session

Use this event to update the avatar's base image. This resets the model and may cut off audio. The image swap takes up to 5 seconds.

```json
{
  "event": "update-image",
  "image_url": "https://example.com/avatar.jpg"
}
```

--------------------------------

### Error Response: Agent Not Owned

Source: https://lemonslice.com/docs/api-reference/create-self-managed-session

Example error response when the requested agent is not owned by the authenticated user.

```json
{
  "detail": "Agent agent_123abc is not owned by the authenticated user"
}
```

--------------------------------

### Error Response: Internal Server Error

Source: https://lemonslice.com/docs/api-reference/create-self-managed-session

Example error response for unexpected internal server errors.

```json
{
  "detail": "Internal server error"
}
```

--------------------------------

### API Response Example (Error)

Source: https://lemonslice.com/docs/api-reference/control-self-managed-session

An error response indicates an invalid event or missing required fields. The 'detail' field provides more information.

```json
{
  "detail": "image_url required for update-image event"
}
```

--------------------------------

### Update Agent Prompt Example

Source: https://lemonslice.com/docs/api-reference/control-self-managed-session

Use this event to update the agent prompt, influencing the avatar's expressions while speaking. This prompt is best used for general demeanor.

```json
{
  "event": "update-agent-prompt",
  "agent_prompt": "a person talking"
}
```

--------------------------------

### Trigger Action on Call Event with LiveKit Agents

Source: https://lemonslice.com/docs/guides/actions-guide

Trigger an action reliably after the avatar is ready at the start of a call. This pattern avoids race conditions by waiting for the avatar session to be prepared before sending control calls.

```python
avatar = lemonslice.AvatarSession(...)
session_id = await avatar.start(session, room=ctx.room)

avatar_ready = await wait_for_avatar_ready(session_id)
if not avatar_ready:
    return
await trigger_action("wave")
await session.generate_reply(instructions="Greet the user.")
```

--------------------------------

### Update Idle Prompt Example

Source: https://lemonslice.com/docs/api-reference/control-self-managed-session

Use this event to update the idle prompt, influencing the avatar's expressions during the idle state. This prompt is best used for general demeanor.

```json
{
  "event": "update-idle-prompt",
  "idle_prompt": "a serious person"
}
```

--------------------------------

### Get Self-Managed Session OpenAPI Specification

Source: https://lemonslice.com/docs/api-reference/get-self-managed-session

This OpenAPI specification defines the GET /liveai/sessions/{session_id} endpoint for retrieving session status. It includes parameters, responses, and examples for different session states.

```yaml
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/sessions/{session_id}:
    get:
      summary: Get self-managed session
      description: >-
        Retrieves the current status of a self-managed session. When the session
        is completed, returns additional metadata about the session.
      operationId: getSession
      parameters:
        - name: session_id
          in: path
          description: The ID of the session to retrieve.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            Session status retrieved successfully. Returns basic status for all
            states. When completed, includes the total cost in credits.
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_status:
                    type: string
                    enum:
                      - QUEUED
                      - ACTIVE
                      - COMPLETED
                      - TIMED_OUT
                      - FAILED
                    description: >-
                      Current status of the session:


                      - **QUEUED**: session is waiting for a GPU container. Typically completes in seconds when warm containers are available. If all warm containers are in use, a cold start is required which may take up to 2.5 minutes.

                      - **ACTIVE**: agent is live.

                      - **COMPLETED**: session ended successfully.

                      - **TIMED_OUT**: GPU container timed out.

                      - **FAILED**: session ended with an error.
                  cost:
                    type: number
                    description: >-
                      Number of credits used for this session. Only returned
                      when session_status is COMPLETED.
                required:
                  - session_status
              examples:
                queued:
                  summary: Session is queued
                  value:
                    session_status: QUEUED
                active:
                  summary: Session is active
                  value:
                    session_status: ACTIVE
                completed:
                  summary: Session completed
                  value:
                    session_status: COMPLETED
                    cost: 10.5
                timed_out:
                  summary: Session timed out
                  value:
                    session_status: TIMED_OUT
                failed:
                  summary: Session failed
                  value:
                    session_status: FAILED
        '401':
          description: Authentication denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Invalid API key
        '403':
          description: Session not owned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Session does not belong to this account
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Session not found
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                detail: Internal server error
components:
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
          example: Agent not found
    ServerError:
      type: object
      properties:
        detail:
          type: string
          example: Internal server error
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your LemonSlice API token.

```

--------------------------------

### OpenAPI Specification for Get Hosted Session

Source: https://lemonslice.com/docs/api-reference/get-hosted-session

This OpenAPI 3.1.0 specification defines the GET /liveai/rooms/{session_id} endpoint for retrieving hosted session status. It outlines request parameters, response schemas, and provides examples for queued, active, and completed sessions.

```yaml
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/rooms/{session_id}:
    get:
      summary: Get hosted session
      description: >-
        Retrieves the current status of a hosted session. Includes additional
        metadata when the session is completed.
      operationId: getRoomStatus
      parameters:
        - name: session_id
          in: path
          description: The session identifier returned upon creation.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            Returns basic status of session. When completed, includes additional
            metadata such as cost, timestamps, end reason, and conversation
            messages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_status:
                    type: string
                    enum:
                      - QUEUED
                      - ACTIVE
                      - COMPLETED
                      - TIMED_OUT
                      - FAILED
                    description: >-
                      Current status of the session:

                      - **QUEUED**: session is waiting for a GPU container. Typically completes in seconds when warm containers are available. If all warm containers are in use, a cold start is required which may take up to 2.5 minutes.

                      - **ACTIVE**: agent is live.

                      - **COMPLETED**: session ended successfully.

                      - **TIMED_OUT**: GPU container timed out.

                      - **FAILED**: session ended with an error.
                  cost:
                    type: number
                    description: >-
                      Number of credits used for this session. Only returned
                      when session_status is COMPLETED.
                  llm_ended_reason:
                    type: string
                    description: >-
                      Reason the LLM session ended. Only returned when
                      session_status is COMPLETED.
                  llm_started_at:
                    type: integer
                    description: >-
                      Unix timestamp when the LLM session started. Only returned
                      when session_status is COMPLETED.
                  llm_ended_at:
                    type: integer
                    description: >-
                      Unix timestamp when the LLM session ended. Only returned
                      when session_status is COMPLETED.
                  messages:
                    type: array
                    description: >-
                      Array of messages exchanged during the session. Only
                      returned when session_status is COMPLETED.
                    items:
                      type: object
                      properties:
                        role:
                          type: string
                          enum:
                            - user
                            - agent
                          description: Role of the message sender.
                        message:
                          type: string
                          description: Content of the message.
                        seconds_from_start:
                          type: integer
                          description: >-
                            Number of seconds from the start of the session when
                            this message was sent.
                      required:
                        - role
                        - message
                        - seconds_from_start
                required:
                  - session_status
              examples:
                queued:
                  summary: Session is queued
                  value:
                    session_status: QUEUED
                active:
                  summary: Session is active
                  value:
                    session_status: ACTIVE
                completed:
                  summary: Session completed with full details
                  value:
                    session_status: COMPLETED
                    cost: 10.5
                    llm_ended_reason: 'Client disconnected: 1000'
                    llm_started_at: 1772746376
                    llm_ended_at: 1772746535
                    messages:
                      - role: user
                        message: hello
                        seconds_from_start: 0
                      - role: agent

```

--------------------------------

### Handle Startup Failures with LiveKit

Source: https://lemonslice.com/docs/self-managed/production-tips

Monitor agent status and send a startup failure message via WebRTC if the agent doesn't join the room. This allows the frontend to gracefully exit the call.

```javascript
import { Room, RoomEvent } from 'livekit-client';

const ROOM_MESSAGE_TOPIC = 'lemonslice/message'

const room = new Room();
const decoder = new TextDecoder();
room.on(
  RoomEvent.DataReceived,
  (payload, participant, kind, topic) => {
    if (topic !== ROOM_MESSAGE_TOPIC) return;

    try {
      const message = JSON.parse(decoder.decode(payload));

      if (message.type === 'startup_failure') {
        console.log('Room closing event received');
        room.disconnect();
        // TODO - swap to UI where the user can restart the call (inactive call)
      }
    } catch (err) {
      console.error('Failed to parse data packet:', err);
    }
  }
);

```

--------------------------------

### Initialize Agent Session with VAD, STT, LLM, and TTS

Source: https://lemonslice.com/docs/guides/livekit-guide

Sets up the core agent pipeline using specified VAD, STT, LLM, and TTS providers. Ensure the models and languages are correctly configured for your use case.

```typescript
session = AgentSession(
  vad=silero.VAD.load(),
  stt=inference.STT(
      model="deepgram/nova-2",
      language="en",
      extra_kwargs={"interim_results": False},
  ),
  llm=groq.LLM(model="llama-3.3-70b-versatile"),
  tts=agent_tts,
)
```

--------------------------------

### Create a LiveAI Room with API Key Authentication

Source: https://lemonslice.com/docs/hosted/endpoint/authentication

This snippet demonstrates how to create a LiveAI room using cURL. Ensure you replace 'YOUR_API_KEY' and 'YOUR_AGENT_ID' with your actual credentials. The API key must be included in the 'X-API-Key' header.

```bash
curl -X POST https://lemonslice.com/api/liveai/rooms \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "YOUR_AGENT_ID" }'
```

--------------------------------

### Create Daily Room

Source: https://lemonslice.com/docs/hosted/integrations/daily-room-integration

Use the `POST /liveai/rooms` endpoint to create a Daily room configured with a LemonSlice agent. The agent will automatically join the room once its startup is complete.

```APIDOC
## POST /liveai/rooms

### Description
Creates a Daily room and configures it with a LemonSlice agent that automatically joins upon startup.

### Method
POST

### Endpoint
https://lemonslice.com/api/liveai/rooms

### Headers
- **X-API-Key** (string) - Required - Your LemonSlice API key.
- **Content-Type** (string) - Required - application/json

### Request Body
- **agent_id** (string) - Required - The ID of the LemonSlice agent to join the room.

### Request Example
```json
{
  "agent_id": "YOUR_AGENT_ID"
}
```

### Response
#### Success Response (200)
- **room_url** (string) - The URL of the created Daily room.
- **token** (string) - The token required to join the room.
```

--------------------------------

### Create LemonSlice Transport Instance

Source: https://lemonslice.com/docs/self-managed/integrations/pipecat-integration

Instantiate the LemonSliceTransport with bot name, API key, aiohttp session, and session request parameters. Ensure the LEMONSLICE_API_KEY is set in your environment.

```python
import os
import aiohttp
from pipecat.transports.lemonslice.transport import (
    LemonSliceNewSessionRequest,
    LemonSliceParams,
    LemonSliceTransport,
)

async def main():
    async with aiohttp.ClientSession() as session:
        transport = LemonSliceTransport(
            bot_name="Pipecat",
            api_key=os.getenv("LEMONSLICE_API_KEY"),
            session=session,
            session_request=LemonSliceNewSessionRequest(
                agent_image_url="...",
            ),
        )

        # stt, tts, llm...
```

--------------------------------

### Join Daily Room with Daily JavaScript SDK

Source: https://lemonslice.com/docs/hosted/integrations/daily-room-integration

Use Daily's JavaScript SDK to join a room. Provide the room URL and token obtained from the room creation API. The LemonSlice agent will connect once the room is joined.

```javascript
import DailyIframe from "@daily-co/daily-js";

const callObject = DailyIframe.createCallObject();

await callObject.join({
  url: room_url,
  token: token
});
```

--------------------------------

### Terminate Session Example

Source: https://lemonslice.com/docs/api-reference/control-self-managed-session

Use this event to immediately shut down the LemonSlice avatar and remove it from the WebRTC room.

```json
{
  "event": "terminate"
}
```

--------------------------------

### Create Self-Managed Session

Source: https://lemonslice.com/docs/llms.txt

Creates a self-managed session that takes in avatar audio and returns synchronized video/audio.

```APIDOC
## POST /create-self-managed-session

### Description
Creates a self-managed session that takes in avatar audio and returns synchronized video/audio.

### Method
POST

### Endpoint
/create-self-managed-session

### Parameters
#### Request Body
- **audio_stream_url** (string) - Required - The URL of the avatar audio stream.
- **session_config** (object) - Optional - Configuration for the self-managed session.
```

--------------------------------

### Get Hosted Session

Source: https://lemonslice.com/docs/llms.txt

Retrieves the current status of a hosted session. Includes additional metadata when the session is completed.

```APIDOC
## GET /get-hosted-session

### Description
Retrieves the current status of a hosted session. Includes additional metadata when the session is completed.

### Method
GET

### Endpoint
/get-hosted-session

### Parameters
#### Query Parameters
- **session_id** (string) - Required - The ID of the hosted session.
```

--------------------------------

### Get Hosted Session Status

Source: https://lemonslice.com/docs/api-reference/get-hosted-session

Fetches the status of a hosted session. If the session is completed, additional metadata will be returned.

```APIDOC
## GET /hosted-sessions/{sessionId}

### Description
Retrieves the current status of a hosted session. Includes additional metadata when the session is completed.

### Method
GET

### Endpoint
/hosted-sessions/{sessionId}

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The unique identifier of the hosted session.

### Response
#### Success Response (200)
- **status** (string) - The current status of the session (e.g., "in_progress", "completed", "failed").
- **metadata** (object) - Optional - Additional metadata, available only when the session is completed. Contains details specific to the completed session.
```

--------------------------------

### Get Hosted Session Status

Source: https://lemonslice.com/docs/api-reference/get-hosted-session

Retrieves the current status of a hosted session. Includes additional metadata when the session is completed.

```APIDOC
## GET /liveai/rooms/{session_id}

### Description
Retrieves the current status of a hosted session. Includes additional metadata when the session is completed.

### Method
GET

### Endpoint
/liveai/rooms/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The session identifier returned upon creation.

### Response
#### Success Response (200)
- **session_status** (string) - Enum: QUEUED, ACTIVE, COMPLETED, TIMED_OUT, FAILED - Current status of the session.
- **cost** (number) - Optional - Number of credits used for this session. Only returned when session_status is COMPLETED.
- **llm_ended_reason** (string) - Optional - Reason the LLM session ended. Only returned when session_status is COMPLETED.
- **llm_started_at** (integer) - Optional - Unix timestamp when the LLM session started. Only returned when session_status is COMPLETED.
- **llm_ended_at** (integer) - Optional - Unix timestamp when the LLM session ended. Only returned when session_status is COMPLETED.
- **messages** (array) - Optional - Array of messages exchanged during the session. Only returned when session_status is COMPLETED.
  - **role** (string) - Enum: user, agent - Role of the message sender.
  - **message** (string) - Content of the message.
  - **seconds_from_start** (integer) - Number of seconds from the start of the session when this message was sent.

#### Response Example
```json
{
  "session_status": "COMPLETED",
  "cost": 10.5,
  "llm_ended_reason": "Client disconnected: 1000",
  "llm_started_at": 1772746376,
  "llm_ended_at": 1772746535,
  "messages": [
    {
      "role": "user",
      "message": "hello",
      "seconds_from_start": 0
    },
    {
      "role": "agent",
      "message": "Hi there! How can I help you today?",
      "seconds_from_start": 2
    }
  ]
}
```
```

--------------------------------

### Get self-managed session

Source: https://lemonslice.com/docs/api-reference/get-self-managed-session

Retrieves the current status of a self-managed session. When the session is completed, returns additional metadata about the session.

```APIDOC
## GET /liveai/sessions/{session_id}

### Description
Retrieves the current status of a self-managed session. When the session is completed, returns additional metadata about the session.

### Method
GET

### Endpoint
/liveai/sessions/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session to retrieve.

### Response
#### Success Response (200)
- **session_status** (string) - Enum: QUEUED, ACTIVE, COMPLETED, TIMED_OUT, FAILED - Current status of the session.
- **cost** (number) - Optional - Number of credits used for this session. Only returned when session_status is COMPLETED.

#### Response Example
```json
{
  "session_status": "COMPLETED",
  "cost": 10.5
}
```

#### Error Responses
- **401** - Authentication denied
- **403** - Session not owned
- **404** - Session not found
- **500** - Unexpected error
```

--------------------------------

### List Widget Sessions

Source: https://lemonslice.com/docs/widget/call-metadata

Use this endpoint to retrieve a paginated list of widget sessions associated with your account. Include your API key in the request headers.

```bash
curl -X GET "https://lemonslice.com/api/liveai/rooms?page=1&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------

### Create Self-Managed Session Configuration

Source: https://lemonslice.com/docs/api-reference/create-self-managed-session

This snippet outlines the configuration for creating a self-managed session, focusing on recording storage details.

```APIDOC
## POST /sessions/self-managed

### Description
Initiates a self-managed session. This endpoint allows for detailed configuration, including where session recordings should be stored.

### Method
POST

### Endpoint
/sessions/self-managed

### Request Body
- **recordings_bucket** (object) - Required - The S3 bucket configuration where recordings will be saved.
  - **bucket_name** (string) - Required - The name of the S3 bucket.
  - **bucket_region** (string) - Required - The AWS region of the S3 bucket.
  - **assume_role_arn** (string) - Required - The ARN of the IAM role for Daily to assume for storage.
  - **allow_api_access** (boolean) - Optional - Whether Daily's recording access link API should allow downloading the recording.

### Request Example
```json
{
  "recordings_bucket": {
    "bucket_name": "your-s3-bucket-name",
    "bucket_region": "us-east-1",
    "assume_role_arn": "arn:aws:iam::123456789012:role/DailyRecordingRole",
    "allow_api_access": true
  }
}
```

### Response
#### Success Response (201 Created)
- **session_id** (string) - The unique identifier for the created session.
- **daily_room_url** (string) - The URL for the Daily room.
- **daily_token** (string) - A token for accessing the Daily room.

#### Response Example
```json
{
  "session_id": "sess_abcdef123456",
  "daily_room_url": "https://your-domain.daily.co/your-room",
  "daily_token": "eyJhbGciOiJIUzI1NiIsInR5c..."
}
```

### Error Handling
- **400 Bad Request**: If the request body is invalid or missing required fields.
- **401 Unauthorized**: If the API key is invalid.
- **500 Internal Server Error**: If there was an issue on the server.
```

--------------------------------

### Control LemonSlice Widget Methods

Source: https://lemonslice.com/docs/widget/control

Use these methods to programmatically control the widget's audio, microphone, and message sending. `micOn()` and `sendMessage()` automatically handle user interaction, widget state, and room creation/joining.

```javascript
const widget = document.querySelector('lemon-slice-widget');

// Turn on microphone (will start room automatically)
await widget.micOn();

// Send a message (will start room automatically if needed)
await widget.sendMessage('Hello, agent!');

// Check microphone status
if (widget.isMicOn()) {
  console.log('Microphone is on');
}

// Mute audio
await widget.mute();

// Check if muted
if (widget.isMuted()) {
  console.log('Audio is muted');
}
```

--------------------------------

### Provide Visual and Functional Context for Video Agents

Source: https://lemonslice.com/docs/guides/prompt-engineering

Include detailed descriptions of the agent's appearance and capabilities, including its underlying technology. This helps the agent maintain conversational flow when asked about its nature or appearance.

```text
You are powered by a cutting-edge pipeline of STT, LLM, TTS, and a diffusion transformer video model for the avatar. The user is speaking to you via a browser. You appear as a young woman with light skin, large brown eyes, dark brown hair in a loose updo with bangs, wearing a fitted black top, and a thin necklace. You are in your room, with a window view of a hilly town in the background.
```

--------------------------------

### Handle Bot Ready RPC for Video Loading State

Source: https://lemonslice.com/docs/guides/livekit-guide

Subscribes to the 'lemonslice' data channel to detect when the bot is ready, indicated by a 'bot_ready' message type. This is used to update the UI to show the video call is loaded.

```typescript
const LEMONSLICE_RPC_TOPIC = "lemonslice";
const BOT_READY_MSG_TYPE = "bot_ready";

const onLemonsliceData = useCallback((msg: ReceivedDataMessage<typeof LEMONSLICE_RPC_TOPIC>) => {
    let parsed: unknown;
    try {
      parsed = JSON.parse(new TextDecoder().decode(msg.payload));
    } catch {
      return;
    }
    if (
      typeof parsed !== "object" ||
      parsed === null ||
      (parsed as { type?: unknown }).type !== BOT_READY_MSG_TYPE
    ) {
      return;
    }
    setAvatarJoined(true);
  }, []);

  /** Subscribes to the single shared data channel; `topic` filters to LemonSlice RPC only. */
  useDataChannel(LEMONSLICE_RPC_TOPIC, onLemonsliceData);
```

--------------------------------

### Configure LemonSlice Idle Timeout

Source: https://lemonslice.com/docs/self-managed/production-tips

Update the `idle_timeout` parameter when starting an AvatarSession to manage how long the avatar remains active without user interaction. Setting it to -1 disables the timeout.

```python
import lemonslice

# Assuming 'session' and 'ctx' are defined elsewhere
avatar = lemonslice.AvatarSession(
    agent_image_url="....",
    agent_prompt="a person talking.",
    idle_timeout=600,  # update this LemonSlice parameter
)
session_id = await avatar.start(session, room=ctx.room)

```

--------------------------------

### Get Hosted Session

Source: https://lemonslice.com/docs/api-reference/get-hosted-session

Retrieves the status and details of a hosted session. This endpoint can return a success message, indicate a timeout or failure, or provide specific error details for authentication, authorization, or server issues.

```APIDOC
## GET /hosted/session

### Description
Retrieves the status and details of a hosted session. This endpoint can return a success message, indicate a timeout or failure, or provide specific error details for authentication, authorization, or server issues.

### Method
GET

### Endpoint
/hosted/session

### Parameters
#### Query Parameters
- **session_id** (string) - Required - The ID of the session to retrieve.

### Response
#### Success Response (200)
- **message** (string) - A success message from the assistant.
- **seconds_from_start** (integer) - The number of seconds from the start of the session.
- **timed_out** (object) - Information about session timeout.
  - **session_status** (string) - The status of the session, e.g., "TIMED_OUT".
- **failed** (object) - Information about session failure.
  - **session_status** (string) - The status of the session, e.g., "FAILED".

#### Error Response (401)
- **detail** (string) - Description of the authentication error.

#### Error Response (403)
- **detail** (string) - Description of the authorization error.

#### Error Response (404)
- **detail** (string) - Description of the not found error.

#### Error Response (500)
- **detail** (string) - Description of the internal server error.

### Response Example
#### Success Response (200)
```json
{
  "message": "Hello! How can I assist you today?",
  "seconds_from_start": 10,
  "timed_out": {
    "session_status": "TIMED_OUT"
  },
  "failed": {
    "session_status": "FAILED"
  }
}
```

#### Error Response Example (401)
```json
{
  "detail": "Invalid API key"
}
```
```

--------------------------------

### Create Hosted Session Request

Source: https://lemonslice.com/docs/api-reference/create-room

Use this cURL command to send a POST request to create a new hosted session. Ensure you replace '<api-key>' with your actual API key and provide the desired agent_id.

```cURL
curl --request POST \
  --url https://lemonslice.com/api/liveai/rooms \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "agent_id": "agent_abc123"
}'
```

--------------------------------

### List Self-Managed Sessions OpenAPI Specification

Source: https://lemonslice.com/docs/api-reference/list-self-managed-sessions

This OpenAPI 3.1.0 specification defines the endpoint for listing self-managed sessions. It includes details on request parameters, response schemas, and example payloads for successful retrieval and error conditions.

```yaml
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/sessions:
    get:
      summary: List self-managed sessions
      description: Returns paginated self-managed sessions for the authenticated account.
      operationId: listSessions
      parameters:
        - name: page
          in: query
          description: Page number (1-indexed).
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Number of sessions per page.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
      responses:
        '200':
          description: Sessions retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessions:
                    type: array
                    items:
                      type: object
                      properties:
                        session_id:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        session_status:
                          type: string
                        credits_used:
                          type:
                            - number
                            - 'null'
                        provider:
                          type:
                            - string
                            - 'null'
                      required:
                        - session_id
                        - created_at
                        - session_status
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      total:
                        type: integer
                      total_pages:
                        type: integer
                      has_more:
                        type: boolean
                    required:
                      - page
                      - limit
                      - total
                      - total_pages
                      - has_more
                required:
                  - sessions
                  - pagination
              example:
                sessions:
                  - session_id: livekit-3f7c2b91-9e1f-4a6a-8e9d-2c7c3e7d9b5a
                    created_at: '2026-04-29T20:34:56.000Z'
                    session_status: COMPLETED
                    credits_used: 10.5
                    provider: LIVEKIT
                pagination:
                  page: 1
                  limit: 25
                  total: 1
                  total_pages: 1
                  has_more: false
        '400':
          description: Invalid pagination request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Requested page is too deep. Maximum offset is 1000.
        '401':
          description: Authentication denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Invalid API key
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                detail: Internal server error
components:
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
          example: Agent not found
    ServerError:
      type: object
      properties:
        detail:
          type: string
          example: Internal server error
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your LemonSlice API token.

```

--------------------------------

### Create LiveAI Session

Source: https://lemonslice.com/docs/self-managed/endpoint/authentication

This endpoint is used to create a new LiveAI session. Authentication is required via an API key in the header.

```APIDOC
## POST /api/liveai/sessions

### Description
Creates a new LiveAI session.

### Method
POST

### Endpoint
/api/liveai/sessions

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent to use for the session.

### Request Example
{
  "agent_id": "YOUR_AGENT_ID"
}

### Headers
- **X-API-Key** (string) - Required - Your API key for authentication.
- **Content-Type** (string) - Required - application/json
```

--------------------------------

### Handle Avatar Connect/Disconnect Events

Source: https://lemonslice.com/docs/self-managed/production-tips

Listen for 'bot_ready' and 'ParticipantDisconnected' events to manage UI states for active and inactive calls. Use 'bot_ready' for robust UI transitions after video frames are visible. 'ParticipantDisconnected' signals the avatar leaving, prompting a switch to an inactive UI.

```javascript
import { Room, RoomEvent } from "livekit-client";

const AVATAR_IDENTITY = "lemonslice-avatar-agent";
const LEMONSLICE_RPC_TOPIC = "lemonslice";

const room = new Room(...); // Logic to join to the LiveKit room

room.on(RoomEvent.DataReceived, (payload, participant, kind, topic) => {
    if (topic !== LEMONSLICE_RPC_TOPIC) return;

    try {
        const data = new TextDecoder().decode(payload);

        if (data === null || typeof data !== "object") return;

        if (data.type === "bot_ready") {
            console.log(`Avatar is ready! session_id = ${data.session_id}`);
            // TODO - swap over to active call UI.
            // We recommend staying in the "ringing" state until the avatar has joined. 
        }
    } catch (e) {
        console.warn("Unable to decode LemonSlice RPC JSON", e);
    }
});

room.on(RoomEvent.ParticipantDisconnected, (participant) => {
    if (participant.identity === AVATAR_IDENTITY) {
        console.log("LemonSlice avatar left");
        room.disconnect();
        // TODO - swap over to inactive call UI. Users can reinitiate a new call from here. 
    }
});
```
Tokens:
Raw