Get started / Quickstart
Quickstart
A minimal end-to-end program: connect to your avatar server, send a message,
and print the conversation as it streams back. Swap
http://your-server:8080 for your box.
Before you start
server_urlstringRequired
Base URL of your Zeli avatar server, e.g. http://your-server:8080.
Passed via ClientOptions.
avatar_idstringOptional
A prepared avatar on your server (uploaded files are keyed by filename stem). Omit to use the server default. See Avatars & tones.
api_keystringOptional
Sent to the server when it requires auth. Optional for an embedded/loopback box. See Authentication.
1. Create a client
import asyncio
from zeli import ZeliClient, AvatarConfig, ClientOptions, ZeliEvent, Message
client = ZeliClient(
avatar_config=AvatarConfig(
avatar_id="presenter-male-1080", # an avatar prepared on your server
voice_id="your-voice-id", # optional
),
options=ClientOptions(server_url="http://your-server:8080"),
)2. Subscribe to events
Handlers can be sync or async. Register them before connecting.
@client.on(ZeliEvent.SESSION_READY)
async def _ready(info):
print("session ready:", info.session_id)
@client.on(ZeliEvent.MESSAGE_RECEIVED)
async def _message(message: Message):
print(f"{message.role.value}: {message.content}")3. Connect and drive the avatar
async def main():
async with client.connect() as session:
print("connected to avatar:", session.avatar)
await session.send_message("Hi! Introduce yourself in one sentence.")
await asyncio.sleep(12) # let the reply stream back
print("\nTranscript:")
for msg in client.get_message_history():
print(f" {msg.role.value}: {msg.content}")
asyncio.run(main())async with client.connect() as session: opens the session and tears
it down cleanly on exit. Prefer it over calling session.close()
yourself.
What just happened
- The SDK negotiated a WebRTC media connection to the server.
- It opened the control channel and emitted
SESSION_READY. send_messageran the server's conversational loop; the reply streamed back asMESSAGE_STREAM_EVENT_RECEIVEDchunks and a finalMESSAGE_RECEIVED, while the avatar spoke it on the video track.