Get started / Overview
Zeli Avatar
Embed a live, lip-synced talking-head avatar in your own application. Connect to a Zeli avatar server, receive synchronized audio and video over WebRTC, and drive the avatar with text — either through a conversational model or straight to text-to-speech. Real-time avatars, in a few lines of code.
What it is
Zeli Avatar renders a real-time, conversational, lip-synced avatar on a GPU
server and streams it to your process over WebRTC. Your app uses the SDK as a
thin, fully-typed client: it receives synchronized VideoFrame / AudioFrame
objects on the media plane, and sends text and receives events (transcripts,
speech start/stop, emotions, errors) on the control plane.
The models are self-hostable, the data stays on your own infrastructure with Australian data residency (Sydney), and the underlying model is MIT-licensed.
Point the client at your avatar server, connect(), and either
send_message() for a full conversational turn or talk()
to speak exact text — the synchronized video and audio stream straight back to
you.
from zeli import ZeliClient, AvatarConfig, ClientOptions
client = ZeliClient(
avatar_config=AvatarConfig(avatar_id="presenter-male-1080"),
options=ClientOptions(server_url="http://your-server:8080"),
)
async with client.connect() as session:
await session.talk("Hi there — welcome to Zeli.")
await session.wait_until_closed()Start here
Connect, send a message, and read the conversation — in under a minute.
Install zeli-avatar and its small async runtime stack.
How the media plane and control plane fit together.
The Python SDK surface — client, session, events, config, errors.
Feature highlights
- Real-time A/V streaming — synchronized frames as PyAV
VideoFrame/AudioFrameobjects, ready for NumPy. - Two-way conversation —
send_message()runs the model → TTS → avatar loop. - Direct speech —
talk()and incremental talk streams bypass the model. - Barge-in —
interrupt()stops the avatar mid-sentence. - Event-driven — subscribe with
@client.on(ZeliEvent.…); a running transcript is kept for you. - Typed & async — dataclass config, a clean async client/session API, and a structured error hierarchy.
What you can do today
| Capability | SDK surface | Status |
|---|---|---|
| Connect and receive A/V | client.connect() → Session | Ready |
| Conversational turn | session.send_message(text) | Ready |
| Direct TTS | session.talk(text) | Needs gateway |
| Incremental speech | session.create_talk_stream() | Needs gateway |
| Barge-in | session.interrupt() | Ready |
| Emotion events | ZeliEvent.EMOTION_DETECTED | Ready |
| Mic-driven user speech | USER_SPEECH_* events | Reserved |
The SDK is a client — it does not run the avatar models itself. You need a running Zeli avatar server (the real-time server in this repository) and its base URL. See Real-time avatars for the architecture.