WebSockets | OpenAI API

Choisissez votre API pour afficher les étapes de connexion et les événements de session correspondants.

Connexion d’un serveur à GPT-Live

Nous recommandons WebRTC pour les connexions audio à GPT-Live, y compris pour les intégrations de serveur à serveur.

GPT-Live prend également en charge les connexions WebSocket. La connexion WebSocket principale transporte l’audio et les événements JSON dans les deux sens. Conservez la clé API du projet sur votre serveur de confiance.

Ce guide explique comment transmettre un flux audio à GPT-Live. Pour surveiller ou piloter une session existante, consultez Contrôles côté serveur. Pour connecter un backend chargé du raisonnement et de l’exécution des outils à l’API Responses, consultez Mode WebSocket de l’API Responses.

Authentification et démarrage de la session

Connectez-vous à wss://api.openai.com/v1/live/sessions sans paramètre de requête. Authentifiez-vous avec Authorization: Bearer $OPENAI_API_KEY et incluez les en-têtes de connexion indiqués dans l’exemple.
Envoyez session.start comme premier message. Dans l’objet session, indiquez le modèle, les instructions de conversation, le format audio, la voix et la configuration de la délégation.
Attendez l’événement session.started avant d’envoyer des données audio ou des commandes de l’application. Cet événement contient la configuration effective de la session et son identifiant.

L’exemple ci-dessous utilise la voix Marin, de l’audio PCM16 à 24 kHz et un backend Responses avec recherche web. Formulez des instructions de conversation courtes. Pour configurer les instructions du backend, ses outils et leurs autorisations, consultez Délégation et outils.

Transmission d’un flux audio avec un SDK

Pour Node.js, installez openai et ws avec npm install openai ws, puis enregistrez l’exemple JavaScript sous le nom client.mjs. Pour Python sur macOS ou Linux, installez openai[realtime], puis enregistrez l’exemple Python sous le nom client.py. Définissez OPENAI_API_KEY dans l’environnement du serveur. Ces exemples nécessitent une version du SDK compatible avec Live. L’exemple lit un flux audio brut PCM16 mono à 24 kHz sur l’entrée standard et écrit l’audio reçu dans le même format sur la sortie standard. Reliez ces flux aux fonctions de capture et de lecture audio de votre application. Les journaux et les événements de transcription sont écrits sur la sortie d’erreur standard pour préserver l’intégrité du flux audio.

Pour Go, utilisez Go 1.26 ou une version ultérieure, enregistrez l’exemple sous le nom main.go, initialisez un module avec go mod init live-demo, puis installez github.com/openai/openai-go/v3@v3.85.1 avec go get. Pour Java, utilisez Java 17 ou une version ultérieure, ajoutez la dépendance Maven com.openai:openai-java:4.95.0 et utilisez la classe LiveConnectionWebsocketExample. Pour Ruby 3.3 ou une version ultérieure, installez le SDK avec gem install openai -v 0.110.0, installez sa dépendance WebSocket avec gem install async-websocket, puis enregistrez l’exemple sous le nom 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

Exécutez node client.mjs, python client.py, go run ., ruby client.rb ou votre application Java après avoir connecté votre source audio et votre lecteur. Une fois le message Session ready affiché, transmettez en continu l’audio du microphone au rythme de l’enregistrement, en respectant sa fréquence d’échantillonnage. Envoyer tout un fichier d’un seul coup via un tube ne simule pas un microphone en direct. La fin du flux (EOF) de la source audio ne met pas fin à la conversation. Envoyez SIGINT au processus pour demander une fermeture propre.

L’exemple relie les flux audio. Votre application assure la capture, la mise en mémoire tampon, la lecture et, si nécessaire, le rééchantillonnage. Testez ces fonctions avec vos appareils et votre réseau avant d’évaluer le comportement du modèle.

Choix du format audio

Définissez session.audio.format au démarrage. Le même format s’applique à l’entrée et à la sortie et reste fixe pendant toute la session.

{"type":"audio/pcm","rate":24000} : PCM mono signé sur 16 bits à 24 kHz, octet de poids faible en premier (format par défaut).
{"type":"audio/pcm","rate":16000} : PCM mono signé sur 16 bits à 16 kHz, octet de poids faible en premier.
{"type":"audio/pcmu","rate":8000} : G.711 loi μ à 8 kHz, un octet par échantillon.
{"type":"audio/pcma","rate":8000} : G.711 loi A à 8 kHz, un octet par échantillon.

Encodez les octets bruts en base64, sans en-tête WAV ni en-tête d’un autre conteneur. Chaque bloc PCM doit contenir des échantillons complets de 16 bits et donc un nombre pair d’octets. S’il reste un octet en fin de bloc, l’exemple le reporte au début du bloc d’entrée suivant. Pour le reste, vous pouvez découper le flux librement, à condition de préserver sa continuité et l’ordre des données.

Rééchantillonnez l’audio si sa fréquence d’échantillonnage diffère de la fréquence configurée. Modifier le format dans la configuration ne convertit pas les octets d’entrée. Pour adapter l’exemple à G.711, transmettez les octets encodés de chaque bloc sans appliquer l’alignement sur deux octets propre au PCM, puis configurez le lecteur de sortie pour qu’il utilise le même codec. Un flux G.711 conforme à la configuration peut être transmis sans conversion en PCM. Pour connecter un appel téléphonique, consultez Intégrations téléphoniques.

Envoi et réception d’événements

Envoyez chaque événement dans un message texte au format JSON. Ces messages transportent l’audio encodé en base64.

Envoi de l’audio : envoyez session.input_audio.append en plaçant les octets bruts encodés en base64 dans audio. Les ajouts de données audio ne donnent lieu à aucun accusé de réception.
Réception de l’audio : décodez delta dans chaque événement session.output_audio.delta, puis placez les blocs audio dans la file de lecture dans l’ordre de réception, en utilisant le format configuré.
Réception des transcriptions : ajoutez le texte du champ delta des événements session.input_transcript.delta et session.output_transcript.delta à la transcription correspondante.
Réception des événements du backend : si vous utilisez la délégation à Responses, traitez l’objet event imbriqué dans chaque enveloppe response.event.
Gestion des erreurs : traitez les rejets de commandes et les erreurs de session signalés par les événements error. Utilisez error.client_event_id, s’il est présent, pour identifier la commande.

Suivez la lecture à l’aide de la file d’attente audio de votre application. La connexion WebSocket principale de GPT-Live transmet l’audio de sortie sans champs temporels ni événement signalant la fin de l’audio de sortie. Utilisez les horodatages des transcriptions pour organiser les sous-titres et les événements du backend pour suivre les tâches déléguées.

Pendant la transmission continue de l’audio, GPT-Live détermine quand écouter et quand prendre la parole. Utilisez response.create pour lancer ou poursuivre une tâche déléguée au backend. Pour en savoir plus sur cette procédure, consultez Délégation et outils.

Configuration d’une session en cours

Le modèle Live, les instructions de conversation initiales, le format audio, la voix et le mode de délégation sont fixés au démarrage. Utilisez session.update pour modifier les paramètres pris en charge dans le mode de délégation actuel. Les paramètres omis conservent leur valeur. Si la mise à jour réussit, vous recevez session.updated avec la configuration effective de la session.

Utilisez session.instructions.append pour ajouter des instructions de conversation et session.input_audio.mute ou session.input_audio.unmute pour couper ou réactiver l’entrée audio. Couper l’entrée audio n’annule pas les tâches du backend et n’interrompt pas la parole générée. Pour en savoir plus sur les mises à jour du contexte, les transcriptions, les commandes d’entrée et les données d’utilisation, consultez Gestion des sessions.

Fermeture de la session

Envoyez session.close à la fin de la conversation. Enregistrez au préalable un gestionnaire pour session.closed, continuez à recevoir les événements jusqu’à la réception de cet événement final, puis libérez la connexion. L’exemple attend jusqu’à 15 secondes et signale que la fermeture n’a pas abouti si l’événement final n’arrive pas.

Conservez les données finales d’utilisation de la voix fournies par session.closed ainsi que les événements d’utilisation du backend déjà reçus. Chaque mise à jour de la durée d’utilisation de la voix indique un total cumulé. Ne les additionnez pas. En cas d’erreur de transport ou d’expiration du délai avant la réception de session.closed, les données finales d’utilisation restent à confirmer. Pour consulter l’ensemble du cycle de vie, reportez-vous à Gestion des sessions.

L’API WebSockets, largement prise en charge, permet de transférer des données en temps réel. Elle convient particulièrement bien aux applications qui se connectent à la Realtime API d’OpenAI de serveur à serveur. Pour les navigateurs et les clients mobiles, nous recommandons une connexion via WebRTC.

Dans une intégration de serveur à serveur avec Realtime, votre backend se connecte directement à la Realtime API via WebSocket. Vous pouvez authentifier cette connexion avec une clé API standard, puisque le jeton d’authentification reste accessible uniquement sur votre serveur backend sécurisé.

Connexion directe à la Realtime API

Connexion via WebSocket

Les exemples ci-dessous montrent comment se connecter à la Realtime API via WebSocket. Utilisez l’URL WebSocket indiquée et transmettez un en-tête d’authentification contenant votre clé API OpenAI. Si votre application attribue des identifiants de sécurité, transmettez dans l’en-tête OpenAI-Safety-Identifier l’identifiant stable qui préserve la confidentialité de l’utilisateur final.

Dans un navigateur, vous pouvez utiliser WebSocket avec un jeton API éphémère, comme expliqué dans le guide de connexion WebRTC. Toutefois, pour une connexion depuis un client tel qu’un navigateur ou une application mobile, WebRTC offre une solution plus robuste dans la plupart des cas.

Connexion avec le module 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");
});

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

Installez les gems nécessaires avec gem install openai async-websocket.

Connexion avec le SDK 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

Utilisez Java 17 ou une version ultérieure avec com.openai:openai-java:4.75.1.

Connexion avec le SDK 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;
    }
  }
}

Utilisez Go 1.26 ou une version ultérieure et installez le SDK avec go get github.com/openai/openai-go/v3@v3.85.1. Le SDK gère le transport des données via la connexion WebSocket. Votre application traite les événements, capture et lit l’audio, puis restaure l’état de la session après une reconnexion.

Connexion avec le SDK 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()

Installez le SDK avec dotnet add package OpenAI –version 2.14.0. La Realtime API utilise des types expérimentaux du SDK. L’exemple inclut la directive requise pour gérer l’avertissement correspondant.

Connexion avec le SDK 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.");

Connexion avec l’interface WebSocket standard (navigateurs)

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

Envoi et réception d’événements

La gestion des sessions de la Realtime API repose sur deux types d’événements : les événements envoyés par le client, que vous émettez depuis votre application, et les événements envoyés par le serveur, que la Realtime API génère pour signaler les étapes du cycle de vie de la session.

Sur une connexion WebSocket, vous envoyez et recevez les événements sérialisés en JSON sous forme de chaînes de caractères. L’exemple Node.js ci-dessous illustre ce fonctionnement. Les mêmes principes s’appliquent aux autres bibliothèques 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()));
});

L’interface WebSocket est peut-être l’interface de plus bas niveau disponible pour interagir avec un modèle Realtime. Votre application doit à la fois envoyer les blocs audio encodés en base64 sur la connexion et traiter ceux qu’elle reçoit.

Pour savoir comment envoyer et recevoir de l’audio via WebSocket, consultez le guide des conversations Realtime.

Suggestions

Premiers pas

Notions fondamentales

SDK et CLI

Fournisseurs de services cloud

Ressources

Anciennes API

Choisissez un modèle

Texte et code

Rédaction de prompts

Raisonnement

Images

Temps réel et audio

Modèles spécialisés

API Agents

Agents SDK

ChatKit

Recherche et récupération d’informations

Connectez des outils et des sources de données

Créez des workflows qui font appel à des outils

Ordinateur et code

Médias

GPT-Live

Realtime API

Créer des applications vocales

Connexions

Traitement audio

Mise en production

Performances et qualité

Évaluation

Coût et débit

Sécurité et gouvernance

Infrastructure et accès

Opérations

Concepts clés

Planification

Développement

Tests et publication

Spécifications de conversion

Guides

Ressources

Identité

Utilisation du forfait ChatGPT

Guides

Envoi de fichiers

API

Mesure des performances

API pour les annonceurs

Référence de l’API

Premiers pas

Premiers pas

Notions de base

Explorer

Disponible sur

Versions

Workflows

Capacités

Sites

dots

Espace ChatGPT

Référence

Personnalisation

Fichier de configuration

Configuration des agents

Étendre les fonctionnalités de ChatGPT et de Codex

Linux

Windows

Workflows de développement

Extensions et automatisation

Environnements

Codex Cloud

Développer avec Codex

Intégrations tierces

Référence

Autorisations

Codex Security

Cybersécurité

Premiers pas

Configuration des fonctionnalités

Identité et accès