Open an Omni voice-agent session (WebSocket)
This is the primary way to build an AI voice agent on PyAI. Open this WebSocket, send one configure frame (voice, persona, knowledge endpoint, tools), then stream PCM16 audio both ways. There is nothing to create first: the session is authorized by your key’s org, and the whole agent travels in the configure frame.
Connect with wss://api.pyai.com/v1/omni?format=pcm16&rate=24000 (rate=16000 or rate=8000 for telephony; use rate=8000 for an 8 kHz G.711/Twilio leg so the only conversion is μ-law companding, no resampling, see the Telephony audio reference). Send PCM16 audio as binary frames and receive agent audio the same way.
Requires the omni:session scope (or the omni:* wildcard). The optional session_label (alias: agent_id) is an opaque tag echoed to your own knowledge endpoint so you can branch per session; any value in your org’s namespace is accepted (PyAI stores no per-agent state).
Auth: send the key as the subprotocol Sec-WebSocket-Protocol: pyai-key.<API_KEY> (browsers can’t set headers on a WebSocket; server clients may use ?api_key= instead). Browser apps: if the client can’t hold your secret key, mint a short-lived origin-locked token with POST /v1/omni/sessions first and use that token as the subprotocol.
See the Omni wire protocol reference for the frame catalog and close codes.
Authorizations
Use Authorization: Bearer pyai_live_... (or pyai_test_...).
Query Parameters
Optional opaque tag for this session, echoed to your own kb_endpoint so you can branch per session. The session is authorized by your key's org (PyAI stores no per-agent state); any value in your org's namespace is accepted. Must be safe as a header value (no control chars, ≤256 chars). Omit it entirely if you don't need per-session correlation.
Deprecated alias for session_label. Accepted for back-compat; prefer session_label. If both are present, session_label wins.
Audio sample format for both directions.
pcm16 Audio sample rate in Hz. Use 24000 for browser/WebRTC, 16000 for wideband telephony, or 8000 for an 8 kHz G.711/Twilio leg (μ-law companding only, no resampling). Load-bearing on the connect URL; the gateway preserves it verbatim.
8000, 16000, 24000 Response
Switching Protocols, the Omni WebSocket is open.