Live Channels

​

What this guide is for

• open a live audio/text channel on a session
• send audio, text, or model-supported image input to a live channel
• understand live channel lifecycle and capabilities
• reason about live channels in the context of the normal session model

​

Mental model

        +--------------------------+
        |   Session (history,      |
        |   tools, context)        |
        +--------------------------+
                     |
                     | session.model = "gpt-realtime-2"
                     v
        +--------------------------+
        | Live channel (caller-    |  audio/text at turn boundaries;
        | initiated via live/open) |  images after provider ACK +
        +--------------------------+  durable redacted receipt

• One canonical history. The session is the source of conversational truth. Committed audio and text join the same history as non-live turns at turn boundaries. A provider-acknowledged image is materialized and persisted as canonical context before the channel emits its redacted user_content_committed receipt.
• Capability gates channel open. ModelCapabilities.realtime is the signal that determines whether live/open succeeds. No channel is opened automatically.
• Channel lifecycle is caller-initiated. Call live/open to start a channel, live/close to end it, and live/send_input / live/commit_input / live/interrupt / live/truncate to control flow.
• Refresh without history replay. live/refresh applies mutable session config (instructions, tools, audio format) to an open channel without interrupting audio flow. Identity swaps (model/provider) and canonical transcript or user-content-registry rewrites cannot be hot-applied; they return a typed reopen-required error and require live/close + live/open.

​

Realtime-capable models

• OpenAI: gpt-realtime-2 — the only realtime-capable model in the current catalog, with still-image input advertised as capabilities.image_in == true.
• Gemini: reserved for future *-live* endpoints — no production models today.
• Anthropic: no realtime-capable models today.
• Self-hosted: realtime = false by default.

​

Opening a live channel

​

At session creation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/create",
  "params": {
    "prompt": "Let's talk.",
    "model": "gpt-realtime-2",
    "provider": "openai"
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "live/open",
  "params": {
    "session_id": "01936f8a-7b2c-7000-8000-000000000001"
  }
}

from meerkat import MeerkatClient

async with MeerkatClient() as client:
    await client.connect(realm_id="team-alpha")
    session = await client.create_session(
        prompt="Let's talk.",
        model="gpt-realtime-2",
        provider="openai",
    )
    channel = await client.live_open(session.id)

​

Bounding the initial seed

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "live/open",
  "params": {
    "session_id": "01936f8a-7b2c-7000-8000-000000000001",
    "seed_max_chars": 24000
  }
}

result = await client.live_open(session.id, seed_max_chars=24_000)

const result = await client.liveOpen({
  session_id: session.id,
  seed_max_chars: 24_000,
});

const channel = LiveChannel.session(client, session.id, {
  seedMaxChars: 24_000,
});

​

Configuration defaults

​

Observing channel status

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "live/status",
  "params": {"channel_id": "ch_01936f8a-..."}
}

​

Live channel methods

​

Sending image input

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "live/send_input",
  "params": {
    "channel_id": "ch_01936f8a-...",
    "chunk": {
      "kind": "image",
      "idempotency_key": "turn-42-diagram",
      "mime": "image/png",
      "data": "iVBORw0KGgo..."
    }
  }
}

result = await client.live_open(session.id)
if not result["capabilities"]["image_in"]:
    raise RuntimeError("bound realtime model does not accept image input")

await client.live_send_input_image(
    result["channel_id"],
    "turn-42-diagram",
    "image/png",
    image_data_base64,
)
# `status: "sent"` is queue acceptance. Wait for the matching
# `user_content_committed` observation before sending dependent input.
# (Transport observation-loop code is omitted here.)
await client.live_send_input_text(
    result["channel_id"],
    "What is the dominant color in this image?",
)

const result = await client.liveOpen({ session_id: session.id });
if (!result.capabilities.image_in) {
  throw new Error("bound realtime model does not accept image input");
}

await client.liveSendInputImage(
  result.channel_id,
  "turn-42-diagram",
  "image/png",
  imageDataBase64,
);
// Resolution is queue acceptance only. Wait for the matching durable
// user_content_committed observation before sending dependent input.
// (Transport observation-loop code is omitted here.)

​

Acceptance, rejection, and durability

​

End-to-end example

from meerkat import MeerkatClient

async with MeerkatClient() as client:
    await client.connect(realm_id="team-alpha")

    # 1. Create a session on a realtime-capable model.
    session = await client.create_session(
        prompt="Ready for live audio.",
        model="gpt-realtime-2",
        provider="openai",
    )

    # 2. Open a live channel (returns channel_id + transport bootstrap).
    result = await client.live_open(session.id)
    channel_id = result["channel_id"]
    # result["transport"] contains the WebSocket URL + token
    # result["capabilities"] describes supported input/output modalities,
    # including model-gated image_in

    # 3. Send audio input and commit at turn boundaries.
    await client.live_send_input_audio(channel_id, audio_data, 24000, 1)
    await client.live_commit_input(channel_id)

    # 4. Close the channel when done.
    await client.live_close(channel_id)

    # 5. The session's history accumulates committed turns — same as a text session.
    history = await client.read_session_history(session.id)

​

Live channels and mobs

id = "live-demo"

[profiles.host]
model = "gpt-realtime-2"
provider = "openai"
peer_description = "Live audio host"

​

Limitations and known gaps

• OpenAI Realtime API only. The shipped provider integration is OpenAI’s Realtime API (gpt-realtime-2). Azure OpenAI (azure_openai) and other providers are not yet wired into the live transport layer.
• One live channel per session. A session has at most one live channel at a time. For per-member live channels in mobs, open channels against individual member sessions.
• Deferred sessions are model-gated. live/open may materialize a deferred session whose resolved model is realtime-capable; a deferred non-realtime session is rejected before channel creation.
• Identity/history rewrites require close/reopen. live/refresh applies config-only changes (instructions, tools, audio format); model/provider swaps and canonical transcript or user-content-registry rewrites require live/close + live/open.

​

See also

• Mobs guide — spawning members, profiles, realtime-capable per-member models
• Configuration guide — setting default_model
• JSON-RPC API — session/create, live/* methods
• REST API — REST routes for session creation