WebSocket-Nachrichten: Text und Audio
Auf dieser Seite
Aktualisiert am 3. November 2026, basierend auf der xAI-Seite Text to Speech: Deltas von bis zu 60.000 Zeichen, Abbruch (
text.clear,audio.clear) und die Aussprachetabelle (session.update,session.updated). Quelle: Text to Speech.
Das TTS-Nachrichtenprotokoll
Sobald die WebSocket-Verbindung geöffnet ist, erfolgt die Kommunikation durch den Austausch von JSON-Nachrichten. Sie senden Text, und der Server antwortet mit base64-kodiertem Audio. Das Verständnis dieses Protokolls ist unerlässlich, um die TTS-Streaming-Funktion korrekt zu implementieren.
Client-zu-Server-Nachrichten
Ihre Anwendung sendet vier Arten von Nachrichten an den Server: text.delta und text.done für Text, text.clear zum Abbrechen und session.update zur Konfiguration.
text.delta: Senden eines Textfragments
Die Nachricht text.delta sendet ein Textfragment zur Umwandlung. Sie können den Text in aufeinanderfolgenden Stücken senden:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Jedes Delta kann bis zu 60.000 Zeichen enthalten, und der gesamte Text hat keine Obergrenze. Der Server beginnt mit der Audioerzeugung, sobald er genügend Kontext für eine natürliche Aussprache hat.
text.done: Signalisieren des Textendes
Die Nachricht text.done informiert den Server, dass Sie das Senden des Textes für diese Sequenz abgeschlossen haben:
{"type": "text.done"}
Sobald dieser empfangen wird, beendet der Server die Audioerzeugung und sendet eine audio.done-Nachricht. Anschließend können Sie neue Deltas für eine neue Sequenz senden.
text.clear: Abbrechen der aktuellen Sequenz
text.clear bricht die aktuelle Sequenz ab: Der Server stoppt die Audioerzeugung, löscht den im Speicher gehaltenen Inhalt und antwortet mit audio.clear. Die Verbindung ist sofort bereit für die nächste Sequenz, ohne dass ein neuer WebSocket-Handshake erforderlich ist; xAI veranschlagt die Ersparnis bei etwa 600 ms für einen entfernten Client. Es handelt sich um den Unterbrechungsmechanismus („Barge-in”), wenn der Nutzer einbricht.
{"type": "text.clear"}
session.update: Aussprache korrigieren
session.update installiert oder ersetzt die replace-Tabelle der Verbindung: Jeder im Text gefundene Ausdruck wird vor der Synthese durch seine gesprochene Form ersetzt, ohne den gesendeten Text oder die Anzahl der abgerechneten Zeichen zu ändern. Senden Sie diese Nachricht vor dem ersten text.delta, damit sie die gesamte Verbindung abdeckt; ein Update, das während einer Sequenz empfangen wird, gilt erst ab der nächsten Sequenz.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Server-zu-Client-Nachrichten
Der Server antwortet mit fünf Arten von Nachrichten: audio.delta, audio.done und error, die unten detailliert beschrieben sind, sowie audio.clear, das eine Abbruchbestätigung darstellt, und session.updated, das die gültige replace-Tabelle zurückgibt.
audio.delta: Ein Audiofragment
Die Nachricht audio.delta enthält ein base64-kodiertes Audiofragment:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Jedes Delta ist ein gültiges Audiofragment, das sofort decodiert und abgespielt werden kann. Die Deltas eintreffen, während die Erzeugung fortschreitet.
audio.done: Erzeugung abgeschlossen
Die Nachricht audio.done signalisiert, dass das gesamte Audio für die von Ihnen gesendete Textsequenz erzeugt wurde:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
Die trace_id ist eine eindeutige Kennung für die Sequenz, die für die Fehlerbehebung und Verfolgung nützlich ist.
error: Ein Fehler ist aufgetreten
Wenn etwas schiefgeht, sendet der Server eine Fehlermeldung:
{
"type": "error",
"message": "Invalid text encoding"
}
Der vollständige Kommunikationsablauf
So verläuft eine typische Sitzung:
Client Server
| |
|-- text.delta ("Hello, ") ----->|
|-- text.delta ("how are ") ---->|
|-- text.delta ("you?") -------->|
|<-- audio.delta (Chunk 1) -----|
|<-- audio.delta (Chunk 2) -----|
|-- text.done ----------------->|
|<-- audio.delta (Chunk 3) -----|
|<-- audio.done ----------------|
Der Server kann audio.delta-Nachrichten senden, bevor Sie text.done gesendet haben. Das ist der Kern des Streamings: Die Erzeugung beginnt so früh wie möglich.
Komplexe Implementierung in Python
import asyncio
import websockets
import json
import base64
async def stream_tts(api_key, text, voice="eve", language="en"):
uri = f"wss://api.x.ai/v1/tts?language={language}&voice={voice}&codec=mp3"
headers = {"Authorization": f"Bearer {api_key}"}
audio_chunks = []
async with websockets.connect(uri, additional_headers=headers) as ws:
# Senden des Textes in Blöcken von 2.000 Zeichen
chunk_size = 2000
for i in range(0, len(text), chunk_size):
chunk = text[i:i + chunk_size]
await ws.send(json.dumps({
"type": "text.delta",
"delta": chunk
}))
# Signalisieren des Textendes
await ws.send(json.dumps({"type": "text.done"}))
# Empfangen der Audiofragmente
async for message in ws:
data = json.loads(message)
if data["type"] == "audio.delta":
audio_bytes = base64.b64decode(data["delta"])
audio_chunks.append(audio_bytes)
elif data["type"] == "audio.done":
print(f"Erzeugung abgeschlossen (Trace: {data['trace_id']})")
break
elif data["type"] == "error":
raise Exception(f"TTS-Fehler: {data['message']}")
# Zusammenfügen des vollständigen Audios
return b"".join(audio_chunks)
Implementierung in JavaScript (Node.js)
const WebSocket = require("ws");
function streamTTS(apiKey, text, voice = "eve", language = "en") {
return new Promise((resolve, reject) => {
const ws = new WebSocket(
`wss://api.x.ai/v1/tts?language=${language}&voice=${voice}&codec=mp3`,
{ headers: { Authorization: `Bearer ${apiKey}` } }
);
const audioChunks = [];
ws.on("open", () => {
// Senden des Textes
ws.send(JSON.stringify({ type: "text.delta", delta: text }));
ws.send(JSON.stringify({ type: "text.done" }));
});
ws.on("message", (raw) => {
const data = JSON.parse(raw);
if (data.type === "audio.delta") {
audioChunks.push(Buffer.from(data.delta, "base64"));
} else if (data.type === "audio.done") {
ws.close();
resolve(Buffer.concat(audioChunks));
} else if (data.type === "error") {
ws.close();
reject(new Error(data.message));
}
});
ws.on("error", reject);
});
}
Umgang mit vielen Deltas
Für progressiv generierten Text (z. B. die Ausgabe eines LLM) senden Sie jedes Token direkt an den TTS-WebSocket:
async def llm_to_speech(ws_tts, llm_stream):
async for token in llm_stream:
await ws_tts.send(json.dumps({
"type": "text.delta",
"delta": token
}))
await ws_tts.send(json.dumps({"type": "text.done"}))
Diese Architektur „Streaming-LLM in Streaming-TTS” bietet die geringstmögliche Latenz: Der Nutzer hört die Antwort, während das LLM noch generiert.
Kernaussagen
- Vier Client-Nachrichten:
text.delta(Text senden),text.done(Textende),text.clear(Abbrechen) undsession.update(replace-Tabelle) - Fünf Server-Nachrichten:
audio.delta(ein Audiofragment),audio.done(Ende),audio.clear(Abbruch bestätigt),session.updatedunderror - Audio ist in
audio.delta-Nachrichten base64-kodiert - Der Server beginnt mit der Erzeugung, bevor er
text.doneerhält - Jedes Text-Delta ist auf 60.000 Zeichen begrenzt
- Die Verkettung eines Streaming-LLM mit Streaming-TTS ergibt die geringste Latenz