Python SDK / Configuration

Configuration

Three dataclasses shape a session: AvatarConfig (the persona), ClientOptions (where the server is), and SessionOptions (per-session media settings).

from zeli import AvatarConfig, ClientOptions, SessionOptions

AvatarConfig

Describes the avatar persona to bring to life.

Field	Type	Default	Description
`avatar_id`	`str \| None`	`None`	Prepared avatar to render (uploaded files are keyed by filename stem). If omitted, the server default is used.
`name`	`str \| None`	`None`	Human-friendly persona label.
`voice_id`	`str \| None`	`None`	Voice to speak with.
`llm_id`	`str \| None`	`None`	Conversational model id for `send_message`.
`system_prompt`	`str \| None`	`None`	System prompt priming the model.
`language_code`	`str \| None`	`None`	BCP-47 language, e.g. `"en"`.
`emotion_responsive`	`bool`	`False`	Switch tone clips to match the reply's emotion.
`enhance`	`bool`	`False`	Region-limited mouth restoration for sharper lips/teeth.
`enhance_strength`	`float \| None`	`None`	Blend factor for `enhance` in `[0, 1]`.
`loop_mode`	`"boomerang" \| "forward" \| None`	`None`	How the idle loop repeats while speaking.
`max_session_length_seconds`	`int \| None`	`None`	Hard cap before the server tears the session down.

avatar_id and voice_id are honored today. The remaining fields are applied where the target server supports them.

ClientOptions

Client-wide settings: where the server is and how to reach it.

Field	Type	Default	Description
`server_url`	`str`	`"http://localhost:8080"`	Base URL of the avatar server.
`connect_path`	`str`	`"/connect"`	Persistent WebRTC offer/answer path.
`ice_servers`	`list[dict] \| None`	Google STUN	ICE servers for NAT traversal.
`connect_timeout`	`float`	`30.0`	Seconds to wait for the media connection.
`client_label`	`str \| None`	`None`	Optional label attached to requests for observability.

SessionOptions

Per-session settings passed to connect().

Field	Type	Default	Description
`video_quality`	`"high" \| "auto"`	`"high"`	`"auto"` lets the server adapt to bandwidth.
`receive_video`	`bool`	`True`	Subscribe to the inbound video track.
`receive_audio`	`bool`	`True`	Subscribe to the inbound audio track.

Example

client = ZeliClient(
    avatar_config=AvatarConfig(
        avatar_id="presenter-male-1080",
        voice_id="your-voice-id",
        emotion_responsive=True,
        enhance=True,
        enhance_strength=0.5,
    ),
    options=ClientOptions(
        server_url="https://avatar.zeligate.ai",
        connect_timeout=20.0,
    ),
)
 
async with client.connect(SessionOptions(video_quality="auto")) as session:
    ...

Configuration#

AvatarConfig#

ClientOptions#

SessionOptions#

Example#

Configuration

AvatarConfig

ClientOptions

SessionOptions

Example