Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Der WebSocket-Endpunkt und die Echtzeit-Verbindung

Lektion 1 von 16 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Die Echtzeit-Voice-Agent-API
  2. Die WebSocket-Verbindung öffnen
  3. Lebenszyklus der Sitzung
  4. Kernaussagen

Aktualisiert am 3. November 2026, basierend auf den xAI-Seiten zu Speech to Speech, Pricing und Rate limits: 0,08 USD pro Minute, gleichzeitige Sitzungen pro Tarifstufe und grok-voice-3.0 als aktuelles Modell. Quellen: Speech to Speech · Pricing · Rate limits.

Die Echtzeit-Voice-Agent-API

Die Grok Voice Agent API ermöglicht es Ihnen, konversationelle Voice-Agenten zu erstellen, die mit Ihren Nutzern in Echtzeit sprechen. Im Gegensatz zu klassischen REST-APIs, die Anfrage für Anfrage arbeiten, nutzt diese API das WebSocket-Protokoll, um eine persistente bidirektionale Verbindung zwischen Ihrer Anwendung und den Servern von xAI aufrechtzuerhalten.

Voice Agent API documentation

Es gibt einen einzigen Endpunkt:

wss://api.x.ai/v1/realtime

Sie wählen das Modell über den URL-Parameter model, beispielsweise wss://api.x.ai/v1/realtime?model=grok-voice-latest. grok-voice-latest verweist auf grok-voice-3.0, das aktuelle Modell, und ist zudem der Standardwert. In der Produktion empfiehlt xAI, eine benannte Version festzulegen.

Dieser einzelne Endpunkt verwaltet den gesamten Lebenszyklus einer Sprachkonversation: Er empfängt Audio, erkennt Sprache, generiert die Antwort und sendet das synthetisierte Audio zurück.

WebSocket
Echtzeit-Protokoll
grok-voice-3.0
Aktuelles Modell
10
Gleichzeitige Sitzungen im Einstiegs-Tarif
0,08 USD/Min
Preise

Die WebSocket-Verbindung öffnen

Um eine Verbindung herzustellen, geben Sie Ihren xAI API-Schlüssel im Autorisierungs-Header an. Hier ist ein Beispiel in JavaScript:

const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
  headers: {
    "Authorization": "Bearer " + process.env.XAI_API_KEY
  }
});

ws.on("open", () => {
  console.log("WebSocket-Verbindung hergestellt");
});

ws.on("message", (data) => {
  const event = JSON.parse(data);
  console.log("Ereignis empfangen:", event.type);
});

ws.on("close", (code, reason) => {
  console.log("Verbindung geschlossen:", code, reason);
});

ws.on("error", (err) => {
  console.error("WebSocket-Fehler:", err);
});

In Python können Sie die Bibliothek websockets verwenden:

import asyncio
import websockets
import json
import os

async def connect():
    uri = "wss://api.x.ai/v1/realtime"
    headers = {
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}"
    }

    async with websockets.connect(uri, additional_headers=headers) as ws:
        async for message in ws:
            event = json.loads(message)
            print(f"Ereignis: {event['type']}")

asyncio.run(connect())

Lebenszyklus der Sitzung

Sobald die WebSocket-Verbindung geöffnet ist, sendet der Server ein session.created-Ereignis, das bestätigt, dass die Sitzung aktiv ist. Sie senden dann ein session.update-Ereignis, um die Konversation zu konfigurieren (Stimme, Anweisungen, Tools, Spracherkennung).

Der typische Zyklus sieht wie folgt aus:

  1. Verbindung: Öffnen Sie das WebSocket mit Authentifizierung.
  2. Konfiguration: Senden Sie session.update mit Ihren Einstellungen.
  3. Bestätigung: Empfangen Sie session.updated vom Server.
  4. Konversation: Tauschen Sie Audio- und Textereignisse aus.
  5. Schließen: Trennen Sie das WebSocket sauber.

Fehler bei der Verbindung behandeln

Der Server kann die Verbindung aus mehreren Gründen schließen oder ablehnen: ein Authentifizierungsfehler, Überschreiten des Limits für gleichzeitige Sitzungen Ihres Tarifs (10 im Einstiegs-Tarif, bis zu 200 im höchsten Tarif) oder ein Vorfall. Die aktuelle Dokumentation legt keine maximale Sitzungsdauer fest, und die Wiederaufnahme einer Sitzung (Lektion 4) ermöglicht es Ihnen, eine Konversation nach einem Abbruch fortzusetzen. Ihre Anwendung sollte eine Wiederverbindungslogik mit exponentiellem Backoff enthalten.

Preise geprüft am 3. November 2026. Die Preise ändern sich häufig: Bevor Sie Budgets planen, überprüfen Sie die aktuellen Tarife auf der offiziellen xAI-Preissseite.

Kernaussagen

  • Der WebSocket-Endpunkt wss://api.x.ai/v1/realtime ist der einzige Einstiegspunkt für alle Sprachkonversationen.
  • Sie authentifizieren sich mit dem Header Authorization: Bearer {API key}.
  • Die Anzahl der gleichzeitigen Sitzungen hängt von Ihrem Tarif ab: 10 im Einstiegs-Tarif, bis zu 200.
  • Der Server sendet session.created bei der Verbindung und wartet darauf, dass Sie session.update senden, um die Konversation zu konfigurieren.
  • Die Preise betragen 0,08 USD pro Minute oder 4,80 USD pro Stunde, plus 0,004 USD pro Texteingabe.