WebSocket | OpenAI API

사용할 API를 선택하면 연결 절차와 세션 이벤트를 확인할 수 있습니다.

서버를 GPT-Live에 연결하기

서버 간 통합을 포함해 GPT-Live에 오디오를 연결할 때는 WebRTC를 권장합니다.

WebSocket도 지원합니다. 기본 WebSocket 연결 하나로 오디오와 JSON 이벤트를 양방향으로 주고받습니다. 프로젝트 API 키는 신뢰할 수 있는 서버에 보관하세요.

이 가이드에서는 GPT-Live로 오디오를 스트리밍하는 방법을 설명합니다. 기존 세션을 모니터링하거나 제어하려면 서버 측 제어를 참고하세요. 추론과 도구 실행을 담당하는 백엔드를 Responses API에 연결하려면 Responses WebSocket 모드를 참고하세요.

인증 및 세션 시작

쿼리 매개변수 없이 wss://api.openai.com/v1/live/sessions에 연결하세요. Authorization: Bearer $OPENAI_API_KEY로 인증하고 예제에 나온 연결 헤더를 포함하세요.
첫 번째 메시지로 session.start를 보내세요. session 객체에 모델, 대화 지침, 오디오 형식, 음성, 위임 설정을 지정하세요.
session.started를 받은 후에 오디오나 애플리케이션 명령어를 보내세요. 이 이벤트에는 실제로 적용된 세션 설정과 세션 ID가 포함됩니다.

아래 예제에서는 Marin 음성, 24 kHz PCM16 오디오, 웹 검색이 가능한 Responses 백엔드를 사용합니다. 대화 지침은 짧게 작성하세요. 백엔드 지침, 도구, 도구 권한은 위임 및 도구를 참고해 설정하세요.

SDK로 오디오 스트리밍하기

Node.js에서는 openai와 ws를 npm install openai ws로 설치하고 JavaScript 예제를 client.mjs로 저장하세요. macOS 또는 Linux에서 Python을 사용한다면 openai[realtime]을 설치하고 Python 예제를 client.py로 저장하세요. 서버 환경에 OPENAI_API_KEY를 설정하세요. 이 예제를 실행하려면 Live를 지원하는 SDK 버전이 필요합니다. 예제는 표준 입력에서 24 kHz 모노 PCM16 원시 오디오를 읽고, 반환된 오디오를 같은 형식으로 표준 출력에 씁니다. 이 스트림을 애플리케이션의 오디오 캡처 및 재생 기능에 연결하세요. 로그와 전사 이벤트는 오디오 스트림에 섞이지 않도록 표준 오류로 출력합니다.

Go에서는 Go 1.26 이상을 사용하세요. 예제를 main.go로 저장하고 go mod init live-demo로 모듈을 초기화한 다음 github.com/openai/openai-go/v3@v3.85.1을 go get으로 설치하세요. Java에서는 Java 17 이상을 사용하고 Maven 종속성 com.openai:openai-java:4.95.0을 추가한 다음 LiveConnectionWebsocketExample 클래스를 사용하세요. Ruby 3.3 이상에서는 gem install openai -v 0.110.0으로 SDK를 설치하고 gem install async-websocket으로 WebSocket 종속성을 설치한 다음 예제를 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

오디오 소스와 플레이어를 연결한 상태에서 node client.mjs, python client.py, go run ., ruby client.rb 또는 Java 애플리케이션을 실행하세요. Session ready가 표시되면 녹음 시의 샘플링 레이트에 맞춰 마이크 오디오를 연속으로 보내세요. 파일 전체를 한 번에 파이프로 보내면 실시간 마이크 입력을 재현할 수 없습니다. 오디오 소스에서 EOF에 도달해도 대화는 계속됩니다. 프로세스에 SIGINT를 보내 정상 종료를 요청하세요.

예제는 오디오 스트림을 연결합니다. 오디오 캡처, 버퍼링, 재생은 애플리케이션에서 처리하며, 필요한 경우 리샘플링도 수행합니다. 모델의 동작을 평가하기 전에 실제 기기와 네트워크에서 이 기능들을 테스트하세요.

오디오 형식 선택

세션을 시작할 때 session.audio.format을 설정하세요. 입력과 출력에 같은 형식이 적용되며 세션 도중에는 변경할 수 없습니다.

{"type":"audio/pcm","rate":24000}: 24 kHz 모노 PCM으로, 부호 있는 16비트 샘플을 리틀 엔디언으로 저장합니다. 기본값입니다.
{"type":"audio/pcm","rate":16000}: 16 kHz 모노 PCM으로, 부호 있는 16비트 샘플을 리틀 엔디언으로 저장합니다.
{"type":"audio/pcmu","rate":8000}: 8 kHz G.711 μ-law이며 샘플당 1바이트입니다.
{"type":"audio/pcma","rate":8000}: 8 kHz G.711 A-law이며 샘플당 1바이트입니다.

WAV 등 컨테이너 헤더를 제외한 원시 바이트를 Base64로 인코딩하세요. PCM 청크에는 온전한 16비트 샘플만 들어가야 하므로 바이트 수가 짝수여야 합니다. 예제에서는 마지막에 1바이트가 남으면 다음 입력 청크의 맨 앞에 붙입니다. 이 조건만 지키면 청크 경계는 자유롭게 정할 수 있습니다. 스트림이 끊기거나 순서가 바뀌지 않도록 하세요.

오디오의 샘플링 레이트가 설정값과 다르면 리샘플링하세요. 형식 설정을 바꿔도 입력 바이트가 변환되지는 않습니다. 예제를 G.711에 맞게 수정하려면 PCM 전용 2바이트 정렬 로직을 생략하고 각 청크의 코덱 바이트를 그대로 전달하세요. 출력 플레이어에도 같은 코덱을 설정하세요. 설정과 일치하는 G.711 스트림은 PCM으로 변환할 필요 없이 그대로 전달할 수 있습니다. 전화 통화를 연결하는 방법은 전화 통신 통합을 참고하세요.

이벤트 송수신

각 이벤트를 JSON 텍스트 메시지로 보내세요. 오디오는 이 메시지 안에 Base64로 인코딩해 전송합니다.

오디오 전송: session.input_audio.append를 보낼 때 audio 필드에 Base64로 인코딩한 원시 바이트를 넣으세요. 오디오 추가 요청에는 수신 확인 응답이 없습니다.
오디오 수신: delta 값을 각 session.output_audio.delta 이벤트에서 읽어 디코딩한 다음, 설정한 형식으로 순서대로 재생할 수 있도록 오디오를 큐에 넣으세요.
전사 텍스트 수신: delta에 담긴 텍스트를 session.input_transcript.delta와 session.output_transcript.delta에서 읽어 각각 입력 전사와 출력 전사에 이어 붙이세요.
백엔드 이벤트 수신: Responses 위임을 사용할 때는 중첩된 event를 각 response.event 메시지에서 꺼내 처리하세요.
오류 처리: error 이벤트를 받아 거부된 명령어와 세션 오류를 처리하세요. error.client_event_id가 있으면 이 값으로 해당 명령어를 식별하세요.

애플리케이션의 오디오 큐로 재생 진행 상태를 추적하세요. GPT-Live의 기본 WebSocket은 출력 오디오를 보내지만 타이밍 필드나 출력 오디오 완료 이벤트는 제공하지 않습니다. 전사 타임스탬프로 자막을 배치하고 백엔드 이벤트로 위임된 작업을 추적하세요.

오디오가 계속 스트리밍되는 동안 GPT-Live가 언제 듣고 말할지 결정합니다. response.create를 사용하면 백엔드에 위임한 작업을 시작하거나 이어서 진행할 수 있습니다. 이 워크플로우는 위임 및 도구를 참고하세요.

진행 중인 세션 설정

Live 모델, 초기 대화 지침, 오디오 형식, 음성, 위임 모드는 세션 시작 시 고정됩니다. 현재 위임 모드에서 지원하는 설정은 session.update로 변경하세요. 생략한 설정은 기존 값을 유지합니다. 업데이트에 성공하면 실제로 적용된 세션 설정이 담긴 session.updated가 반환됩니다.

대화 지침을 추가하려면 session.instructions.append를 사용하세요. 입력 오디오를 제어하려면 session.input_audio.mute 또는 session.input_audio.unmute를 사용하세요. 입력을 음소거해도 백엔드 작업이나 생성된 음성 출력은 계속됩니다. 컨텍스트 업데이트, 전사, 입력 제어, 사용량에 관한 자세한 내용은 세션 관리를 참고하세요.

세션 종료

대화가 끝나면 session.close를 보내세요. 보내기 전에 session.closed 리스너를 등록하세요. 이 이벤트가 도착할 때까지 계속 수신한 다음 연결을 해제하세요. 예제는 최대 15초 동안 기다리고, 그 안에 종료 이벤트가 도착하지 않으면 종료 처리가 완료되지 않았다고 알립니다.

session.closed에 포함된 최종 음성 사용량과 이미 수신한 백엔드 사용량 이벤트를 보관하세요. 음성 사용 시간 업데이트는 각 시점까지의 누적값이므로 서로 더하지 마세요. session.closed를 받기 전에 전송 오류가 발생하거나 시간이 초과되면 최종 사용량을 확인할 수 없습니다. 전체 세션 수명 주기는 세션 관리를 참고하세요.

WebSocket은 다양한 환경에서 지원하는 실시간 데이터 전송 API로, 애플리케이션 서버에서 OpenAI Realtime API에 연결할 때 적합합니다. 브라우저 및 모바일 클라이언트에서는 WebRTC로 연결하는 것이 좋습니다.

Realtime을 서버 간에 통합하면 백엔드 시스템이 WebSocket으로 Realtime API에 직접 연결합니다. 안전하게 관리되는 백엔드 서버에서만 토큰에 접근할 수 있으므로 표준 API 키로 연결을 인증할 수 있습니다.

Realtime API에 직접 연결하는 구조

WebSocket으로 연결하기

아래 예제에서는 WebSocket으로 Realtime API에 연결하는 여러 방법을 보여 줍니다. 예제의 WebSocket URL을 사용하고 OpenAI API 키가 담긴 인증 헤더도 함께 보내야 합니다. 애플리케이션에서 안전 식별자를 할당한다면 OpenAI-Safety-Identifier 헤더에 최종 사용자의 식별자를 넣어 보내세요. 같은 사용자에게는 일관된 식별자를 사용하고, 식별자에 개인정보가 드러나지 않도록 하세요.

브라우저에서도 WebRTC 연결 가이드에 나온 임시 API 토큰으로 WebSocket을 사용할 수 있습니다. 다만 브라우저나 모바일 앱 같은 클라이언트에서 연결할 때는 대부분 WebRTC가 더 안정적입니다.

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");
});

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.")

필요한 gem은 gem install openai async-websocket으로 설치하세요.

OpenAI SDK로 연결하기 (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

Java 17 이상과 com.openai:openai-java:4.75.1을 함께 사용하세요.

OpenAI SDK로 연결하기 (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;
    }
  }
}

Go 1.26 이상을 사용하고 go get github.com/openai/openai-go/v3@v3.85.1을 실행해 SDK를 설치하세요. SDK가 소켓 전송을 관리합니다. 애플리케이션은 이벤트 처리, 오디오 캡처 및 재생, 재연결 후 세션 상태 복원을 담당합니다.

OpenAI SDK로 연결하기 (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()

SDK는 dotnet add package OpenAI –version 2.14.0을 실행해 설치하세요. Realtime API는 실험적 SDK 타입을 사용하므로 예제에 필요한 경고 지시문이 포함되어 있습니다.

OpenAI SDK로 연결하기 (.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.");

표준 WebSocket으로 연결하기 (브라우저)

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);
});

이벤트 송수신

Realtime API 세션을 관리할 때는 개발자가 클라이언트에서 보내는 이벤트와 Realtime API가 세션 수명 주기의 변화를 알리기 위해 서버에서 보내는 이벤트를 함께 사용합니다.

WebSocket에서는 이벤트를 JSON으로 직렬화한 텍스트 문자열로 주고받습니다. 아래 Node.js 예제와 같은 원리가 다른 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()));
});

WebSocket은 Realtime 모델과 상호작용하는 인터페이스 중 가장 저수준에 가깝습니다. 애플리케이션에서 소켓 연결을 통해 Base64로 인코딩한 오디오 청크를 직접 전송하고 수신한 청크도 직접 처리해야 합니다.

WebSocket으로 오디오를 주고받는 방법은 Realtime 대화 가이드를 참고하세요.

추천

시작하기

핵심 개념

SDK 및 CLI

클라우드 제공업체

자료

레거시 API

모델 선택하기

텍스트 및 코드

프롬프트 작성

추론

이미지

실시간 처리 및 오디오

특화 모델

Agents API

Agents SDK

ChatKit

검색 및 정보 조회

도구와 데이터 연결하기

도구를 활용한 워크플로우 구축하기

컴퓨터 및 코드

미디어

GPT-Live

Realtime API

음성 기능 개발

연결

오디오 처리

서비스 출시하기

성능 및 품질

평가

비용 및 처리량

안전 및 거버넌스

인프라 및 접근 권한

운영

핵심 개념

기획

개발

테스트 및 게시

전환 명세

가이드

자료

사용자 식별

ChatGPT 요금제 사용량

가이드

파일 업로드

API

성과 측정

광고주 API

API 레퍼런스

시작하기

시작하기

기초

둘러보기

지원 플랫폼

릴리스

워크플로우

주요 기능

Sites

dot

ChatGPT 스페이스

레퍼런스

맞춤 설정

설정 파일

에이전트 설정

ChatGPT와 Codex 확장하기

Linux

Windows

개발 워크플로우

확장 및 자동화

환경

Codex Cloud

Codex로 개발하기

서드 파티 통합

레퍼런스

권한

Codex Security

사이버 안전

시작하기

기능 설정

ID 및 액세스