Realtime WebSocket

ZeaLLM exposes an OpenAI-compatible Realtime transport as a governed WebSocket proxy. Clients connect to the gateway; the gateway authenticates, resolves a model group to a deployment, dials the provider with the deployment API key, and proxies events bidirectionally.

POST /v1/realtime/sessions is not implemented in the MVP. Use a virtual key on the gateway WebSocket.

Clients must use the Realtime GA event shapes (session.type: "realtime", audio/pcm, etc.). The gateway dials upstream without the deprecated OpenAI-Beta: realtime=v1 header.

Connection

Item	Value
URL	wss://{ZEAGATE_HOST}/v1/realtime?model={MODEL_GROUP}
Alias	wss://{ZEAGATE_HOST}/realtime?model={MODEL_GROUP}
Method	GET with WebSocket upgrade
Auth	Authorization: Bearer zea-... on the upgrade request

Model routing: the model query parameter is the ZeaLLM model group (same as HTTP APIs). The gateway maps it to the deployment providerModel for the upstream wss:// URL. Do not rely on changing model inside session.update for routing.

Governance

Before the WebSocket upgrade, the gateway applies the same controls as other endpoints:

• Virtual key authentication and key state
• Model access (access groups)
• Org pricing
• Budgets and rate limits (connection counted as a request)

Response headers on upgrade (when supported):

• x-zeallm-request-id
• x-zeallm-model-group
• x-zeallm-deployment-id

Proxy behavior

• All client → provider and provider → client frames are forwarded unchanged (including session.update for session configuration).
• Spend is recorded when the session ends (endpoint: realtime_ws, streamed: true). Token usage is taken from response.done events when present; otherwise billing may be estimated.

Compared to HTTP audio

Feature	STT / TTS (HTTP)	Realtime (WebSocket)
Transport	POST	GET + WebSocket
Use case	File/batch transcribe, speak text	Voice agent, low-latency duplex
Model param	Body or multipart model	Query ?model= at connect time

Testing

Use a WebSocket client (wscat, Python websockets) against the gateway URL with your zea- key. See QA Case26 in the test-case pack.