Open an Omni voice-agent session (WebSocket)
The native Omni API: a full-duplex WebSocket to a voice agent grounded in its knowledge bases + tools. Omni runs on a single engine tier (Ultra), so this is the canonical surface for agentic voice.
Upgrade with wss://api.pyai.com/v1/omni?agent_id=<id>. Send PCM16 audio (?format=pcm16&rate=24000 for browser/WebRTC, rate=16000 for telephony) as binary frames and receive agent audio the same way.
Requires the omni:session scope (or the omni:* wildcard). The session is authorized by your key’s org — there is nothing to create first. 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). The agent’s behavior — voice, persona, knowledge endpoint — travels in the post-handshake configure frame, not in a pre-built record.
Auth: browsers can’t set Authorization on a WebSocket, so send the key as a subprotocol: Sec-WebSocket-Protocol: pyai-key.<API_KEY> (server clients may use ?api_key= instead). The customer key is validated and swapped for the internal engine credential on the upgrade.
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 telephony.
16000, 24000 Response
Switching Protocols — the Omni WebSocket is open.