WebSocket-beskeder: tekst og lyd
På denne side
Opdateret 3. november 2026 baseret på xAI-siden Text to Speech: deltas på op til 60.000 tegn, annullering (
text.clear,audio.clear) og udtalestabellen (session.update,session.updated). Kilde: Text to Speech.
TTS-beskedprotokollen
Når WebSocket-forbindelsen er åben, foregår kommunikationen ved udveksling af JSON-beskeder. Du sender tekst, og serveren svarer med base64-kodet lyd. Det er afgørende at forstå denne protokol for at kunne implementere TTS-streaming korrekt.
Beskeder fra klient til server
Din app sender fire typer beskeder til serveren: text.delta og text.done til tekst, text.clear til annullering og session.update til konfiguration.
text.delta: send et tekststykke
Beskeden text.delta sender et fragment af tekst, der skal konverteres. Du kan sende teksten i successive bidder:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Hver delta kan indeholde op til 60.000 tegn, og den samlede tekst har ingen begrænsning. Serveren begynder at generere lyd, så snart den har nok kontekst til at producere naturlig udtale.
text.done: signalér slutningen på teksten
Beskeden text.done fortæller serveren, at du er færdig med at sende tekst til denne sekvens:
{"type": "text.done"}
Når serveren modtager denne besked, færdiggør den lydgenereringen og sender en audio.done-besked. Derefter kan du begynde at sende nye deltas til en ny sekvens.
text.clear: annullér den aktuelle sekvens
text.clear annullerer den aktuelle sekvens: serveren stopper lydgenereringen, kasserer det, den havde i hukommelsen, og svarer med audio.clear. Forbindelsen er straks klar til næste sekvens uden nyt WebSocket-håndtryk; xAI estimerer besparelsen til ca. 600 ms for en fjern klient. Det er interruptionsmekanismen („barge-in”), når brugeren afbryder.
{"type": "text.clear"}
session.update: ret udtalen
session.update installerer eller erstatter forbindelsens replace-tabel: hver frase, der findes i teksten, byttes ud med sin talte form før syntesen, uden at ændre teksten, du sender, eller antallet af tegn, du bliver faktureret for. Send den før den første text.delta, så den dækker hele forbindelsen; en opdatering, der modtages midt i en sekvens, gælder først fra næste sekvens.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Beskeder fra server til klient
Serveren svarer med fem typer beskeder: audio.delta, audio.done og error, som er beskrevet nedenfor, plus audio.clear, der bekræfter en annullering, og session.updated, der returnerer den gældende replace-tabel.
audio.delta: et lydstykke
Beskeden audio.delta indeholder et base64-kodet lydfragment:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Hver delta er et gyldigt lydstykke, du kan dekodede og afspille med det samme. Deltas ankommer, efterhånden som genereringen skrider frem.
audio.done: generering afsluttet
Beskeden audio.done signalerer, at al lyd for den tekstsekvens, du har sendt, er genereret:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
trace_id er et unikt ID for sekvensen, hvilket er nyttigt til fejlfinding og sporing.
error: der opstod en fejl
Hvis noget går galt, sender serveren en fejlbesked:
{
"type": "error",
"message": "Invalid text encoding"
}
Den fulde kommunikationsflow
Sådan ser en typisk session ud:
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 ----------------|
Serveren kan begynde at sende audio.delta-beskeder, før du overhovedet har sendt text.done. Det er hele idéen med streaming: genereringen starter så hurtigt som muligt.
Komplet implementation i 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:
# Send teksten i bidder på 2.000 tegn
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
}))
# Signalér slutningen på teksten
await ws.send(json.dumps({"type": "text.done"}))
# Modtag lydbidderne
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']}")
# Saml den komplette lyd
return b"".join(audio_chunks)
Implementation i 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", () => {
// Send teksten
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);
});
}
Håndtering af mange deltas
For tekst, der genereres progressivt (f.eks. output fra en LLM), skal du sende hvert token direkte til TTS-WebSocket’en:
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"}))
Denne arkitektur, der kæder en streaming-LLM sammen med streaming-TTS, giver den lavest mulige latency: brugeren hører svaret, mens LLM’en stadig genererer.
Vigtige pointer
- Fire klientbeskeder:
text.delta(send tekst),text.done(slut på tekst),text.clear(annullér) ogsession.update(replace-tabel) - Fem serverbeskeder:
audio.delta(et lydstykke),audio.done(slut),audio.clear(annullering bekræftet),session.updatedogerror - Lyd er base64-kodet i
audio.delta-beskeder - Serveren begynder at generere, før den modtager
text.done - Hver tekst-delta er begrænset til 60.000 tegn
- Kædning af en streaming-LLM ind i streaming-TTS giver den laveste latency