API reference · API
Realtime voice (WebSocket)
GET/v1/realtimeAPI key
Upgrade to a WebSocket that speaks OpenAI's Realtime protocol (client events such as session.update, input_audio_buffer.append and response.create; server events such as session.created, response.created, the response deltas and response.done), so OpenAI's own clients connect with a new URL and an Antimatter key. Off unless the operator switches it on, and then a 404 like any unknown path. The key rides Authorization: Bearer, or the subprotocol openai-insecure-api-key.<key> beside realtime, which is the subprotocol answered. Chat scope, the realtime wire, funded accounts only. Every check runs before the upgrade and a refusal is the JSON error below. Inside the session the gateway forces max_output_tokens to at most 4096, holds each next response at its worst case (the conversation's bound at the dearest input rate plus the output ceiling at the dearest output rate, at the margin) before it sends input that could start one, charges each response.done what its usage reports at OpenAI's published card plus the margin, never past its hold, and writes one usage row per response with its own request id. A response whose usage never arrives is charged its hold. When the session's budget or the balance cannot cover the next response it sends an error event, realtime_budget_exhausted or insufficient_credits, lets a held response finish and closes with 1008; after 30 minutes, or before the platform's own deadline, realtime_session_expired and 1001. Refused in session with an error event: another model, input transcription, tools other than functions, stored prompts and tracing. rate_limits.updated is not relayed.
Parameters
| Field | Type | What it is |
|---|---|---|
| model (query)required | string | The realtime model; the bare OpenAI id (gpt-realtime-mini) works too. One of "openai/gpt-realtime-2.1", "openai/gpt-realtime-2.1-mini", "openai/gpt-realtime-2", "openai/gpt-realtime-1.5", "openai/gpt-realtime", "openai/gpt-realtime-mini". |
| budget_micros (query) | integer | The most this session may spend, micro USD. 20000000 when absent, 100000000 at most, never more than the balance. The first session.update may set it instead as antimatter.budget_micros beside the session. At least 1. |
| antimatter_events (query) | string | 1 adds an antimatter.response.cost event after each response.done: its request id, its billed cost and the session's running total. One of "1". |
Errors
- 101Switching protocols: the session is open.
- 400OpenAI shaped error.
- 401OpenAI shaped error.
- 402OpenAI shaped error.
- 403OpenAI shaped error.
- 404OpenAI shaped error.
- 426A plain request: this path is a WebSocket. Error type upgrade_required.
- 429OpenAI shaped error.
- 503realtime_unavailable: this deployment cannot hold the socket (the message names the standalone relay's address when one is configured).
Every error answers in one shape, with its type, code and the field it names. The whole list is in the docs' Errors section.