Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Connect

The Realtime API enables you to build low-latency, multi-modal conversational experiences. It currently supports text and audio as both input and output, as well as function calling.

Some notable benefits of the API include:

  • Native speech-to-speech: Skipping an intermediate text format means low latency and nuanced output.
  • Natural, steerable voices: The models have natural inflection and can laugh, whisper, and adhere to tone direction.
  • Simultaneous multimodal output: Text is useful for moderation; faster-than-realtime audio ensures stable playback.

The Realtime API is a stateful, event-based API that communicates over a WebSocket. To start a Realtime conversation, set model in the connection URL. To join an existing call, set call_id instead. Transcription sessions use intent=transcription.

WebSocket wss://api.openai.com/v1/realtime

Connect

import OpenAI from 'openai';
import { OpenAIRealtimeWS } from 'openai/realtime/ws';

const client = new OpenAI();
const connection = await OpenAIRealtimeWS.create(client, { model: 'gpt-realtime' });
try {
  await new Promise<void>((resolve, reject) => {
    let settled = false;
    const deadline = setTimeout(
      () => finish(new Error('Timed out before the response completed.')),
      60_000,
    );
    function finish(error?: Error) {
      if (settled) return;
      settled = true;
      clearTimeout(deadline);
      if (error) reject(error);
      else resolve();
    }
    // Realtime uses callbacks. Register them before sending to handle immediate replies and disconnects.
    connection.on('error', (error) => finish(error));
    connection.on('event', (event) => {
      if (event.type === 'response.output_text.delta') process.stdout.write(event.delta);
      else if (event.type === 'response.done') {
        if (event.response.status !== 'completed')
          finish(new Error(`Response ended: ${event.response.status}`));
        else {
          process.stdout.write('\n');
          finish();
        }
      }
    });
    connection.socket.once('close', () =>
      finish(new Error('Connection closed before the response completed.')),
    );
    const send = () => {
      if (settled) return;
      try {
        connection.send({
          type: 'session.update',
          session: { type: 'realtime', output_modalities: ['text'] },
        });
        connection.send({
          type: 'conversation.item.create',
          item: {
            type: 'message',
            role: 'user',
            content: [{ type: 'input_text', text: 'Say hello in one sentence.' }],
          },
        });
        connection.send({ type: 'response.create' });
      } catch (error) {
        finish(error instanceof Error ? error : new Error(String(error)));
      }
    };
    if (connection.socket.readyState === 1) send();
    else if (connection.socket.readyState === 0) connection.socket.once('open', send);
    else finish(new Error('Connection closed before opening.'));
  });
} finally {
  connection.close();
}