Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Streaming TTS über WebSocket

Lektion 9 von 14 Aktualisiert am 3. November 2026 Mittelstufe
Auf dieser Seite
  1. Warum Streaming das Erlebnis verändert
  2. Verbindung öffnen
  3. Das Nachrichtenprotokoll
  4. Eine vollständige Implementierung
  5. Wichtige Grenzen
  6. HTTP oder WebSocket
  7. Kernaussagen

Aktualisiert am 3. November 2026, basierend auf der xAI-Seite Text to Speech. Quelle: Text to Speech.

Warum Streaming das Erlebnis verändert

Im HTTP-Modus übergibt die TTS-Engine die Kontrolle erst zurück, sobald die gesamte Audioaufnahme erstellt wurde. Bei einer zweisätzigen Benachrichtigung fällt diese Wartezeit niemandem auf. Bei einem Blogbeitrag, einem Buchkapitel oder einem kontinuierlich scrollenden Nachrichtenfeed wird die Wartezeit jedoch zur größten Schwäche Ihres Produkts: Nutzer klicken, starren dann aber mehrere Sekunden lang auf einen Ladeindikator.

Der WebSocket-Modus eliminiert diese Wartezeit, indem er das Audio schrittweise übermittelt, sobald es synthetisiert wird. Die Wiedergabe beginnt bereits bei den ersten Wörtern, noch bevor der gesamte Text verarbeitet ist. Das ist der Unterschied zwischen einer Seite, die eingefroren wirkt, und Audio, das sofort abspielt.

Verbindung öffnen

Die Verbindung wird über wss://api.x.ai/v1/tts hergestellt, und alle Konfigurationseinstellungen erfolgen über die Abfragezeichenfolge (Query String) der URL, nicht in einer Initialisierungs-Nachricht.

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=en&voice=ara&codec=mp3&sample_rate=24000",
  {
    headers: {
      "Authorization": "Bearer " + XAI_API_KEY
    }
  }
);

Dies sind die akzeptierten Parameter:

  • language (erforderlich): ein BCP-47-Code oder auto
  • voice (optional, Standard: eve): die Voice-ID
  • codec (optional, Standard: mp3): das Ausgabe-Audioformat
  • sample_rate (optional, Standard: 24000): die Abtastfrequenz in Hz
  • bit_rate (optional, Standard: 128000): die Bitrate in bps (nur für MP3)

Diese Einstellungen gelten für die gesamte Sitzung: Sie können die Voice oder den Codec während der Sitzung nicht ändern. Wenn Ihre Anwendung zwischen zwei Erzählern wechseln muss, öffnen Sie zwei separate Verbindungen.

Das Nachrichtenprotokoll

Auf der Sendeseite benötigen Sie lediglich zwei Nachrichtentypen, um die Synthese zu steuern. Die erste Nachricht übermittelt einen Textabschnitt; die zweite meldet, dass der Text vollständig ist.

{ "type": "text.delta", "delta": "Hello and welcome " }
{ "type": "text.done" }

Sie können so viele text.delta-Nachrichten senden, wie nötig, wobei jede Nachricht bis zu 60.000 Zeichen umfassen kann. Es ist dennoch besser, dieses Limit nicht zu maximieren: Das Aufteilen des Textes in Abschnitte von wenigen Sätzen sorgt dafür, dass der erste Audioabschnitt viel schneller bei Ihnen ankommt, was der eigentliche Zweck von Streaming ist. Ein einzelner Delta-Wert von mehreren tausend Zeichen führt Sie zurück zum HTTP-Modus-Verhalten.

Auf der Empfangsseite enthält jede audio.delta-Nachricht ein Fragment von Audio, das im von Ihnen beim Verbinden gewählten Codec base64-kodiert ist. Decodieren Sie es und fügen Sie es Ihrem Wiedergabepuffer an.

{ "type": "audio.delta", "delta": "<base64 audio>" }
{ "type": "audio.done", "trace_id": "trace-uuid" }

Das audio.done-Ereignis markiert das Ende der Synthese. Die trace_id ist die Identifikationsnummer, die Sie dem Support zur Verfügung stellen oder in Ihren Protokollen erfassen sollten, wenn eine Generierung fehlerhaft verläuft. Ist der Text ungültig oder haben Sie Ihr Kontingent überschritten, erhalten Sie stattdessen eine Fehlermeldung.

{ "type": "error", "message": "description of the error" }

Eine vollständige Implementierung

Das folgende Beispiel teilt einen langen Text in Absätze auf, sendet diese nacheinander und montiert die empfangenen Audiofragmente zu einer MP3-Datei.

const WebSocket = require("ws");
const fs = require("fs");

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3",
  { headers: { "Authorization": "Bearer " + process.env.XAI_API_KEY } }
);

const audioChunks = [];

ws.on("open", () => {
  const paragraphs = longText.split("\n\n");
  for (const para of paragraphs) {
    ws.send(JSON.stringify({
      type: "text.delta",
      delta: para + " "
    }));
  }
  ws.send(JSON.stringify({ type: "text.done" }));
});

ws.on("message", (data) => {
  const msg = JSON.parse(data);
  if (msg.type === "audio.delta") {
    audioChunks.push(Buffer.from(msg.delta, "base64"));
  } else if (msg.type === "audio.done") {
    fs.writeFileSync("output.mp3", Buffer.concat(audioChunks));
    ws.close();
  }
});

Achten Sie auf para + " ": Ohne diesen Leerzeichen würde das Ende eines Absatzes direkt in den Anfang des nächsten übergehen, und die Engine würde die beiden Wörter zusammen lesen, ohne eine Pausenatmung.

Wichtige Grenzen

MetrikWert
Text pro DeltaMaximal 60.000 Zeichen
Gesamter TextUnbegrenzt
Gleichzeitige Sitzungen50 pro Team
Sitzungs-Genehmigung600 Sekunden
Verbindungs-TimeoutKein Timeout

Die xAI-Seite gibt an, dass die Verbindung keinen Timeout hat, und erwähnt separat eine „Sitzungs-Genehmigung” von 600 Sekunden, ohne zu erklären, was passiert, wenn diese abläuft. Um auf der sicheren Seite zu sein, verbinden Sie sich, wenn Sie Text zum Senden haben, nicht wenn die Seite lädt, und planen Sie Neuanbindungen vor. Gehen Sie mit dem Limit von 50 gleichzeitigen Sitzungen pro Team genauso vor: Eine Audiobibliothek, die im Hintergrund ihren Katalog konvertiert, sollte ihre Aufgaben in einer Warteschlange anordnen, statt zweihundert Verbindungen parallel zu öffnen.

HTTP oder WebSocket

Der HTTP-Modus bleibt die richtige Wahl für kurze Texte, einmalige Generierungen und überall, wo die Einfachheit der Integration am wichtigsten ist: eine Anfrage, eine Antwort, kein Zustand zu verwalten. Der WebSocket-Modus ist der richtige Weg, sobald der Text lang wird, wenn das Audio während der Erstellung abgespielt werden muss oder wenn der Inhalt selbst als Stream ankommt, typischerweise als Ausgabe eines Sprachmodells, das Sie während der Generierung vorlesen.

Kernaussagen

  • WebSocket-TTS ermöglicht es Ihnen, gestreamtes Audio zu empfangen, ohne auf das Ende der Generierung warten zu müssen.
  • Konfigurationsparameter werden in der Abfragezeichenfolge der Verbindungs-URL platziert.
  • Das Protokoll ist einfach: text.delta zum Senden von Text, audio.delta zum Empfangen von Audio.
  • WebSocket-Sitzungen sind auf 50 gleichzeitige pro Team begrenzt; planen Sie Neuanbindungen vor.
  • Bevorzugen Sie WebSocket für lange Texte und Echtzeit-Hör-Erlebnisse.