Open a realtime duplex session (WebSocket)

curl --request GET \
  --url https://api.pyai.com/v1/realtime \
  --header 'Authorization: Bearer <token>'

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

Realtime

Open a realtime duplex session (WebSocket)

Upgrade to a WebSocket for full-duplex STT + turn-taking + TTS in one connection.

model=pyai-omni-realtime (default) — agentic voice. Requires the omni:session scope; the session is authorized by your key’s org. An optional session_label (alias: agent_id) is an opaque tag echoed to your own knowledge endpoint — there is nothing to pre-create. This is the OpenAI-realtime-compatible surface for Omni; for new integrations prefer the native /v1/omni endpoint.
model=pyai-flow-realtime — legacy voice duplex (Flow). Retired for new customers; existing Flow keys with the flow:session scope still connect.

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= / ?access_token= instead). The customer key is validated and swapped for the internal upstream credential on the upgrade.

GET

realtime

Open a realtime duplex session (WebSocket)

curl --request GET \
  --url https://api.pyai.com/v1/realtime \
  --header 'Authorization: Bearer <token>'

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Use Authorization: Bearer pyai_live_... (or pyai_test_...).

Query Parameters

model

enum<string>

default:pyai-omni-realtime

required

Realtime model. pyai-omni-realtime (default) enables the agent layer; pyai-flow-realtime is the retired legacy Flow engine.

Available options:

pyai-omni-realtime,

pyai-flow-realtime

session_label

string

Omni only. Optional opaque tag echoed to your own kb_endpoint (PyAI stores no per-agent state). Nothing to pre-create; the session is authorized by your key's org.

agent_id

string

Omni only. Deprecated alias for session_label; prefer session_label. If both are present, session_label wins.

Response

Switching Protocols — the duplex WebSocket is open.

Open an Omni voice-agent session (WebSocket)

⌘I