Anleitung zur Nutzung der GPT-Realtime-2.1-mini API

Sprachagenten benötigten früher drei bewegliche Teile: Spracherkennung, ein Sprachmodell und dann Text-zu-Sprache. Jeder Schritt fügte Latenz hinzu und verlor den Ton. Die Realtime API von OpenAI fasst dies in einem einzigen Sprach-zu-Sprache-Modell zusammen, und gpt-realtime-2.1-mini ist die günstigere, schnellere Stufe dieser Familie. Es hört Audio, denkt und antwortet über eine einzige Streaming-Verbindung.

Dieser Leitfaden zeigt Ihnen, wie Sie es End-to-End aufrufen: welche Modell-ID Sie verwenden, wie Sie über WebSocket und WebRTC verbinden, wie Sie eine Sitzung gestalten und wie Sie das Ganze mit Apidog testen, bevor Sie es in eine App integrieren. Alles hier entspricht dem offiziellen OpenAI Realtime-Leitfaden.

Zuerst den richtigen Modellnamen verwenden

Die Namensgebung verwirrt oft, daher klären wir das vor jedem Code. Es gibt zwei Bezeichner für dasselbe Mini-Modell:

• gpt-realtime-2.1-mini: die versionierte ID. Dies ist, was auf der OpenAI-Preisgestaltungsseite erscheint und Sie an die 2.1-Generation bindet.
• gpt-realtime-mini: der Familien-Alias. Er verweist immer auf den neuesten Schnappschuss, derzeit gpt-realtime-mini-2025-12-15.

Schnappschüsse ermöglichen es Ihnen, das Verhalten in der Produktion zu fixieren:

Verwenden Sie den Alias während der Entwicklung und fixieren Sie dann einen datierten Schnappschuss, bevor Sie ausliefern, damit ein Modell-Update das Verhalten Ihres Agenten nicht über Nacht ändert.

Was gpt-realtime-2.1-mini leistet

Es ist ein Sprach-zu-Sprache-Modell. Sie streamen Audio hinein, und es streamt Audio mit natürlicher Intonation zurück, ohne einen separaten Transkriptions- oder TTS-Schritt. Es verarbeitet auch Text, sodass Sie Texteingaben und gesprochene Ausgaben in derselben Sitzung mischen können.

Hier ist das Datenblatt von der Modellseite:

marin und cedar sind die neuesten Stimmen und exklusiv für die Realtime API verfügbar; OpenAI empfiehlt sie für die natürlichste Ausgabe. Die älteren Stimmen funktionieren weiterhin, wenn Sie ein bestimmtes Timbre wünschen.

Die „Mini“-Stufe tauscht etwas Denkfähigkeit gegen geringere Latenz und eine deutlich niedrigere Rechnung ein. Für die meisten Support-Bots, Bestellabläufe und Sprach-Frontends ist dies die richtige Standardeinstellung. Greifen Sie nur auf das vollständige gpt-realtime-2.1 zurück, wenn die Konversation eine komplexere Argumentation erfordert.

Was es kostet

Mini ist etwa ein Drittel des Preises des vollständigen Modells. Token-Raten von der Preisgestaltungsseite:

Audio dominiert die Rechnung, und der größte Kostenhebel ist, wie viel Ihr Agent spricht. Ein Agent, der 35 Sekunden pro Minute spricht, kostet ungefähr doppelt so viel wie einer, der 15 Sekunden pro Minute spricht. Die tatsächlichen Pro-Minute-Kosten für Mini liegen je nach Ausführlichkeit bei etwa $0.06 bis $0.15. Weisen Sie Ihr Modell also an, in den Anweisungen prägnant zu sein, und Sie werden die Rechnung direkt reduzieren. Die Preise ändern sich, daher sollten Sie diese vor der Prognose auf der aktuellen Preisgestaltungsseite überprüfen.

Voraussetzungen

Sie benötigen drei Dinge:

1. Einen OpenAI API-Schlüssel mit Realtime-Zugriff, der als OPENAI_API_KEY festgelegt ist.
2. Node.js 18+ für die Server-Beispiele (das ws-Paket für rohes WebSocket oder das offizielle openai SDK).
3. Für Browser-Audio eine Seite, die über HTTPS oder localhost bereitgestellt wird, damit getUserMedia funktioniert.

Eine Regel, bevor Sie den Browser berühren: Senden Sie niemals Ihren echten API-Schlüssel an den Client. Browser- und Mobil-Apps verwenden stattdessen kurzlebige, temporäre Tokens. Mehr dazu weiter unten.

Eine Verbindungsmethode auswählen

Das Mini-Modell unterstützt drei Transportprotokolle. Wählen Sie je nachdem, wo sich Ihr Audio befindet.

Die meisten Leute beginnen mit WebSocket, um serverseitig Prototypen zu erstellen, und wechseln dann zu WebRTC für den eigentlichen Client. Machen wir beides.

Quickstart 1: WebSocket von Ihrem Server

WebSocket ist der schnellste Weg, das Modell reagieren zu sehen. Der Endpunkt ist eine einzelne URL mit dem Modell im Abfrage-String:

wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini

Da dies die GA-Schnittstelle ist, authentifizieren Sie sich mit einem einfachen Authorization: Bearer-Header und benötigen den alten OpenAI-Beta-Header nicht mehr. Hier ist ein Text-in, Text-out „Hallo Welt“, damit Sie ohne Mikrofon testen können:

import WebSocket from "ws";

const url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini";
const ws = new WebSocket(url, {
  headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
});

ws.on("open", () => {
  // 1. Sitzung konfigurieren
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      type: "realtime",
      model: "gpt-realtime-2.1-mini",
      output_modalities: ["text"],
      instructions: "You are a concise API support agent. Keep answers short.",
    },
  }));

  // 2. Benutzernachricht hinzufügen
  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "message",
      role: "user",
      content: [{ type: "input_text", text: "What is an idempotent request?" }],
    },
  }));

  // 3. Eine Antwort anfordern
  ws.send(JSON.stringify({ type: "response.create" }));
});

ws.on("message", (raw) => {
  const event = JSON.parse(raw.toString());
  if (event.type === "response.output_text.delta") process.stdout.write(event.delta);
  if (event.type === "response.done") ws.close();
});

Der Ablauf ist immer derselbe: konfigurieren, Eingabe hinzufügen, eine Antwort anfordern, auf Deltas hören. Serverereignisse werden als JSON zurückgestreamt. Die wichtigsten sind:

• session.created / session.updated: Ihre Konfiguration wurde akzeptiert
• response.output_text.delta: ein Textabschnitt
• response.output_audio.delta: ein Abschnitt von base64-Audio
• response.output_audio_transcript.delta: die Transkription dessen, was das Modell sagt
• response.done: die Runde ist beendet

Um von Text zu Sprache zu wechseln, ändern Sie output_modalities auf ["audio"] und fügen Sie eine Audio-Konfiguration hinzu (nächster Abschnitt). Audio kommt in response.output_audio.delta-Ereignissen als base64 PCM-Blöcke an, die Sie dekodieren und abspielen.

Quickstart 2: WebRTC im Browser

Für eine echte Sprach-App nimmt der Browser das Mikrofon auf und spielt die Antwort direkt ab, was die Latenz niedrig hält. Der Haken ist die Authentifizierung: Sie können Ihren API-Schlüssel nicht offenlegen, daher prägt Ihr Server zuerst einen kurzlebigen Token.

Schritt 1: Einen temporären Token auf Ihrem Server prägen. Rufen Sie den Client-Secrets-Endpunkt mit Ihrem echten Schlüssel auf:

// serverseitig
const r = await fetch("https://api.openai.com/v1/realtime/client_secrets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    session: { type: "realtime", model: "gpt-realtime-2.1-mini" },
  }),
});
const { value } = await r.json(); // temporärer Schlüssel, beginnt mit "ek_"

Senden Sie value an den Browser. Es läuft schnell ab, daher ist ein Leak risikoarm.

Schritt 2: Vom Browser aus verbinden mit WebRTC. Sie nehmen das Mikrofon auf, öffnen einen Datenkanal für Ereignisse und tauschen SDP mit dem Endpunkt /v1/realtime/calls aus:

// browserseitig: `EPHEMERAL_KEY` kam von Ihrem Server
const pc = new RTCPeerConnection();

// Audio des Modells wiedergeben
pc.ontrack = (e) => (document.getElementById("audio").srcObject = e.streams[0]);

// Mikrofon senden
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
pc.addTrack(mic.getTracks()[0]);

// Ereignisse fließen über einen Datenkanal
const channel = pc.createDataChannel("oai-events");
channel.onmessage = (e) => console.log(JSON.parse(e.data));

// SDP-Handshake
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

const sdpResp = await fetch(
  "https://api.openai.com/v1/realtime/calls?model=gpt-realtime-2.1-mini",
  {
    method: "POST",
    body: offer.sdp,
    headers: {
      Authorization: `Bearer ${EPHEMERAL_KEY}`,
      "Content-Type": "application/sdp",
    },
  }
);
await pc.setRemoteDescription({ type: "answer", sdp: await sdpResp.text() });

Sobald die Verbindung aktiv ist, hört das Modell auf dem Mikrofon-Track und spricht über pc.ontrack. Sie senden Konfiguration und Text über denselben oai-events-Datenkanal unter Verwendung derselben JSON-Ereignisse aus dem WebSocket-Beispiel.

Die Sitzung gestalten

Das session-Objekt ist der Ort, an dem Sie das Verhalten steuern. Dies ist die vollständige Audioversion dessen, was Sie oben gesehen haben:

{
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2.1-mini",
    output_modalities: ["audio"],
    instructions: "You are a friendly booking assistant. Confirm details before acting.",
    audio: {
      input: {
        format: { type: "audio/pcm", rate: 24000 },
        turn_detection: { type: "semantic_vad" },
      },
      output: {
        format: { type: "audio/pcm", rate: 24000 },
        voice: "marin",
      },
    },
  },
}

Die wichtigen Felder:

• instructions: Ihr System-Prompt. Legen Sie die Persona und die Leitplanken fest und „fassen Sie sich kurz“, wenn Ihnen die Kosten wichtig sind.
• output_modalities: ["audio"] für einen sprechenden Agenten, ["text"] für einen nur transkribierenden Bot.
• audio.output.voice: Wählen Sie aus den zehn Stimmen; marin oder cedar klingen am natürlichsten.
• audio.input.turn_detection: wie das Modell entscheidet, dass Sie aufgehört haben zu sprechen. semantic_vad wartet auf eine natürliche Pause in der Bedeutung; server_vad wird bei Stille ausgelöst. Semantische Erkennung unterbricht weniger und fühlt sich im Gespräch flüssiger an.

Ändern Sie jedes Feld während des Anrufs, indem Sie ein weiteres session.update senden. Sie müssen die Verbindung nicht erneut herstellen.

Tools hinzufügen, damit der Agent handeln kann

Ein Sprachagent, der nur chatten kann, ist eine Demo. Um einen Tisch zu buchen oder eine Bestellung zu überprüfen, benötigt das Modell Tools. Realtime verwendet denselben Funktionsaufruf-Vertrag wie der Rest der Plattform: Sie deklarieren Funktionen in der Sitzung, das Modell sendet einen Aufruf, Sie führen ihn aus und geben das Ergebnis zurück. Wenn Sie zuvor Tools in die Chat-API integriert haben, ist dies dasselbe mentale Modell; unser Leitfaden zu OpenAI Function Calling behandelt das Schema ausführlich, und strukturierte Ausgaben helfen, wenn die Argumente einer strengen Form entsprechen müssen.

Deklarieren Sie Tools innerhalb der Sitzung, verarbeiten Sie dann das Ereignis response.function_call_arguments.done, führen Sie Ihren Code aus und posten Sie ein conversation.item.create mit dem Ergebnis vor dem nächsten response.create. Für alles, was aufwändiger ist als ein paar Funktionen, bietet OpenAI’s AgentKit eine übergeordnete Methode zur Orchestrierung mehrstufiger Sprachagenten.

Endpunkte mit Apidog testen, bevor Sie entwickeln

Sie möchten keinen REST-Aufruf und einen WebSocket-Handshake debuggen, indem Sie Konsolenprotokolle in einer halbfertigen App lesen. Testen Sie die Komponenten zuerst isoliert. Hier verdient Apidog seinen Platz in einem Echtzeit-Workflow.

Zwei Dinge sollten Sie überprüfen, bevor Sie Client-Code schreiben:

1. Der Token-Endpunkt. POST https://api.openai.com/v1/realtime/client_secrets ist ein gewöhnlicher REST-Aufruf. Erstellen Sie eine Anfrage in Apidog, fügen Sie Ihren Authorization: Bearer-Header hinzu, fügen Sie den JSON-Body mit Ihrer Modell-ID ein und senden Sie sie. Sie sehen den ek_-Token und dessen Ablauf sofort, sodass Sie wissen, dass Ihr Schlüssel und der Kontozugriff in Ordnung sind, bevor WebRTC überhaupt ins Spiel kommt. Es ist derselbe Ansatz, den Sie verwenden würden, um jede der REST-Oberflächen von OpenAI zu testen, wie die Responses API.
2. Der WebSocket-Nachrichtenfluss. Apidog verfügt über einen WebSocket-Client, sodass Sie eine Verbindung zu wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini öffnen, den Auth-Header hinzufügen und die Nachrichten session.update, conversation.item.create und response.create einzeln manuell senden können. Das Beobachten der Serverereignisse in einem lesbaren Panel macht die Ereignissequenz offensichtlich, und Sie können die Nachrichten als Beispiele für Ihr Team speichern. Wenn Sie bereits auf solide API-Teststrategien setzen, passt dies genau.

Das isolierte Testen der Transportschicht bedeutet, dass Sie, wenn in der App etwas kaputtgeht, bereits wissen, dass es nicht am API-Vertrag liegt. Laden Sie Apidog herunter, wenn Sie mitmachen möchten.

Die Kosten im Griff behalten

Die Audioausgabe ist der teure Teil, daher zahlen sich einige Gewohnheiten aus:

• Weisen Sie das Modell an, prägnant zu sein. „Halten Sie die Antworten auf ein oder zwei Sätze“ in den Anweisungen reduziert direkt die Audio-Ausgabe-Tokens.
• Fixieren Sie einen Schnappschuss in der Produktion. gpt-realtime-mini-2025-12-15 wird sich nicht ändern; der Alias gpt-realtime-mini kann dies tun.
• Verwenden Sie semantic_vad. Weniger Fehlunterbrechungen bedeuten weniger verschwendete halbe Antworten, für die Sie bezahlen.
• Cachen Sie Ihren System-Prompt. Zwischengespeicherte Eingaben kosten $0.30 pro 1M gegenüber $0.60 für neue Texteingaben, daher ist ein stabiler Anweisungsblock bei jeder Runde günstiger.
• Schließen Sie inaktive Sitzungen. Eine offene Verbindung mit einem inaktiven Benutzer ist immer noch eine Sitzung, für die Ihnen möglicherweise Kosten berechnet werden.

Häufige Fehler und Lösungen

• 401 Unauthorized: Der Schlüssel ist falsch, oder Sie haben einen abgelaufenen temporären Token gesendet. Temporäre Schlüssel sind systembedingt kurzlebig; prägen Sie für jede Sitzung einen neuen.
• Modell nicht gefunden: Überprüfen Sie die genaue ID. Es ist gpt-realtime-2.1-mini, nicht gpt-realtime-mini-2.1.
• Kein Audio im Browser: Sie haben wahrscheinlich den Remote-Stream in pc.ontrack nicht angehängt, oder die Seite wird nicht über HTTPS/localhost bereitgestellt, sodass das Mikrofon nie geöffnet wurde.
• Das Modell hört nicht auf, den Benutzer zu überreden: Stellen Sie turn_detection auf semantic_vad um und stellen Sie sicher, dass der Mikrofon-Track die Verbindung erreicht.
• Senden des Beta-Headers: Der GA-Endpunkt benötigt OpenAI-Beta: realtime=v1 nicht. Entfernen Sie ihn.

FAQ

Ist gpt-realtime-2.1-mini dasselbe wie gpt-realtime-mini? Im Wesentlichen ja. gpt-realtime-2.1-mini ist die versionierte ID, gpt-realtime-mini ist der Alias, der auf den neuesten Schnappschuss verweist (gpt-realtime-mini-2025-12-15). Verwenden Sie den Alias zum Entwickeln, fixieren Sie den Schnappschuss zum Ausliefern.

Kann ich es für einfache Transkription anstelle eines Sprachagenten verwenden? Die Realtime API wurde für interaktive Sprach-zu-Sprache-Kommunikation entwickelt. Für einmalige Transkription sind die dedizierten Transkriptionsmodelle von OpenAI besser geeignet. Verwenden Sie das Mini-Echtzeitmodell, wenn Sie eine zweiseitige Konversation mit geringer Latenz benötigen.

Brauche ich WebRTC, oder reicht WebSocket aus? WebSocket ist ausreichend für serverseitige Pipelines und schnelle Prototypen. Verwenden Sie WebRTC, wenn ein Browser oder eine mobile App Audio direkt erfasst und wiedergibt, da es den Medienstrom und Jitter für Sie verwaltet.

Welche Stimme soll ich wählen? marin und cedar sind die neuesten und natürlichsten und exklusiv für die Realtime API verfügbar. Die anderen acht (alloy, ash, ballad, coral, echo, sage, shimmer, verse) funktionieren weiterhin, wenn Sie einen bestimmten Klang wünschen.

Wie wird dies abgerechnet? Pro Token, aufgeteilt nach Modalität. Für Mini: $0.60 pro 1M Texteingabe, $10 pro 1M Audioeingabe und $20 pro 1M Audioausgabe. Die Audioausgabe ist der dominierende Kostenfaktor, daher ist die Ausführlichkeit Ihr wichtigster Hebel.

Kann es Funktionen aufrufen wie die Chat-Modelle? Ja. Realtime verwendet denselben Funktionsaufruf-Vertrag, sodass ein Sprachagent Bestellungen nachschlagen, den Lagerbestand prüfen oder Aktionen mitten im Gespräch auslösen kann.

Nächste Schritte

Sie haben nun den vollständigen Kreislauf: die richtige Modell-ID, einen WebSocket-Prototypen, einen WebRTC-Browser-Client, Sitzungskonfiguration, Tools und eine Möglichkeit, jedes Element in Apidog zu testen, bevor es in Produktion geht. Beginnen Sie mit dem nur-Text-WebSocket-Beispiel, um den Zugriff zu bestätigen, wechseln Sie output_modalities auf Audio und wechseln Sie dann zu WebRTC, wenn Sie für ein echtes Mikrofon bereit sind. Fixieren Sie einen Schnappschuss, weisen Sie das Modell an, prägnant zu sein, und Sie erhalten einen Sprachagenten mit geringer Latenz, der Sie bei der Rechnung nicht überrascht.