API reference

Use this when you are building your own client rather than embedding ours.

Base URL and authentication

Deployment	Base URL
Hosted SaaS	https://zorgelines.com/api
On-prem	https://<your-domain>/api

Authenticated calls carry a bearer token:

Authorization: Bearer <access_token>

Public demo avatars can be started without a token. Anything tied to your account — your catalog, your session history — requires one.

Create a session

POST /api/sessions/create
Content-Type: application/json

{
  "avatar_id": "f7f6fe47f93446c1",
  "backend_type": "2d",
  "fps": 25
}

Field	Required	Meaning
avatar_id	yes	Avatar from your catalog
backend_type	no	2d for photoreal, ue5 for Unreal Engine
model	no	Pins a specific rendering model
fps	no	Video frame rate, default 25

Response:

{
  "session_id": "sess_TAWTFAv3UrdNhVa2",
  "session_token": "…",
  "backend_id": "…",
  "backend_url": "https://…",
  "backend_type": "2d",
  "whep_url": "https://…/rtc/v1/whep/…",
  "voice_relay_url": "wss://…/api/voice/…",
  "expires_at": 1786012800
}

What to do with each field:

• voice_relay_url — open a WebSocket here for audio and events. See the realtime protocol.
• whep_url — WHEP endpoint for the avatar's video, for 2D backends.
• stream_url — present instead of whep_url on UE5 backends.
• session_id — needed for every other call.
• expires_at — Unix seconds. Sessions are not immortal; a session that hits this without activity is reclaimed.

Session creation allocates a GPU worker. Under load it can take a moment, and it can fail because no capacity is free — treat a failure as retryable and show the user something better than a spinner that never resolves.

Inspect

GET /api/sessions/{session_id}
GET /api/sessions

The first returns the state of one session; the second lists active sessions for the authenticated account.

Interrupt

POST /api/sessions/{session_id}/cancel
POST /api/sessions/{session_id}/cancel?reset=false

Stops speech immediately, drops what the avatar was about to say, and hands the turn back to the user. The session stays alive.

The default triggers the conversation's cancel behaviour. reset=false interrupts speech without disturbing the conversation state — that is the one to use for barge-in, when the user simply started talking over the avatar.

End

DELETE /api/sessions/{session_id}

Ends the conversation and releases the GPU worker. Call it. An abandoned session holds capacity until it times out, which on a busy deployment is capacity someone else wanted. Send it from beforeunload too.

Avatars

GET /api/avatars
GET /api/avatars/available

The first returns your catalog with full metadata — name, description, languages, backend type, preview media. The second returns only the avatars with capacity available right now, which is what you want for a live picker.

Errors

Standard HTTP status codes. The ones worth handling explicitly:

Status	Meaning	What to do
401	Missing or expired token	Re-authenticate
404	Unknown session — expired or already deleted	Start a new session
429	Rate limited	Back off and retry
503	No GPU capacity available	Retry with backoff; tell the user honestly