API Reference

GET

Open a realtime connection

Upgrade an owned session to the provider-independent vor-realtime-v1 WebSocket protocol.

/v1/realtimeBearer VR_SK used to create the session

Query parameters

Field	Type	Description
`session_id`required	`string`	The id returned by POST /v1/voice/sessions.

Response

101 Switching Protocols

The HTTP request upgrades to a WebSocket. JSON events then follow the vor-realtime-v1 schema.

Field	Type	Description
`protocol`required	`string` vor-realtime-v1	The public event protocol negotiated by the gateway.
`audio`required	`binary-in-JSON`	Base64-encoded raw PCM16LE 24 kHz mono frames in JSON events.

GET wss://api.voiceopenrouter.com/v1/realtime?session_id=vs_EXAMPLE
Authorization: Bearer vr-sk-...
Sec-WebSocket-Protocol: vor-realtime-v1

< 101 Switching Protocols

Responses

status codes

101WebSocket upgrade accepted.

401The key is invalid or does not own the session.invalid_vr_sk

404No session exists for this owner and id.session_not_found

410The session has expired and cannot be attached.session_expired

Authentication is checked before upgrade. An invalid key does not create a session or reservation.
Clients must create a session first. The legacy /v1/realtime?model=... direct path is not the canonical lifecycle.

Handshake

Use the same key that created the session and negotiate the public protocol.

GET wss://api.voiceopenrouter.com/v1/realtime?session_id=vs_EXAMPLE
Authorization: Bearer vr-sk-...
Sec-WebSocket-Protocol: vor-realtime-v1

< 101 Switching Protocols

Connection flow

The first events establish the public session before audio is accepted.

Gateway

session.created

The public session resource is ready.

Protocol

conversation.created

The conversation scope can receive input.

Audio

input_audio_buffer.append

Send aligned base64 PCM16LE frames.

Output

response.output_audio.delta

Play each output delta immediately.

Session update

Negotiate supported voice and turn detection settings after the initial session events.

{
  "type": "session.update",
  "event_id": "evt_client_update_001",
  "session": {
    "voice": "eve",
    "turn_detection": {
      "type": "server_vad"
    },
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "encoding": "pcm16le",
          "sample_rate_hz": 24000,
          "channels": 1
        }
      },
      "output": {
        "format": {
          "type": "audio/pcm",
          "encoding": "pcm16le",
          "sample_rate_hz": 24000,
          "channels": 1
        }
      }
    }
  }
}

Input audio

Send raw, aligned PCM16LE frames; a WAV header or odd-sized buffer is invalid.

{
  "type": "input_audio_buffer.append",
  "event_id": "evt_client_audio_001",
  "audio": "BASE64_PCM16LE_FRAME"
}

24,000 Hzsample rate

Monoone channel

PCM16LEsigned samples

98,304 Bmaximum frame