Realtime

Use the OpenAI Realtime–compatible WebSocket route for real-time interaction.

GET /v1/realtime

Realtime uses a WebSocket connection and suits low-latency voice chat, real-time event streams, and bidirectional interaction. Connections go through authentication, model rate limiting, and channel routing.

The default example model is .

Available models

Model	Description
	Realtime voice / event streaming
	Realtime preview model

The debugger can edit illustrative session.update session fields. For actual integration, use the WebSocket connection example below (browser-native WebSocket usually cannot set custom headers; use gateway injection or a client that supports custom headers).

Endpoint

Replace https with wss (or http with ws) in the API Base URL, then append the path:

wss://<API_HOST>/v1/realtime

Example (placeholders are replaced at build time):

https://octopusx.ai/v1/realtime

You can also specify the model via a query parameter, for example: /v1/realtime?model=gpt-realtime.

Headers

Name	Type	Required	Description
	string	Yes	Request authentication. Use a Bearer token, for example: . If the client cannot set WebSocket headers, use a temporary token per gateway config or inject headers at a proxy layer

Connection example

const base = "https://octopusx.ai".replace(/^http/, "ws")
const ws = new WebSocket(`${base}/v1/realtime`)

// If the runtime supports custom headers, include Authorization
// headers: { Authorization: "Bearer YOUR_API_KEY" }

ws.onopen = () => {
  ws.send(
    JSON.stringify({
      type: "session.update",
      session: {
        model: "gpt-realtime",
        modalities: ["text"],
        instructions: "You are a real-time voice assistant."
      }
    })
  )
}

ws.onmessage = (event) => {
  console.log(JSON.parse(event.data))
}

Session configuration (session.update)

After the connection is established, the client may send at any time to update the session; the server returns the effective full configuration via . Only fields present in the message are updated. To clear , send an empty string; to clear , send an empty array; to disable , send .

Name	Type	Required	Description
	array	No	Response modalities, default ; set to disable audio output
	string	No	Realtime model; see Available models above. Can also be set via the URL model query parameter
	string	No	Default system instructions; guides reply content, format, and audio behavior
	string	No	Reply voice, default . Built-in: / / / / / / / / / . Cannot be changed after audio has been output
	string	No	Input audio format, default (24kHz PCM); options ,
	string	No	Output audio format, default ; options ,
	object	No	Input audio transcription settings; off by default
	object	No	Server turn detection; pass to disable and trigger responses manually
	object	No	Input audio noise reduction; pass to disable
	number	No	Sampling temperature, range –, default
	integer | string	No	Maximum output tokens per response (including tool calls); – or (default)
	array	No	List of callable tools; function tools are supported
	string | object	No	Tool selection: (default) / / , or a specific function object

input_audio_transcription

Name	Type	Required	Description
	string	No	Transcription model, e.g. , ,
	string	No	Input language (ISO-639-1), e.g. ,
	string	No	Optional prompt to guide transcription style or supply proper nouns

turn_detection

Name	Type	Required	Description
	string	No	Detection type, default ; optional
	number	No	only. VAD activation threshold, default , range –
	integer	No	only. Audio to keep before speech start (ms), default
	integer	No	only. Silence required to decide the speaker finished (ms), default
	string	No	only. How eager to respond: / / / (default, same as )
	boolean	No	Whether to auto-create a response when speech ends, default
	boolean	No	Whether to interrupt an in-progress response when new speech starts, default

input_audio_noise_reduction

Name	Type	Required	Description
	string	No	Noise reduction type: (near-talk) or (far-field)

Common events

Client events

Event	Description
	Update session configuration
	Append Base64-encoded input audio
	Commit the input audio buffer (manual commit when VAD is off)
	Clear the input audio buffer
	Create a conversation item
	Delete a conversation item
	Trigger a model response
	Cancel an in-progress response

Server events

Event	Description
/	Session created / configuration updated
/	VAD detected speech start / end
	Input audio transcription completed
/	Response started / completed
	Text delta
/	Audio delta / audio output completed
/	Output audio transcript delta / completed
	Function call arguments finished
	Error event
	Rate limits updated

Response example (session.updated)

{
  "type": "session.updated",
  "event_id": "event_abc123",
  "session": {
    "id": "sess_abc123",
    "object": "realtime.session",
    "model": "gpt-realtime",
    "modalities": ["text"],
    "instructions": "You are a real-time voice assistant.",
    "voice": "alloy"
  }
}

Related endpoints

• Chat Completions
• Responses
• Text APIs overview