WebSockets | OpenAI API

Escolha a API para ver como estabelecer a conexão e quais eventos ocorrem durante a sessão.

Conecte um servidor ao GPT-Live

Recomendamos o WebRTC para conexões de áudio com o GPT-Live, inclusive em integrações entre servidores.

Também há suporte a WebSockets. A conexão WebSocket principal transporta áudio e eventos JSON nos dois sentidos. Mantenha a chave de API do projeto no seu servidor de confiança.

Este guia mostra como transmitir áudio para o GPT-Live. Para monitorar ou controlar uma sessão existente, consulte Controles no servidor. Para conectar um backend de raciocínio e ferramentas à Responses API, consulte Modo WebSocket da Responses API.

Autentique a conexão e inicie a sessão

Conecte-se a wss://api.openai.com/v1/live/sessions sem parâmetros de consulta. Use Authorization: Bearer $OPENAI_API_KEY para autenticar a conexão e inclua os cabeçalhos de conexão mostrados no exemplo.
Envie session.start como primeira mensagem. Inclua o modelo, as instruções da conversa, o formato de áudio, a voz e a configuração de delegação no objeto session.
Aguarde session.started antes de enviar áudio ou comandos do aplicativo. Esse evento contém a configuração efetiva da sessão e o ID da sessão.

O exemplo a seguir usa a voz Marin, áudio PCM16 a 24 kHz e um backend da Responses API com pesquisa na Web. Mantenha as instruções da conversa curtas. Para configurar as instruções do backend, as ferramentas e suas permissões, siga o guia Delegação e ferramentas.

Transmita áudio com um SDK

Para Node.js, instale openai e ws com npm install openai ws e salve o exemplo em JavaScript como client.mjs. Para Python no macOS ou Linux, instale openai[realtime] e salve o exemplo em Python como client.py. Defina OPENAI_API_KEY no ambiente do servidor. Esses exemplos exigem uma versão do SDK compatível com o Live. O exemplo lê áudio bruto PCM16 mono a 24 kHz da entrada padrão e grava o áudio recebido na saída padrão, no mesmo formato. Conecte esses fluxos aos recursos de captura e reprodução de áudio do seu aplicativo. Os logs e os eventos de transcrição são enviados para a saída de erro padrão para preservar o fluxo de áudio.

Para Go, use a versão 1.26 ou posterior, salve o exemplo como main.go, inicialize um módulo com go mod init live-demo e instale github.com/openai/openai-go/v3@v3.85.1 com go get. Para Java, use a versão 17 ou posterior, adicione a dependência Maven com.openai:openai-java:4.95.0 e use a classe LiveConnectionWebsocketExample. Para Ruby 3.3 ou posterior, instale o SDK com gem install openai -v 0.110.0, instale a dependência de WebSocket com gem install async-websocket e salve o exemplo como client.rb.

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98import OpenAI from "openai";
import { LiveWS } from "openai/resources/live/ws";

// stdin and stdout carry raw mono PCM16 audio at 24 kHz, not WAV files.
// Supply microphone bytes continuously and play stdout in the same format.
process.stdin.pause();
const ws = new LiveWS(new OpenAI());
let started = false;
let closing = false;
let finalized = false;
let pendingByte = Buffer.alloc(0);

let closeTimeout;

ws.socket.on("open", () => {
  ws.send({
    type: "session.start",
    event_id: "event_start",
    session: {
      model: "gpt-live-1",
      instructions:
        "Be concise. Delegate requests needing current information to the backend, which can search the web.",
      audio: {
        format: { type: "audio/pcm", rate: 24000 },
        output: { voice: "marin" },
      },
      delegation: {
        type: "responses",
        responses: {
          model: "gpt-5.6-luna",
          tools: [{ type: "web_search" }],
          tool_choice: "auto",
        },
      },
    },
  });
});

process.stdin.on("data", (chunk) => {
  if (!started || closing || ws.socket.readyState !== 1) return;
  const bytes = Buffer.concat([pendingByte, chunk]);
  const completeLength = bytes.length - (bytes.length % 2);
  pendingByte = bytes.subarray(completeLength);
  if (completeLength) {
    ws.send({
      type: "session.input_audio.append",
      audio: bytes.subarray(0, completeLength).toString("base64"),
    });
  }
});

// Register the final-event handler before any close command can be sent.
ws.on("event", (event) => {
  if (event.type === "session.started") {
    started = true;
    console.error("Session ready", event.session.id);
    process.stdin.resume();
  } else if (event.type === "session.output_audio.delta") {
    process.stdout.write(Buffer.from(event.delta, "base64"));
  } else if (event.type === "session.closed") {
    finalized = true;
    clearTimeout(closeTimeout);
    process.stdin.pause();
    console.error("Final session usage", event.usage);
    ws.close();
  } else {
    // Includes transcript deltas and nested response.event usage.
    console.error(JSON.stringify(event));
  }
});

process.on("SIGINT", () => {
  if (closing) return;
  if (!started || ws.socket.readyState !== 1) {
    ws.socket.platformSocket.terminate();
    return;
  }
  closing = true;
  process.stdin.pause();
  ws.send({ type: "session.close" });
  closeTimeout = setTimeout(() => {
    console.error("Incomplete finalization: session.closed was not received");
    process.exitCode = 1;
    ws.socket.platformSocket.terminate();
  }, 15_000);
});
ws.on("error", (error) => {
  console.error(error.message);
  process.exitCode = 1;
});
ws.socket.on("close", () => {
  clearTimeout(closeTimeout);
  process.stdin.pause();
  if (!finalized) {
    console.error("Connection closed without final session usage");
    process.exitCode = 1;
  }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107import asyncio
import base64
import os
import signal
import sys

from openai import AsyncOpenAI
from openai.types.live.session_config_param import SessionConfigParam


async def main() -> None:
    # stdin/stdout carry raw mono PCM16 at 24 kHz, not WAV files.
    session: SessionConfigParam = {
        "model": "gpt-live-1",
        "instructions": "Be concise. Delegate requests needing current information to the backend, which can search the web.",
        "audio": {
            "format": {"type": "audio/pcm", "rate": 24000},
            "output": {"voice": "marin"},
        },
        "delegation": {
            "type": "responses",
            "responses": {
                "model": "gpt-5.6-luna",
                "tools": [{"type": "web_search"}],
                "tool_choice": "auto",
            },
        },
    }
    loop = asyncio.get_running_loop()
    chunks: asyncio.Queue[bytes] = asyncio.Queue()
    finalized = asyncio.Event()
    closing = False
    pending = b""
    close_task: asyncio.Task[None] | None = None

    def read_audio() -> None:
        chunk = os.read(sys.stdin.fileno(), 4800)
        if chunk:
            chunks.put_nowait(chunk)
        else:
            # EOF does not end a Live session. Use SIGINT to finalize it.
            loop.remove_reader(sys.stdin.fileno())

    async with AsyncOpenAI() as client:
        async with client.live.connect() as connection:

            async def send_audio() -> None:
                nonlocal pending
                while True:
                    chunk = pending + await chunks.get()
                    complete = len(chunk) - len(chunk) % 2
                    pending = chunk[complete:]
                    if complete and not closing:
                        await connection.session.input_audio.append(
                            audio=base64.b64encode(chunk[:complete]).decode("ascii")
                        )

            async def close_session() -> None:
                nonlocal closing
                closing = True
                loop.remove_reader(sys.stdin.fileno())
                await connection.session.close()
                try:
                    await asyncio.wait_for(finalized.wait(), timeout=15)
                except asyncio.TimeoutError:
                    print(
                        "Incomplete finalization: no session.closed event",
                        file=sys.stderr,
                    )
                    await connection.close()

            def request_close() -> None:
                nonlocal close_task
                if close_task is None:
                    close_task = asyncio.create_task(close_session())

            # Start receiving before a close command can be requested.
            await connection.session.start(session=session, event_id="event_start")
            sender = asyncio.create_task(send_audio())
            try:
                async for event in connection:
                    if event.type == "session.started":
                        print("Session ready", event.session.id, file=sys.stderr)
                        loop.add_reader(sys.stdin.fileno(), read_audio)
                        loop.add_signal_handler(signal.SIGINT, request_close)
                    elif event.type == "session.output_audio.delta":
                        sys.stdout.buffer.write(base64.b64decode(event.delta))
                        sys.stdout.buffer.flush()
                    elif event.type == "session.closed":
                        print("Final session usage", event.usage, file=sys.stderr)
                        finalized.set()
                        break
                    else:
                        print(event.model_dump_json(), file=sys.stderr)
            finally:
                loop.remove_reader(sys.stdin.fileno())
                loop.remove_signal_handler(signal.SIGINT)
                sender.cancel()
                await asyncio.gather(sender, return_exceptions=True)
                if close_task is not None:
                    await close_task
            if not finalized.is_set():
                raise RuntimeError("Connection closed without final session usage")


if __name__ == "__main__":
    asyncio.run(main())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152package main

import (
	"context"
	"encoding/base64"
	"fmt"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/live"
	"io"
	"os"
	"os/signal"
	"time"
)

func run() error {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()
	client := openai.NewClient()
	connection, err := client.Live.Connect(ctx, live.LiveConnectionOptions{})
	if err != nil {
		return err
	}
	defer connection.Abort()
	session := live.SessionConfigParam{
		Model:        "gpt-live-1",
		Instructions: openai.String("Be concise. Delegate requests needing current information to the backend, which can search the web."),
		Audio:        live.SessionConfigAudioParam{Format: live.AudioFormatParamOfAudioPCM(24000), Output: live.SessionConfigAudioOutputParam{Voice: live.SessionConfigAudioOutputVoiceUnionParam{OfString: openai.String("marin")}}},
		Delegation: live.SessionConfigDelegationUnionParam{OfResponses: &live.SessionConfigDelegationResponsesParam{Responses: live.ResponsesDelegationConfigParam{
			Model: "gpt-5.6-luna", Tools: []live.ResponsesDelegationConfigToolUnionParam{{OfWebSearch: &live.ResponsesDelegationConfigToolWebSearchParam{}}},
			ToolChoice: live.ResponsesDelegationConfigToolChoiceUnionParam{OfLiveToolChoiceEnum: openai.String("auto")},
		}}},
	}
	if err := connection.Send(ctx, live.ClientEventUnionParam{OfSessionStart: &live.SessionStartEventParam{Session: session, EventID: openai.String("event_start")}}); err != nil {
		return err
	}
	events := make(chan live.ServerEventUnion)
	failures := make(chan error, 2)
	go func() {
		for {
			event, err := connection.Recv(ctx)
			if err != nil {
				select {
				case failures <- err:
				case <-ctx.Done():
				}
				return
			}
			select {
			case events <- event:
			case <-ctx.Done():
				return
			}
		}
	}()
	audio := make(chan []byte)
	interrupts := make(chan os.Signal, 1)
	signal.Notify(interrupts, os.Interrupt)
	defer signal.Stop(interrupts)
	timer := time.NewTimer(30 * time.Second)
	defer timer.Stop()
	started, closing := false, false
	for {
		select {
		case <-timer.C:
			return fmt.Errorf("session startup or finalization timed out")
		case err := <-failures:
			return err
		case <-interrupts:
			if !started {
				return fmt.Errorf("interrupted before session.started")
			}
			if closing {
				continue
			}
			closing = true
			timer.Reset(15 * time.Second)
			if err := connection.Send(ctx, live.ClientEventUnionParam{OfSessionClose: &live.SessionCloseEventParam{}}); err != nil {
				return err
			}
		case chunk := <-audio:
			if closing {
				continue
			}
			if err := connection.Send(ctx, live.ClientEventUnionParam{OfSessionInputAudioAppend: &live.InputAudioAppendEventParam{Audio: base64.StdEncoding.EncodeToString(chunk)}}); err != nil {
				return err
			}
		case event := <-events:
			switch event.Type {
			case "error":
				return fmt.Errorf("Live error: %s", event.RawJSON())
			case "session.started":
				if started {
					continue
				}
				started = true
				timer.Stop()
				fmt.Fprintln(os.Stderr, "Session ready", event.AsSessionStartedEvent().Session.ID)
				// stdin/stdout carry raw mono PCM16 at 24 kHz, not WAV files.
				go func() {
					pending := []byte{}
					for {
						buffer := make([]byte, 4800)
						n, err := os.Stdin.Read(buffer)
						pending = append(pending, buffer[:n]...)
						complete := len(pending) - len(pending)%2
						if complete > 0 {
							chunk := append([]byte(nil), pending[:complete]...)
							pending = pending[complete:]
							select {
							case audio <- chunk:
							case <-ctx.Done():
								return
							}
						}
						if err != nil {
							if err != io.EOF {
								select {
								case failures <- err:
								case <-ctx.Done():
								}
							}
							// EOF does not close the session. Press Ctrl+C to finalize it.
							return
						}
					}
				}()
			case "session.output_audio.delta":
				chunk, err := base64.StdEncoding.DecodeString(event.AsOutputAudioDeltaEvent().Delta)
				if err != nil {
					return err
				}
				if _, err = os.Stdout.Write(chunk); err != nil {
					return err
				}
			case "session.closed":
				if !started {
					return fmt.Errorf("session closed before startup")
				}
				fmt.Fprintln(os.Stderr, "Final session usage", event.AsSessionClosedEvent().Usage)
				return nil
			default:
				fmt.Fprintln(os.Stderr, event.RawJSON())
			}
		}
	}
}
func main() {
	if err := run(); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130import com.openai.client.okhttp.OkHttpClient;
import com.openai.core.ClientOptions;
import com.openai.helpers.LiveConnection;
import com.openai.models.live.*;
import java.util.*;
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicBoolean;

public final class LiveConnectionWebsocketExample {
  public static void main(String[] args) throws Exception {
    var session =
        SessionConfig.builder()
            .model("gpt-live-1")
            .instructions(
                "Be concise. Delegate requests needing current information to the backend, which can search the web.")
            .audio(
                SessionConfig.Audio.builder()
                    .audioPcmFormat(AudioFormat.AudioPcm.Rate.of(24000L))
                    .output(SessionConfig.Audio.Output.builder().voice("marin").build())
                    .build())
            .responsesDelegation(
                ResponsesDelegationConfig.builder()
                    .model("gpt-5.6-luna")
                    .addToolWebSearch()
                    .toolChoice(ResponsesDelegationConfig.ToolChoice.LiveToolChoiceEnum.AUTO)
                    .build())
            .build();
    var closing = new AtomicBoolean();
    var finished = new CountDownLatch(1);
    var audio = new ArrayBlockingQueue<byte[]>(8);
    var failures = new ArrayBlockingQueue<Exception>(1);
    try (var http = OkHttpClient.builder().build();
        var connection =
            LiveConnection.connect(ClientOptions.builder().fromEnv().httpClient(http).build())) {
      Thread shutdown =
          new Thread(
              () -> {
                closing.set(true);
                try {
                  if (!finished.await(15, TimeUnit.SECONDS)) {
                    System.err.println("Incomplete finalization: no session.closed event");
                    connection.close();
                  }
                } catch (InterruptedException interrupted) {
                  Thread.currentThread().interrupt();
                }
              });
      Runtime.getRuntime().addShutdownHook(shutdown);
      try {
        connection.send(
            ClientEvent.ofSessionStart(
                SessionStartEvent.builder().session(session).eventId("event_start").build()));
        boolean started = false, closeSent = false;
        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(30);
        var incoming = connection.receiveAsync();
        while (true) {
          if (System.nanoTime() > deadline)
            throw new IllegalStateException("Session startup or finalization timed out");
          if (!failures.isEmpty()) throw failures.take();
          if (closing.get() && started && !closeSent) {
            closeSent = true;
            deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(15);
            connection.send(ClientEvent.ofSessionClose(SessionCloseEvent.builder().build()));
          }
          var chunk = audio.poll();
          if (chunk != null && !closing.get())
            connection.send(
                ClientEvent.ofSessionInputAudioAppend(
                    InputAudioAppendEvent.builder()
                        .audio(Base64.getEncoder().encodeToString(chunk))
                        .build()));
          ServerEvent event;
          try {
            event = incoming.get(20, TimeUnit.MILLISECONDS);
          } catch (TimeoutException waiting) {
            continue;
          }
          if (event.isErrorEvent()) throw new IllegalStateException(event.toString());
          if (event.isSessionStarted() && !started) {
            started = true;
            deadline = Long.MAX_VALUE;
            System.err.println("Session ready " + event.asSessionStarted().session().id());
            // stdin/stdout carry raw mono PCM16 at 24 kHz, not WAV files.
            Thread reader =
                new Thread(
                    () -> {
                      try {
                        int pending = -1;
                        while (!closing.get()) {
                          byte[] buffer = new byte[4800];
                          int offset = pending < 0 ? 0 : 1;
                          if (offset == 1) buffer[0] = (byte) pending;
                          int count = System.in.read(buffer, offset, buffer.length - offset);
                          // EOF does not close the session. Press Ctrl+C to finalize it.
                          if (count < 0) return;
                          count += offset;
                          pending = count % 2 == 0 ? -1 : Byte.toUnsignedInt(buffer[count - 1]);
                          int complete = count - count % 2;
                          if (complete > 0) audio.put(Arrays.copyOf(buffer, complete));
                        }
                      } catch (Exception error) {
                        failures.offer(error);
                      }
                    });
            reader.setDaemon(true);
            reader.start();
          } else if (event.isSessionOutputAudioDelta()) {
            System.out.write(Base64.getDecoder().decode(event.asSessionOutputAudioDelta().delta()));
            System.out.flush();
          } else if (event.isSessionClosed()) {
            if (!started) throw new IllegalStateException("Session closed before startup");
            System.err.println("Final session usage " + event.asSessionClosed().usage());
            return;
          } else {
            System.err.println(event);
          }
          incoming = connection.receiveAsync();
        }
      } finally {
        closing.set(true);
        finished.countDown();
        try {
          Runtime.getRuntime().removeShutdownHook(shutdown);
        } catch (IllegalStateException shuttingDown) {
          /* The hook is already draining. */
        }
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111require "openai"
require "base64"
$stdin.binmode
$stdout.binmode
session = {
  model: "gpt-live-1",
  instructions: "Be concise. Delegate requests needing current information to the backend, which can search the web.",
  audio: {
    format: {
      type: :"audio/pcm",
      rate: 24_000
    },
    output: { voice: :marin }
  },
  delegation: {
    type: :responses,
    responses: {
      model: "gpt-5.6-luna",
      tools: [{ type: :web_search }],
      tool_choice: :auto
    }
  }
}
client = OpenAI::Client.new
client.live.connect do |connection|
  state = {
    closing: false,
    finalized: false,
    started: false
  }
  threads = {}
  mutex = Mutex.new
  previous = trap("INT") do
    threads[:closer] ||= Thread.new do
      mutex.synchronize do
        state[:closing] = true
        if state[:started]
          connection.send_event(type: :"session.close")
        else
          connection.close
        end
      end
      sleep 15
      unless state[:finalized]
        warn "Incomplete finalization: no session.closed event"
        connection.close
      end
    end
  end
  begin
    threads[:startup] = Thread.new do
      sleep 30
      unless state[:started]
        warn "Session startup timed out"
        connection.close
      end
    end
    connection.send_event(type: :"session.start", session: session, event_id: "event_start")
    connection.each do |event|
      case event
      when OpenAI::Models::Live::ErrorEvent
        raise "Live error: #{event.to_json}"
      when OpenAI::Models::Live::SessionStartedEvent
        next if state[:started]

        state[:started] = true
        warn "Session ready #{event.session.id}"
        # stdin/stdout carry raw mono PCM16 at 24 kHz, not WAV files.
        threads[:sender] = Thread.new do
          pending = +"".b
          loop do
            pending << $stdin.readpartial(4800)
            complete = pending.bytesize - pending.bytesize % 2
            chunk = pending.slice!(0, complete).to_s
            mutex.synchronize do
              break if state[:closing]

              connection.send_event(type: :"session.input_audio.append", audio: Base64.strict_encode64(chunk)) unless chunk.empty?
            end
          end
        rescue EOFError
          # EOF does not close the session. Press Ctrl+C to finalize it.
          nil
        rescue => error
          warn "Audio input failed: #{error.class}"
          connection.close
        end
      when OpenAI::Models::Live::OutputAudioDeltaEvent
        $stdout.write(Base64.strict_decode64(event.delta))
        $stdout.flush
      when OpenAI::Models::Live::SessionClosedEvent
        raise "Session closed before startup" unless state[:started]

        warn "Final session usage #{event.usage}"
        state[:finalized] = true
        break
      else
        warn event.to_json
      end
    end
    raise "Connection closed without final session usage" unless state[:finalized]
  ensure
    trap("INT", previous)
    threads[:startup]&.kill
    threads[:startup]&.join
    threads[:sender]&.kill
    threads[:sender]&.join
    threads[:closer]&.kill
    threads[:closer]&.join
  end
end

Com a fonte de áudio e o reprodutor conectados, execute node client.mjs, python client.py, go run ., ruby client.rb ou seu aplicativo Java. Quando aparecer Session ready, envie um fluxo contínuo de áudio do microfone, respeitando a taxa de amostragem da gravação. Enviar um arquivo inteiro de uma só vez por um pipe não simula um microfone ao vivo. O fim da entrada de áudio (EOF) não encerra a conversa. Envie SIGINT ao processo para solicitar um encerramento normal.

O exemplo conecta os fluxos de áudio. Seu aplicativo cuida da captura, do armazenamento em buffer, da reprodução e, quando necessário, da reamostragem. Teste essas etapas com seus dispositivos e sua rede antes de avaliar o comportamento do modelo.

Escolha o formato de áudio

Defina session.audio.format ao iniciar a sessão. O mesmo formato se aplica à entrada e à saída e não pode ser alterado durante a sessão.

{"type":"audio/pcm","rate":24000}: PCM mono de 16 bits com sinal, em ordem little-endian, a 24 kHz (formato padrão).
{"type":"audio/pcm","rate":16000}: PCM mono de 16 bits com sinal, em ordem little-endian, a 16 kHz.
{"type":"audio/pcmu","rate":8000}: G.711 μ-law a 8 kHz, com um byte por amostra.
{"type":"audio/pcma","rate":8000}: G.711 A-law a 8 kHz, com um byte por amostra.

Codifique os bytes brutos em Base64, sem cabeçalho WAV ou de outro contêiner. Cada bloco PCM precisa conter amostras completas de 16 bits, portanto seu tamanho em bytes deve ser par. Se sobrar um byte no fim de um bloco de entrada, o exemplo o inclui no início do próximo. Respeitada essa condição, você pode dividir o áudio em blocos em qualquer ponto, desde que mantenha a continuidade e a ordem do fluxo.

Faça a reamostragem do áudio quando a taxa de amostragem for diferente da taxa configurada. Alterar a configuração de formato não converte os bytes de entrada. Para adaptar o exemplo ao G.711, encaminhe os bytes codificados de cada bloco sem aplicar o alinhamento de dois bytes específico do PCM e configure o reprodutor de saída para usar o mesmo codec. Um fluxo G.711 compatível pode ser transmitido sem conversão para PCM. Para conectar uma chamada telefônica, consulte Integrações de telefonia.

Envie e receba eventos

Envie cada evento como uma mensagem de texto em JSON. Essas mensagens transportam o áudio codificado em Base64.

Envio de áudio: envie session.input_audio.append com os bytes brutos codificados em Base64 no campo audio. Não há confirmação de recebimento para os blocos de áudio enviados.
Recebimento de áudio: decodifique o campo delta de cada evento session.output_audio.delta e coloque o áudio na fila de reprodução, na ordem de recebimento e no formato configurado.
Recebimento de transcrições: acrescente o texto do campo delta dos eventos session.input_transcript.delta e session.output_transcript.delta à transcrição correspondente.
Recebimento de eventos do backend: ao usar a delegação para a Responses API, processe o campo event contido em cada envelope response.event.
Tratamento de erros: trate os comandos rejeitados e os erros de sessão informados nos eventos error. Use error.client_event_id, quando presente, para identificar o comando.

Acompanhe a reprodução pela fila de áudio do seu aplicativo. A conexão WebSocket principal do GPT-Live envia o áudio de saída sem campos de temporização e sem emitir um evento que indique o fim desse áudio. Use as marcas de tempo da transcrição para organizar as legendas e os eventos do backend para acompanhar as tarefas delegadas.

Enquanto o áudio é transmitido continuamente, o GPT-Live determina quando ouvir e quando falar. Use response.create para iniciar ou continuar uma tarefa delegada ao backend. Consulte Delegação e ferramentas para conhecer esse fluxo.

Configure uma sessão em andamento

O modelo Live, as instruções iniciais da conversa, o formato de áudio, a voz e o modo de delegação são definidos no início da sessão e permanecem fixos. Use session.update para alterar as configurações compatíveis com o modo de delegação atual. As configurações omitidas mantêm seus valores. Quando a atualização é bem-sucedida, a API retorna session.updated com a configuração efetiva da sessão.

Use session.instructions.append para acrescentar instruções à conversa e session.input_audio.mute ou session.input_audio.unmute para controlar o áudio de entrada. Silenciar a entrada não cancela as tarefas do backend nem interrompe a fala gerada. Consulte Gerenciamento de sessões para saber mais sobre atualizações de contexto, transcrições, controles de entrada e dados de uso.

Encerre a sessão

Envie session.close quando a conversa terminar. Antes de enviar o comando, registre um listener para session.closed. Continue recebendo eventos até que esse evento chegue e só então libere a conexão. O exemplo aguarda até 15 segundos e informa que o encerramento ficou incompleto se o evento final não chegar.

Guarde os dados finais de uso de voz de session.closed e os eventos de uso do backend já recebidos. Cada atualização da duração de voz informa o total acumulado até aquele momento. Não some esses valores. Se ocorrer uma falha de transporte ou o tempo de espera se esgotar antes de session.closed, os dados finais de uso ficam sem confirmação. Consulte Gerenciamento de sessões para conhecer o ciclo de vida completo.

A API de WebSockets oferece transferência de dados em tempo real, tem amplo suporte e é uma ótima opção para conectar aplicativos à Realtime API da OpenAI em integrações entre servidores. Para clientes em navegadores ou dispositivos móveis, recomendamos a conexão via WebRTC.

Em uma integração entre servidores com a Realtime API, seu backend se conecta diretamente à API via WebSocket. Você pode usar uma chave de API padrão para autenticar a conexão, pois o token ficará disponível apenas no servidor seguro do backend.

Conexão direta com a Realtime API

Conecte-se via WebSocket

Os exemplos a seguir mostram como se conectar à Realtime API via WebSocket. Além de usar a URL de WebSocket indicada nos exemplos, envie um cabeçalho de autenticação com sua chave de API da OpenAI. Se o seu aplicativo atribui identificadores de segurança, envie no cabeçalho OpenAI-Safety-Identifier o identificador estável que preserva a privacidade do usuário final.

É possível usar WebSocket em navegadores com um token temporário de API, conforme descrito no guia de conexão via WebRTC. Porém, se a conexão partir de um cliente como um navegador ou aplicativo móvel, o WebRTC será uma solução mais robusta na maioria dos casos.

Conecte-se com o módulo ws (Node.js)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import WebSocket from "ws";

const url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1";
const ws = new WebSocket(url, {
  headers: {
    Authorization: "Bearer " + process.env.OPENAI_API_KEY,
    "OpenAI-Safety-Identifier": "hashed-user-id",
  },
});

let connected = false;
ws.on("message", function incoming(message) {
  const event = JSON.parse(message.toString());
  if (event.type === "error") throw new Error(event.error.message);
  if (event.type === "session.created") {
    connected = true;
    console.log(`Connected to the Realtime API: ${event.session.id}`);
    ws.close(1000);
  }
});
ws.on("close", () => {
  if (!connected)
    throw new Error("Connection closed before the session was created");
});

Conecte-se com websocket-client (Python)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39# example requires websocket-client library:
# pip install websocket-client

import os
import json
import websocket

OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]

url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"
headers = [
    "Authorization: Bearer " + OPENAI_API_KEY,
    "OpenAI-Safety-Identifier: hashed-user-id",
]


session_created = False


def on_message(ws, message):
    global session_created
    data = json.loads(message)
    if data["type"] == "session.created":
        session_created = True
        print("Connected to the Realtime API:", data["session"]["id"])
        ws.close()
    elif data["type"] == "error":
        ws.close()


ws = websocket.WebSocketApp(
    url,
    header=headers,
    on_message=on_message,
)

ws.run_forever()
if not session_created:
    raise RuntimeError("Connection closed before the Realtime session was created.")

Instale as gems necessárias com gem install openai async-websocket.

Conecte-se com o SDK da OpenAI (Ruby)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17require "openai"

client = OpenAI::Client.new(
  default_headers: { "OpenAI-Safety-Identifier" => "hashed-user-id" }
)

client.realtime.connect(model: "gpt-realtime-2.1") do |connection|
  created = connection.find do |event|
    raise event.error.message if event.is_a?(OpenAI::Realtime::RealtimeErrorEvent)

    next unless event.is_a?(OpenAI::Realtime::SessionCreatedEvent)

    puts("Connected to the Realtime API: #{event.session[:id]}")
    true
  end
  raise "Connection closed before the session was created" unless created
end

Use Java 17 ou posterior com com.openai:openai-java:4.75.1.

Conecte-se com o SDK da OpenAI (Java)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29import com.openai.client.okhttp.OkHttpClient;
import com.openai.core.ClientOptions;
import com.openai.helpers.RealtimeConnection;
import com.openai.helpers.RealtimeWebSocketOptions;
import com.openai.models.realtime.*;

var http = OkHttpClient.builder().build();
var options =
    ClientOptions.builder()
        .fromEnv()
        .httpClient(http)
        .putHeader("OpenAI-Safety-Identifier", "hashed-user-id")
        .build();
try (http;
    var connection =
        RealtimeConnection.connect(
            options,
            RealtimeWebSocketOptions.builder().model("gpt-realtime-2.1").build())) {
  while (true) {
    var event = connection.receive();
    if (event.error().isPresent())
      throw new IllegalStateException(event.error().orElseThrow().toString());
    if (event.sessionCreated().isPresent()) {
      System.out.println("Connected to server.");
      System.out.println(event);
      break;
    }
  }
}

Use Go 1.26 ou posterior e instale o SDK com go get github.com/openai/openai-go/v3@v3.85.1. O SDK gerencia o transporte de dados pelo socket. Seu aplicativo trata os eventos, captura e reproduz o áudio e restaura o estado da sessão após uma reconexão.

Conecte-se com o SDK da OpenAI (Go)

1
2
3
4
5
6
7
8ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := openai.NewClient()
conn, err := client.Realtime.Connect(ctx, realtime.RealtimeConnectionOptions{}, option.WithQuery("model", "gpt-realtime-2.1"), option.WithHeader("OpenAI-Safety-Identifier", "hashed-user-id"))
if err != nil {
	return err
}
defer conn.Close()

Instale o SDK com dotnet add package OpenAI –version 2.14.0. A Realtime API usa tipos experimentais do SDK. O exemplo inclui a diretiva necessária para lidar com o aviso do compilador.

Conecte-se com o SDK da OpenAI (.NET)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23using OpenAI.Realtime;

#pragma warning disable OPENAI002

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
RealtimeClient client = new(key);

RealtimeSessionClientOptions options = new();
options.Headers["OpenAI-Safety-Identifier"] = "hashed-user-id";
using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30));
using RealtimeSessionClient session = await client.StartConversationSessionAsync("gpt-realtime-2.1", options, cancellationToken: timeout.Token);
await foreach (RealtimeServerUpdate update in session.ReceiveUpdatesAsync(timeout.Token))
{
    if (update is RealtimeServerUpdateError error)
        throw new InvalidOperationException(error.Error.Message);
    if (update is RealtimeServerUpdateSessionCreated)
    {
        Console.WriteLine("Connected to server.");
        Console.WriteLine(System.ClientModel.Primitives.ModelReaderWriter.Write(update));
        return;
    }
}
throw new InvalidOperationException("Connection closed before session creation.");

Conecte-se com a interface WebSocket padrão (navegadores)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23/*
Note that in client-side environments like web browsers, we recommend
using WebRTC instead. It is possible, however, to use the standard
WebSocket interface in browser-like environments like Deno and
Cloudflare Workers.
*/

const ws = new WebSocket(
  "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1",
  [
    "realtime",
    // Use a short-lived token fetched from your application server.
    "openai-insecure-api-key." + OPENAI_REALTIME_EPHEMERAL_KEY,
  ]
);

ws.addEventListener("open", function open() {
  console.log("Connected to server.");
});

ws.addEventListener("message", function incoming(event) {
  console.log(event.data);
});

Envio e recebimento de eventos

O gerenciamento de sessões da Realtime API combina eventos enviados pelo cliente, que você emite pelo seu código, e eventos enviados pelo servidor, que a Realtime API gera para indicar o que acontece ao longo do ciclo de vida da sessão.

Em uma conexão WebSocket, você envia e recebe eventos serializados em JSON como strings de texto. O exemplo a seguir usa Node.js, e os mesmos princípios se aplicam a outras bibliotecas de WebSocket.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29import WebSocket from "ws";

const url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1";
const ws = new WebSocket(url, {
  headers: {
    Authorization: "Bearer " + process.env.OPENAI_API_KEY,
    "OpenAI-Safety-Identifier": "hashed-user-id",
  },
});

ws.on("open", function open() {
  console.log("Connected to server.");

  // Send client events over the WebSocket once connected
  ws.send(
    JSON.stringify({
      type: "session.update",
      session: {
        type: "realtime",
        instructions: "Be extra nice today!",
      },
    })
  );
});

// Listen for and parse server events
ws.on("message", function incoming(message) {
  console.log(JSON.parse(message.toString()));
});

A interface WebSocket talvez seja a de mais baixo nível disponível para interagir com um modelo Realtime. Ao usá-la, você fica responsável por enviar e processar blocos de áudio codificados em Base64 pela conexão de socket.

Para saber como enviar e receber áudio via WebSockets, consulte o guia de conversas em tempo real.

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Provedores de nuvem

Recursos

APIs legadas

Escolha um modelo

Texto e código

Como escrever prompts

Raciocínio

Imagens

Tempo real e áudio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Busca e recuperação de informações

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolver aplicações de voz

Conexões

Processamento de áudio

Coloque em produção

Desempenho e qualidade

Avaliação

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Planejar

Desenvolver

Testar e publicar

Especificações de conversão

Guias

Recursos

Identidade

Uso do plano do ChatGPT

Guias

Envio de arquivos

API

Mensuração

API para anunciantes

Referência da API

Primeiros passos

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Sites

dots

ChatGPT Space

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Ampliar os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Ampliar recursos e automatizar tarefas

Ambientes

Codex Cloud

Desenvolver com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

Configuração de recursos

Identidade e acesso