Omni

Mint an ephemeral Omni session token

Most integrations do not need this endpoint. Server-side apps, telephony, and backend agents connect to wss /v1/omni directly with their API key (see "Open an Omni voice-agent session"). Use this only when a browser or other untrusted client must open an Omni session without holding your secret key.

It mints a short-lived, origin-locked token the browser can use to open ONE Omni realtime session, the public/private split for realtime. Call this from your server with your secret key (which must hold omni:session); never ship the secret key to a page. The returned token carries only omni:session, is limited to one concurrent session, is locked to the allowed_origins you supply, and expires after ttl_seconds (default 60s, max 600s). Use it as the WebSocket subprotocol pyai-key.<token>, offered after the pyai.v1 marker, against the returned url. See the Omni browser guide for the full flow.

post/v1/omni/sessions

Request

  • Base URL: https://api.pyai.com
  • URL: https://api.pyai.com/v1/omni/sessions
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

allowed_originsstring[] required

Browser origins (scheme://host[:port]) the token may connect from. Required and non-empty, a browser token must be origin-locked. * is not allowed.

ttl_secondsinteger

Token lifetime in seconds. Keep it short; a leaked token is worth seconds, not minutes.

session_labelstring

Optional opaque tag echoed back to your kb_endpoint and recorded on the call.

Example request

{
  "allowed_origins": [
    "https://acme.com"
  ]
}

Response

Minted session token

objectstring
tokenstring

The ephemeral session token. Offer it as the WebSocket subprotocol pyai-key.<token> after the pyai.v1 marker. Short-lived and origin-locked; safe to hand to the browser.

expires_atinteger

Token expiry, Unix epoch milliseconds.

urlstring

The Omni realtime WebSocket URL to connect to.

session_labelstring nullable

Echoed back when supplied on the request.

Example response

{
  "object": "omni.session",
  "token": "pyai_live_sess_a1B2…",
  "url": "wss://api.pyai.com/v1/omni?format=pcm16&rate=24000"
}

Changes

No recorded changes to this operation across all 1 revision of this API.