Python SDK / Session
Session
A Session is returned by
ZeliClient.connect.
You don't construct it directly.
from zeli import SessionProperties
| Property | Type | Description |
|---|---|---|
session_id | str | Server-issued id for this session. |
avatar | str | None | Concrete avatar the server resolved. |
is_active | bool | False once the session is closed. |
has_control_channel | bool | True when the full control gateway is available (enables talk / talk streams / streaming events). |
Media
video_frames() -> AsyncIterator
Yields inbound video frames (PyAV VideoFrame). Use
frame.to_ndarray(format="rgb24").
audio_frames() -> AsyncIterator
Yields inbound audio frames (PyAV AudioFrame, 48 kHz stereo int16 PCM).
Both iterators end when the session closes. See Receiving media.
Driving the avatar
send_message(text, *, avatar=None)
Sends user text through the conversational model; the avatar speaks the reply.
Emits message/speech events. Falls back to an HTTP POST /api/chat when the
control gateway is absent. Raises ValueError on empty text.
talk(text, *, tone=None)
Speaks text directly through TTS, bypassing the model. Does not affect history.
Requires the control gateway (else raises SessionError). Optional tone
colours the delivery (e.g. "confident", "happy").
create_talk_stream(*, tone=None) -> TalkStream
Returns a TalkStream for pushing text incrementally.
Requires the control gateway.
interrupt()
Stops the avatar mid-utterance (barge-in). Emits TALK_STREAM_INTERRUPTED.
talk and create_talk_stream require the server's
control gateway. On a server without it they raise
SessionError — check
session.has_control_channel and use send_message
instead, or upgrade the server.
Lifecycle
wait_until_closed()
Blocks until the session ends (server close, media failure, or close()).
close()
Tears the session down and releases all resources. Called automatically when the
session is used as an async with context manager.