Interactive - Integration Guide

The Interactive API offers an end-to-end integration flow for creators to build real-time interactive session with AI avatars. The following diagram illustrates the lifecycle of an interactive session.

1. Start Session: Tells the Interactive service to start a new session, with the specified session params including Avatar ID, Voice ID, the model used, instructions, and tools.
2. Behind the scenes, the Interactive service will:

• Create a service mapping, and register a client URL for the session.
• Going through the whole service pipeline including setting up service node, load all models, and warming up all service components. It will take around 2 minutes to complete this process.
• During this period, user launch the url in a browser, which will connect to the Interactive service node, showing a connecting state.

3. Upon the service node is ready, the end user can start chatting with the AI avatar.
4. Stop Session: When the session is completed, the client can stop the session, which will clean up all resources and stop the service node.

Start an Interactive Session

To start an interactive session, call the start session API:

curl https://mirako.co/v1/interactive/start_session \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "avatar_id": "MY_AVATAR_ID",
  "voice_profile_id": "MY_VOICE_ID",
  "instruction": "You are a friendly AI.",
  "llm_model": "gemini-2.0-flash"
}'

Parameters

• avatar_id: The ID of the avatar to use for the session.
• voice_id: The ID of the voice to use for the session.
• model: The Interactive model to be used for the session. The latest model is metis-2.5 and is the defrault model used.
• llm_model: The LLM model to be used for the session. See Supported Models.
• instructions: The instruction prompt for the AI avatar.
• tools: Optional MCP tools configuration provided to the LLM. See MCP Tools.

Response

You will receive a response containing the session information, especially the session_id which is the unique identifier for the session.

{
  "data": {
    "session": {
      "session_id": "MY_SESSION_ID",
    }
  }
}

Client URL

The client URL is where end users will interact with the session. The url will be in the format:

https://interactive.mirako.ai/i/{session_id}

where {session_id} is the unique identifier for the session. You obtain this session ID from the response of the start session API.

Embed an interactive session client

You can use this URL to embed the session in your application or share it with users.

// Replace {session_id} with the actual session ID
<iframe src="https://interactive.mirako.ai/i/{session_id}" 
    allow="camera; microphone"
    allowfullscreen>
</iframe>

View Active Interactive Sessions

You can view your active interactive sessions using the list sessions API.

curl https://mirako.co/v1/interactive/list \
  --header 'Authorization: Bearer MY_SECRET_TOKEN'

Stopping an Active Session

When the session is completed, you can stop it using the stop session API. Stop session API accepts multiple session IDs, allowing you to stop several sessions at once.

curl https://mirako.co/v1/interactive/stop_sessions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer MY_SECRET_TOKEN' \
  --data '{
  "session_ids": [
    "MY_SESSION_ID"
  ]
}'