Skip to main content

​
Starter App

Find a working example on how to use the hosted pipeline in our LemonSlice Examples GitHub Repo.

​
Getting Started

Follow these steps to create your first LemonSlice agent session and integrate it into your application.

​
1. Get your API key

Retrieve your API Key from the LemonSlice dashboard. All API requests must include this header: 
X-API-Key: YOUR_API_KEY

​
2. Create a room

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.
Example request
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" }'

​
3. Join the room from your frontend

Use Daily’s JavaScript SDK to join the room with the URL and token returned by the API.
Example (JavaScript)
import DailyIframe from "@daily-co/daily-js";

const callObject = DailyIframe.createCallObject();

await callObject.join({
  url: room_url,
  token: token
});
Once joined, the LemonSlice agent will connect and begin responding in the room.

​
4. Listen for LemonSlice events

LemonSlice uses Daily’s app-message channel to push events about the agent, image updates, and errors.
Example event handler
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);
  }
});

​
You’re ready to build

With a room created, the agent connected, and event hooks wired up, you’re ready to:
  • Build interactive video AI apps
  • Customize agent behavior
  • Trigger image changes and respond to events
Explore the rest of the API docs for more capabilities.

​
Receiving Events

Hook into the Daily event handler to get LemonSlice-specific events.
Event TypeDescription
bot_readyFired when the LemonSlice agent has successfully joined the Daily room and is ready to send and receive audio and video.
idle_timeoutEmitted when the agent stops due to inactivity. The idle timeout threshold is defined by the agent’s configuration.
user_transcriptionEmitted when the user’s speech has been finalized. Includes the field transcription. This event also captures messages sent by the user via text.
agent_transcriptionEmitted when the agent’s response has been finalized. Includes the field transcription.
image_change_requestedA new agent look has been requested, typically after an /imagine request is made.
image_createdA new agent look has been created and is available for use.
image_change_completeThe agent’s look has finished updating and the new look is now active.
image_change_errorThe agent failed to update its look. Includes an error field with additional details.
daily_errorA Daily-related error occurred. Includes error and fatal fields.
video_generation_errorA failure occurred while generating a video segment or rendering agent output.

​
Full event handler

useDailyEvent(
  "app-message",
  useCallback((ev: DailyEventObjectAppMessage) => {
    if (ev?.data?.type === "bot_ready") {
      console.log("Agent has joined the room")
    }
    if (ev?.data?.type === "idle_timeout") {
      console.log("Agent has timed out")
    }
    if (ev?.data?.type === "user_transcription") {
      console.log("Latest user transcription: ", ev?.data?.transcription);
    }
    if (ev?.data?.type === "agent_transcription") {
      console.log("Latest agent transcription: ", ev?.data?.transcription);
    }
    if (ev?.data?.type === "image_change_requested") {
      console.log("Request to edit agent has been received")
    }
    if (ev?.data?.type === "image_created") {
      console.log("New base image for Agent created")
    }
    if (ev?.data?.type === "image_change_complete") {
      console.log("Updated agent is ready")
    }
    if (ev?.data?.type === "image_change_error") {
      console.log("Failed to update agent", ev?.data?.error)
    }
    if (ev?.data?.type === "daily_error") {
      console.log("An error occurred. ", ev?.data?.error, ev?.data?.fatal);
    }
    if (ev?.data?.type === "video_generation_error") {
      console.log("A video generation error occurred.");
    } 
  }, [])
);

​
Control Events

Send events through Daily to control the LemonSlice agent.
Control EventDescription
chat-msgSend a message to the agent for it to respond to.
Also supports triggering avatar image changes via /imagine (see Avatar image changes with /imagine).
force-endImmediately stop the realtime agent. The agent will leave the room and billing will stop.

​
Sending Events

sendAppMessage(
  {
    event: "chat-msg",
    message: "Your message here",
    name: "User",
  },
  "*",
);

sendAppMessage(
  { event: "force-end" },
  "*",
);

​
Avatar image changes with /imagine

The chat-msg control event also supports avatar image updates using a special /imagine prefix.
When a message begins with /imagine, LemonSlice interprets the remainder of the message as an image prompt and updates the agent’s avatar accordingly.
Example
sendAppMessage(
  {
    event: "chat-msg",
    message: "/imagine being in front of a fireplace",
    name: "User",
  },
  "*",
);
How it works
  • Messages starting with /imagine do not trigger a spoken response
  • Instead, the agent’s avatar image is regenerated based on the prompt
  • The avatar retains its core identity and proportions, while updating the visual context
  • Once the image update completes, the agent continues normal interaction
    Agent setup requirement: Allow users to modify appearance must be enabled in the agent configuration. This setting is enabled by default for all newly created agents.

​
Additional resources

The following resources provide more information about using LemonSlice with Daily.

LemonSlice Room API Documentation

Daily Documentation

Ready-to-use LemonSlice Daily Example