WebSocket-berichten: tekst en audio
Op deze pagina
Bijgewerkt op 3 november 2026, gebaseerd op de xAI-pagina Text to Speech: delta’s tot 60.000 tekens, annulering (
text.clear,audio.clear) en de uitspraaktabel (session.update,session.updated). Bron: Text to Speech.
Het TTS-berichtprotocol
Zodra de WebSocket-verbinding tot stand is gebracht, verloopt de communicatie via de uitwisseling van JSON-berichten. U verzendt tekst en de server antwoordt met base64-gecodeerde audio. Inzicht in dit protocol is essentieel voor een correcte implementatie van TTS-streaming.
Berichten van client naar server
Uw applicatie verzendt vier soorten berichten naar de server: text.delta en text.done voor tekst, text.clear om te annuleren, en session.update om te configureren.
text.delta: een tekstfragment verzenden
Het bericht text.delta verzendt een fragment van de te converteren tekst. U kunt de tekst in opeenvolgende stukken verzenden:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Elke delta kan maximaal 60.000 tekens bevatten, terwijl er geen limiet is op de totale tekstlengte. De server begint met het genereren van audio zodra er voldoende context is voor een natuurlijke uitspraak.
text.done: het einde van de tekst signaleren
Het bericht text.done informeert de server dat u klaar bent met het verzenden van tekst voor deze reeks:
{"type": "text.done"}
Zodra de server dit bericht ontvangt, voltooit deze de audiogeneratie en verzendt een audio.done-bericht. Vervolgens kunt u nieuwe delta’s starten voor een volgende reeks.
text.clear: de huidige reeks annuleren
text.clear annuleert de huidige reeks: de server stopt met het genereren van audio, verwijdert de gegevens uit het geheugen en antwoordt met audio.clear. De verbinding is direct weer gereed voor de volgende reeks, zonder nieuwe WebSocket-handshake; xAI schat de besparing voor een externe client op ongeveer 600 ms. Dit is het interruptiemechanisme (“barge-in”) voor wanneer de gebruiker onderbreekt.
{"type": "text.clear"}
session.update: uitspraak corrigeren
session.update installeert of vervangt de replace-tabel van de verbinding: elke zin die in de tekst wordt gevonden, wordt vervangen door de gesproken vorm vóór de synthese, zonder dat de verzonden tekst of het aantal gefactureerde tekens verandert. Verzend dit bericht vóór de eerste text.delta zodat het de hele verbinding bestrijkt; een update die midden in een reeks wordt ontvangen, geldt pas vanaf de volgende reeks.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Berichten van server naar client
De server antwoordt met vijf soorten berichten: audio.delta, audio.done en error (hieronder toegelicht), plus audio.clear ter bevestiging van een annulering, en session.updated dat de actieve replace-tabel retourneert.
audio.delta: een audiofragment
Het bericht audio.delta bevat een base64-gecodeerd audiofragment:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Elke delta is een geldig audiofragment dat u direct kunt decoderen en afspelen. Delta’s arriveren naarmate de generatie vordert.
audio.done: generatie voltooid
Het bericht audio.done geeft aan dat alle audio voor de verzonden tekstreeks is gegenereerd:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
De trace_id is een unieke ID voor de reeks, nuttig voor debugging en tracking.
error: er is een fout opgetreden
Als er iets misgaat, verzendt de server een foutbericht:
{
"type": "error",
"message": "Invalid text encoding"
}
De volledige communicatiestroom
Zo ziet een typische sessie eruit:
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 ----------------|
De server kan audio.delta-berichten verzenden nog voordat u text.done hebt gestuurd. Dat is precies het idee van streaming: de generatie start zo snel mogelijk.
Volledige implementatie 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:
# Verzend de tekst in stukken van 2.000 tekens
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
}))
# Signaleer het einde van de tekst
await ws.send(json.dumps({"type": "text.done"}))
# Ontvang de audiofragmenten
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"Generation finished (trace: {data['trace_id']})")
break
elif data["type"] == "error":
raise Exception(f"TTS error: {data['message']}")
# Stel de volledige audio samen
return b"".join(audio_chunks)
Implementatie 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", () => {
// Verzend de tekst
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);
});
}
Omgaan met meerdere delta’s
Voor tekst die progressief wordt gegenereerd (bijvoorbeeld de output van een LLM), verzendt u elke token direct naar de 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"}))
Deze architectuur, waarbij een streaming LLM wordt gekoppeld aan streaming TTS, biedt de laagst mogelijke latentie: de gebruiker hoort het antwoord terwijl de LLM nog bezig is met genereren.
Belangrijkste punten
- Vier clientberichten:
text.delta(tekst verzenden),text.done(einde tekst),text.clear(annuleren) ensession.update(replace-tabel) - Vijf serverberichten:
audio.delta(audiofragment),audio.done(einde),audio.clear(annulering bevestigd),session.updatedenerror - Audio is base64-gecodeerd in
audio.delta-berichten - De server start met genereren voordat
text.doneis ontvangen - Elke tekstdelta is beperkt tot 60.000 tekens
- Het koppelen van een streaming LLM aan streaming TTS resulteert in de laagste latentie