Reading · Benjamin Crozat's blog posts

What this GPT Realtime guide covers

As of March 14, 2026, OpenAI’s current model docs call this model gpt-realtime, and the pinned snapshot is gpt-realtime-2025-08-28.

The current Realtime guide says this model is built for low-latency conversations over WebRTC, WebSocket, or SIP. That makes it very different from a normal request-response GPT tutorial.

If you are starting a brand-new voice agent today, compare this older model with the newer gpt-realtime-1.5 page first. OpenAI describes that newer model as its flagship audio model, so most readers should sanity-check that option before building on the original gpt-realtime snapshot.

This guide stays focused on two things that actually matter when you are getting started:

creating a realtime session token for a browser or mobile client
sending a first live message over WebSocket and getting the reply back immediately

If you do not need a live, interruption-friendly session, read GPT Audio instead. It is simpler when one request and one generated audio response are enough.

Get your API key ready

You need an OpenAI account, a funded API project, and an API key from the API keys page.

Then export it in your terminal.

macOS and Linux:

export OPENAI_API_KEY="sk-..."

Windows Command Prompt:

setx OPENAI_API_KEY "sk-..."

If you use setx, open a new terminal before testing the key.

Create a realtime session token

For browser and mobile clients, the current Realtime docs use an ephemeral client secret rather than exposing your standard API key to the frontend.

This exact request worked for me:

curl -s https://api.openai.com/v1/realtime/client_secrets \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session": {
      "type": "realtime",
      "model": "gpt-realtime-2025-08-28",
      "audio": {
        "output": {
          "voice": "marin"
        }
      }
    }
  }'

That exact request completed successfully for me and returned a short-lived client secret plus a session object that confirmed:

the model was gpt-realtime-2025-08-28
the session type was realtime
the output voice was marin

That is the server-side step you need before a browser client opens a live voice session.

Pick the right connection type first

The current Realtime guide presents three connection styles for this model:

WebRTC for browser and mobile voice experiences
WebSocket for server-side or backend-controlled integrations
SIP for phone-style integrations

If you are building an in-browser voice assistant, WebRTC is usually the first option to evaluate. If you want a backend process or a CLI-style integration, WebSocket is the simpler place to start.

Send your first live GPT Realtime message

Before you add audio streaming, start with a text-only Realtime turn. It is much easier to debug and still proves the live connection works.

This exact Node.js script worked for me on Node 25:

OPENAI_API_KEY="$OPENAI_API_KEY" node --input-type=module <<'NODE'
const ws = new WebSocket('wss://api.openai.com/v1/realtime?model=gpt-realtime-2025-08-28', {
  headers: {
    Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
  },
});
let finalText = '';
ws.addEventListener('open', () => {
  ws.send(JSON.stringify({
    type: 'conversation.item.create',
    item: {
      type: 'message',
      role: 'user',
      content: [
        {
          type: 'input_text',
          text: 'Say hello in one short sentence.',
        },
      ],
    },
  }));
  ws.send(JSON.stringify({
    type: 'response.create',
    response: {
      output_modalities: ['text'],
    },
  }));
});
ws.addEventListener('message', (event) => {
  const data = JSON.parse(event.data.toString());
  if (data.type === 'response.output_text.delta' && data.delta) {
    finalText += data.delta;
  }
  if (data.type === 'response.output_text.done') {
    console.log(data.text);
  }
  if (data.type === 'response.done' || data.type === 'error') {
    ws.close();
  }
});
NODE

That exact script completed successfully for me and printed:

Hey there, great to meet you!

At that point, you know four important things are working:

the WebSocket connection opens
the model accepts your user message
response.create triggers generation
the model streams text events back in realtime

You can update the session without reconnecting

One helpful Realtime pattern is changing the session while the connection stays open.

I also verified that this session.update shape worked for me:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "Be extra nice today!",
    "audio": {
      "output": {
        "voice": "marin"
      }
    }
  }
}

That is useful when your app needs to change tone, instructions, or the output voice without tearing down the whole session.

Build something useful: a low-latency support assistant

The useful Realtime pattern is not “generate a long perfect answer.” It is “keep the conversation moving with very low delay.”

Imagine a support widget where the user speaks, interrupts, clarifies, and expects the assistant to react immediately.

That is where gpt-realtime makes sense:

live turn-taking matters
interruptions matter
audio input and output matter
session state matters

The architecture is usually:

your server creates an ephemeral client secret
your browser or mobile client opens the live connection
the model keeps the conversation going turn by turn

If you only need “generate one audio reply for this prompt,” that architecture is heavier than necessary. GPT Audio is the simpler fit for that job.

The field name that is easy to get wrong

One current Realtime gotcha is the output field name.

In my live tests:

response.modalities failed
response.output_modalities worked
session.modalities failed
the GA endpoint worked without an OpenAI-Beta: realtime=v1 header

So if your first WebSocket request returns an unknown-parameter error, check that field first.

What GPT Realtime supports well

The current model page says gpt-realtime supports:

text and audio inputs
text and audio outputs
function calling

The same page also says structured outputs are not supported on this model, which is another reason Realtime is not the best starting point for strict JSON workflows. For those, standard GPT models like GPT-5.0 are usually easier.

When GPT Realtime is the right choice

Pick gpt-realtime when you need:

live voice conversations
low latency
interruption-friendly turn-taking
a long-running session instead of isolated requests

Do not pick it just because it sounds newer or more advanced. If the job is fundamentally request-response, you are usually better off with GPT Audio or a standard GPT text model.

Common mistakes with GPT Realtime

1. Starting with audio before proving text works

Start with a text-only live turn first. It isolates connection and event-shape problems quickly.

2. Treating Realtime like the Responses API

Realtime is event-based. You send conversation items and response events rather than one big /v1/responses payload.

3. Expecting strict JSON schemas

The current model page marks structured outputs as unsupported for gpt-realtime.

4. Exposing your normal API key in the frontend

Use the ephemeral client secret flow for browser and mobile clients.

5. Choosing WebSocket for a browser voice UI by default

It can work, but the Realtime guide is built around WebRTC for browser-class voice experiences. WebSocket is usually the better fit for server-side control and debugging.

If you are deciding between low-latency voice and simpler request-response audio, these are the next pages I would keep open:

GPT Realtime API quick start with a live workflow