API reference / Overview

API reference#

Use the hosted API to manage your resources and connect real-time avatar experiences. Each endpoint documents its path, accepted credential and response format.

Base URL#

https://zeli-avatar.zelibot.xyz

Append the endpoint path exactly as documented. Paths include /api/, /auth/ and /v1/; do not add an extra prefix.

Live streaming requires an available avatar service. Account management, saved Personas, provider settings and token creation can be used independently of an active stream.

Authentication#

Each endpoint states its accepted credential. API keys do not grant access to all account routes, and streaming tokens cannot perform management operations.

See Authentication to create a key and implement token minting.

Field names and envelopes#

Request and response bodies are JSON. Field names are snake_case throughout: expires_at, next_cursor, avatar_id, source_kind, idle_stand_in, emotion_responsive, transcript_unavailable.

The one exception is the SDK control WebSocket, which is camelCase (sessionId, correlationId, contentIndex, endOfSpeech). It sits on the same host as the snake_case HTTP routes. See Events and models.

Most routes return a bare object, not a wrapper. Three routes wrap their payload in data, and they are named where they appear: POST /v1/streaming.create_token, POST /v1/photo_avatar.create and POST /api/chat/reset.

Errors#

Response shapes vary by endpoint; the endpoint reference documents the exact shape.

Structured, used by every /auth/* route and by the streaming and media routes (clips, photo avatar, settings refusals, token minting):

{ "error": { "code": "avatar_not_found", "message": "No such avatar." } }

POST /v1/streaming.create_token returns the same two fields unwrapped:

{ "code": "mint_failed", "message": "..." }

Flat, used by some media routes:

{ "error": "only uploaded avatars can be deleted" }

The code is the stable, machine readable half; branch on it rather than on the message, which is written for a person and may be reworded.

Status codes#

Pagination#

Read the pagination fields documented for each endpoint. Session history uses limit and an opaque cursor, returning next when another page exists. Persona lists, versions, links and visitor sessions have their own paginated responses. Do not decode or construct cursors, and do not assume every catalogue is paginated.

Groups#