API reference / Sessions

Sessions#

A session on this service is one live WebRTC connection to one GPU avatar server, and an avatar server serves exactly one at a time. Opening a new one closes the previous one. The routes here mint the credential a browser streams with, report whether a turn is possible, drive and stop the live session, and read back the conversation history it produced.

Mint a session token#

Call this from your server with a full API key and hand the result to the browser. The token it returns is stream only: it can drive an avatar but can never mutate server state.

Token creation is available before a stream starts. Present a full portal-created API key through X-Api-Key or Authorization: Bearer; a streaming token cannot mint another token.

curl -X POST "https://zeli-avatar.zelibot.xyz/v1/streaming.create_token" \
  -H "X-Api-Key: zsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 300}'

// your backend, never bundled for the browser
const { token, expiresAt, scope } = await admin.management.createSessionToken({
  expiresInSeconds: 300,
});

token = await client.create_session_token(expires_in_seconds=300)

Response 200. This is one of the three routes that wraps its payload in data:

{
  "data": {
    "token": "zsk_temp_...",
    "expires_at": 1770000000,
    "scope": "tts"
  }
}

expires_at is unix seconds. scope is always tts. The token is an opaque string, not a JWT, so do not try to decode it; ask the server.

Errors are returned as unwrapped code and message, which is unusual on this surface and is called out on the overview:

Readiness#

Returns current readiness for the caller's conversation and voice configuration. This status is not a capacity reservation.

Takes no parameters. The answer is scoped to the calling credential, so somebody speaking on their own voice provider account is told about their engine.

{
  "llm": true,
  "tts": true,
  "ready": true,
  "voice_origin": "byo",
  "voice_provider": "cartesia",
  "voice": true,
  "transcribe": true,
  "llm_state": "ready",
  "tts_state": "ready",
  "llm_detail": "",
  "tts_detail": "",
  "starting": false,
  "voice_notice": "",
  "reason": ""
}

One conversational turn#

Runs the whole loop: your message goes to the model, the model returns words and a delivery tone, and the reply is spoken. The response shape depends on whether a live session is connected, and the response transport depends on whether you opted in to streaming, which is off unless you ask for it.

With a live session connected, the reply is streamed straight into it and no audio comes back, because the avatar is already speaking:

{
  "reply": "Good question. The short answer is yes.",
  "tone": "confident",
  "avatar": "01-presenter-male__confident",
  "tools": [],
  "streamed": true,
  "identity": "01-presenter-male",
  "tones": ["neutral", "confident", "warm"],
  "voice_notice": ""
}

With no live session, the reply is synthesized to a file for you to lip sync with POST /offer. Note audio appears and streamed, avatar and tools do not:

{
  "reply": "Good question. The short answer is yes.",
  "tone": "confident",
  "audio": "chat_00042.wav",
  "identity": "01-presenter-male",
  "tones": ["neutral", "confident", "warm"],
  "voice_notice": ""
}

tools names, in wording meant for a person, which tools ran during the turn, so a page can explain why the avatar paused. It is empty on a turn that used none.

A 502 means the model or the voice engine failed. The body carries {"error": "..."} and, on an empty generation, interrupted. A caller that asked for the stream is told the same thing in an error frame instead, for the reason given below.

Stream the turn as it happens#

Both shapes above are what this route answers by default, and that is unchanged: a caller that asks for nothing gets exactly the single JSON body it has always got. A caller that opts in is given the turn as it happens instead, as NDJSON: one JSON object per line, written while the avatar is still speaking, so the words land with the speech rather than after it.

There are two ways to ask, and either one on its own is enough:

The header is matched case insensitively and the media type may sit among other values. The body field must be the JSON boolean true, which exists for a client that cannot set headers at all. Anything else is not an opt in, and the turn comes back as one body.

curl -N -X POST "https://zeli-avatar.zelibot.xyz/api/chat" \
  -H "X-Api-Key: zsk_temp_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  -d '{"message": "Walk me through the tiers.", "voice": "<voice id>"}'

Response 200, Content-Type: application/x-ndjson. It also carries Cache-Control: no-store and X-Accel-Buffering: no, so nothing between you and the avatar server holds the body back to buffer it. Read it a line at a time; a frame can be split across two network reads, so cut lines from a buffer rather than from whatever arrived.

{"type":"reply_chunk","text":"Good question.","tone":"confident"}
{"type":"tool","name":"current_time","label":"Checking the time"}
{"type":"reply_chunk","text":"The short answer is yes.","tone":"confident"}
{"type":"reply","reply":"Good question. The short answer is yes.","tone":"confident","avatar":"01-presenter-male__confident","tools":[],"streamed":true,"identity":"01-presenter-male","tones":["neutral","confident","warm"],"voice_notice":""}

tone travels on every clause rather than once at the end, because a reply can change tone partway through and the avatar's face already follows it.

The closing reply frame is authoritative over every clause streamed before it: it carries the transcript as the moderation screen left it. Every clause you receive has already passed that screen and has already been synthesized into speech, so a refused sentence never reaches the stream at all.

Two things about errors, because the status line is spent early:

• A refusal found before the first frame is written is still an ordinary HTTP status, exactly as it is for a plain caller: a blank message is a 400, a turn with no voice to speak in is a 400, and a model or voice engine that is not configured is a 503.
• A failure found after the first frame cannot be a status any more, because 200 went out with the headers. It arrives as the error frame, which is what an empty or interrupted generation looks like to a streaming caller.

With no live session the request still streams, and the whole turn is the one closing reply frame, carrying the same audio name the plain body carries. So typed chat has one way to be read whether or not an avatar is on stage.

Speak exact text#

Bypasses the model entirely: the text is spoken as written and nothing is committed to conversation history.

curl -X POST "https://zeli-avatar.zelibot.xyz/api/talk" \
  -H "X-Api-Key: zsk_temp_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Welcome back.", "tone": "warm"}'

await session.talk("Welcome back.");

await session.talk("Welcome back.")

Response 200: { "ok": true, "spoken": "Welcome back." }. A 409 means there is no live session, so call /connect first. A 503 means text to speech is not configured.

Barge in#

Stops the current utterance without clearing history. The body is never read, so send an empty one. Response 200: { "ok": true }, whether or not anything was speaking.

The stop names the generation it saw, so a turn that finishes first is not silenced retroactively. On a shared avatar server that matters: the sentence you would otherwise cut may belong to somebody else.

Start a fresh conversation#

Closes this caller's conversation and opens a new one, then interrupts this caller's own utterance if one is in flight. Only this caller's, never another tenant's on the same box.

This is the third route that uses a data wrapper:

{ "ok": true, "data": { "conversation_id": "c_01H..." } }

conversation_id is null when nothing rotated, which happens when the caller had no conversation to begin with. That is the honest answer rather than an invented id.

Stop the live session#

Tears down the one live session on the box. Takes no body and no id: there is no session identifier to send, and the teardown is synchronous, so the session is gone when the response is written.

Response 200: { "ok": true }.

The control WebSocket#

The SDK's single control and event channel, and the primary way to drive a session. A browser cannot set headers on a WebSocket upgrade, which is the whole reason the ?session_token= query form of the credential exists.

This is the one surface on the service that uses camelCase. Both SDKs speak it for you and map it onto their own event names (see Events and models); everything below is the wire itself, for a client reading the socket directly.

The credential on the upgrade is frozen for the life of the socket, and so is the identity behind it. A session that outlives its token is told so and keeps the account, history and persona it was authorised with, rather than being quietly demoted to an anonymous caller mid conversation.

What you send#

What comes back#

Seventeen event types, and the count is the point: the reply itself arrives on message_stream, one clause at a time as each clause is handed to the voice. message closes the turn rather than being the first place the words appear, so a client that switches on message alone shows nothing at all until the avatar has stopped speaking.

The five dotted types are the typed state events. They are additive: avatar_speech_started, avatar_speech_ended and interrupted above keep going out unchanged. A normal turn arrives as avatar.state listening, user.transcription, avatar.state thinking, avatar.state speaking, avatar.speak_started, avatar.speak_ended, avatar.state listening. The same events (without user.transcription) are published to a LiveKit room as one JSON text stream per event on the text topic zeli.avatar_events, sent by the avatar's own participant. The Python SDK's zeli.livekit.AvatarSession subscribes and fires the typed event handlers for you; the JavaScript SDK has no LiveKit client, so there you read that topic with livekit-client.

Two clocks can end a session, and session_expired names which: an idle window that is the avatar server's policy, and a ceiling you asked for by putting max_session_length_seconds on the upgrade URL. Omit it for the avatar server's default, or pass 0 to ask for no ceiling at all.

Treat an unrecognised type as ignorable rather than as an error. The list above is what the avatar server sends today, and a client that throws on anything else is a client that breaks the next time one is added.

Session history#

Session history is served by the always on service, so it is there whether or not an avatar server is running, and whichever avatar server the session ran on. Sessions in the portal is built on these routes. They take a portal session (the signed in cookie or a signed-in identity token), not an API key. Results belong to the signed-in person, which is what makes another person's history unreachable rather than merely filtered.

List sessions#

{
  "sessions": [
    {
      "id": "0192f1c4...",
      "title": "Pricing questions",
      "preview": "Can you walk me through the tiers?",
      "avatar_id": "jordan",
      "started_at": 1769990000,
      "ended_at": 1769991234,
      "duration_seconds": 1234,
      "turns": 8,
      "has_recording": true,
      "starred": false,
      "tags": []
    }
  ],
  "next": "eyJwayI6..."
}

next is absent on the last page. Each row carries more fields than shown here (the kind of session, its end reason, persona facts); read the ones you need and ignore the rest. 503 sessions_unavailable means the history store is not wired in this environment, and is never answered with an empty list.

Read one session#

Answers {session, transcript, recording, consent}. recording and consent are short lived links, present only when the session was recorded and the file is still there; otherwise they are null and the answer is still 200. Somebody else's id is the same 404 session_not_found as an id nobody has.

Edit one session#

Any of title, notes, tags and starred. Any other field is a 400 session_field_not_editable that names it. Answers 200 {session}.

Erase a session#

Erases the transcript, the summary, the recording, the recording consent and the row. Always 202, with done and pending lists naming what is gone and what is still owed.

Not served in this group#

Stated plainly rather than left for you to discover from a 404:

Persona share links and embeds have a separate visitor session flow. They are not SDK streaming tokens.

• Session recordings. Conversations in the Live Studio are recorded automatically, with a visible "This conversation is recorded, your voice included" notice for as long as the recording runs. A recording keeps both sides of the call in one video: the avatar's picture and voice, and the person's own voice as their microphone hears it (never their camera). They are listed, played and erased from Sessions in the portal, not from this group. A session started through this API or the SDKs is not recorded: neither asks the avatar server to record. A persona conversation (a share link or an embed) is recorded the same way, the visitor's voice included, and the visitor is told so before they press Start: "This conversation, including your voice, is recorded and transcribed." Their camera is never used. The notice itself is public: GET /auth/recordings/terms answers {text, version, digest} with no credential and no avatar server, so the wording a recording names can be read and hashed by anybody.
• Session reports, insights or summaries. Nothing of the kind is generated or stored.
• Per turn and aggregate latency analytics. Half the wire contract already exists: a correlationId threads a turn through the control WebSocket and avatar_speech_started and avatar_speech_ended both carry it. What is missing is server side capture of those timestamps and a route to read them back.