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

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/realtime"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() error {
	// Bound the whole exchange, including reads from a silent server.
	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()
	client := openai.NewClient()
	connection, err := client.Realtime.Connect(ctx, realtime.RealtimeConnectionOptions{},
		option.WithQuery("model", "gpt-realtime"))
	if err != nil {
		return err
	}
	// Closing in run releases the socket before main can exit on an error.
	defer connection.Close()

	events := []realtime.RealtimeClientEventUnionParam{
		{OfSessionUpdate: &realtime.SessionUpdateEventParam{
			Session: realtime.SessionUpdateEventSessionUnionParam{
				OfRealtime: &realtime.RealtimeSessionCreateRequestParam{
					OutputModalities: []string{"text"},
				},
			},
		}},
		{OfConversationItemCreate: &realtime.ConversationItemCreateEventParam{
			Item: realtime.ConversationItemUnionParam{
				OfRealtimeUserMessageItem: &realtime.RealtimeConversationItemUserMessageParam{
					Content: []realtime.RealtimeConversationItemUserMessageContentParam{
						{Type: "input_text", Text: openai.String("Say hello in one short sentence.")},
					},
				},
			},
		}},
		{OfResponseCreate: &realtime.ResponseCreateEventParam{}},
	}
	for _, event := range events {
		if err := connection.Send(ctx, event); err != nil {
			return err
		}
	}
	for {
		event, err := connection.Recv(ctx)
		if err != nil {
			return fmt.Errorf("realtime response did not complete: %w", err)
		}
		switch detail := event.AsAny().(type) {
		case realtime.ResponseTextDeltaEvent:
			fmt.Print(detail.Delta)
		case realtime.ResponseDoneEvent:
			// response.done also reports failed, cancelled, or incomplete responses.
			status := detail.Response.Status
			if status != "completed" {
				return fmt.Errorf("realtime response ended with status %q", status)
			}
			fmt.Println()
			return nil
		case realtime.RealtimeErrorEvent:
			e := detail.Error
			return fmt.Errorf("%s: %s", e.Code, e.Message)
		}
	}
}