WebSocket-meddelanden: text och ljud
På denna sida
Uppdaterat den 3 november 2026, baserat på xAI:s sida Text to Speech: deltar (deltas) på upp till 60 000 tecken, avbrytning (
text.clear,audio.clear) och uttalstabellen (session.update,session.updated). Källa: Text to Speech.
TTS-meddelandeprotokollet
När WebSocket-anslutningen är öppen sker kommunikationen genom utbyte av JSON-meddelanden. Du skickar text och servern svarar med ljud kodat i base64. Att förstå detta protokoll är avgörande för att implementera TTS-streaming korrekt.
Meddelanden från klient till server
Din app skickar fyra typer av meddelanden till servern: text.delta och text.done för text, text.clear för att avbryta, samt session.update för konfiguration.
text.delta: skicka en textbit
Meddelandet text.delta skickar en textfragment för konvertering. Du kan skicka texten i successiva bitar:
{"type": "text.delta", "delta": "Hej, och välkommen till "}
{"type": "text.delta", "delta": "vår presentation om talgenerering."}
Varje delta kan innehålla upp till 60 000 tecken, och den totala textmängden har ingen begränsning. Servern börjar generera ljud så snart den har tillräckligt med kontext för att producera ett naturligt uttal.
text.done: signalera slutet på texten
Meddelandet text.done talar om för servern att du har slutat skicka text för denna sekvens:
{"type": "text.done"}
När servern tar emot detta meddelande avslutar den ljudgenereringen och skickar ett meddelande audio.done. Därefter kan du börja skicka nya deltar för en ny sekvens.
text.clear: avbryt den aktuella sekvensen
text.clear avbryter den aktuella sekvensen: servern slutar generera ljud, kasserar det den hade i minnet och svarar med audio.clear. Anslutningen är omedelbart redo för nästa sekvens utan någon ny WebSocket-handskakning; xAI uppskattar besparingen till cirka 600 ms för en klient på avstånd. Det är mekanismen för avbrott (“barge-in”) när användaren avbryter.
{"type": "text.clear"}
session.update: korrigera uttal
session.update installerar eller ersätter anslutningens replace-tabell: varje fras som hittas i texten byts ut mot sitt talade format innan syntes, utan att ändra texten du skickar eller antalet tecken du debiteras för. Skicka det före den första text.delta så att det täcker hela anslutningen; en uppdatering som tas emot mitt i en sekvens gäller först från nästa sekvens.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Meddelanden från server till klient
Servern svarar med fem typer av meddelanden: audio.delta, audio.done och error, som beskrivs nedan, plus audio.clear som bekräftar ett avbrott, och session.updated som returnerar den gällande replace-tabellen.
audio.delta: en ljudbit
Meddelandet audio.delta innehåller en ljudfragment kodad i base64:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Varje delta är en giltig ljudbit som du kan dekoda och spela upp direkt. Deltar anländer i takt med att genereringen fortskrider.
audio.done: genereringen avslutad
Meddelandet audio.done signalerar att allt ljud för textsekvensen du skickat har genererats:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
trace_id är ett unikt ID för sekvensen, användbart för felsökning och spårning.
error: ett fel har inträffat
Om något går fel skickar servern ett felmeddelande:
{
"type": "error",
"message": "Invalid text encoding"
}
Det fullständiga kommunikationsflödet
Så här ser en typisk session ut:
Klient Server
| |
|-- text.delta ("Hej, ") ------->|
|-- text.delta ("hur mår ") ---->|
|-- text.delta ("du?") --------->|
|<-- audio.delta (bit 1) --------|
|<-- audio.delta (bit 2) --------|
|-- text.done ------------------>|
|<-- audio.delta (bit 3) --------|
|<-- audio.done -----------------|
Servern kan börja skicka audio.delta-meddelanden innan du ens har skickat text.done. Det är hela poängen med streaming: genereringen startar så snart som möjligt.
Fullständig 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:
# Skicka texten i bitar om 2 000 tecken
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
}))
# Signalera slutet på texten
await ws.send(json.dumps({"type": "text.done"}))
# Ta emot ljudbitarna
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"Generering avslutad (spårning: {data['trace_id']})")
break
elif data["type"] == "error":
raise Exception(f"TTS-fel: {data['message']}")
# Sammanställ det kompletta ljudet
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", () => {
// Skicka texten
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);
});
}
Hantering av många deltar
För text som genereras progressivt (till exempel utdata från en LLM), skickar du varje token direkt till TTS-WebSocketen:
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"}))
Denna arkitektur, “streaming LLM in i streaming TTS”, erbjuder den lägsta möjliga latensen: användaren hör svaret medan LLM:n fortfarande genererar.
Viktiga punkter
- Fyra klientmeddelanden:
text.delta(skicka text),text.done(slut på text),text.clear(avbryt) ochsession.update(replace-tabell) - Fem servermeddelanden:
audio.delta(en ljudbit),audio.done(slut),audio.clear(avbrott bekräftat),session.updatedocherror - Ljudet är base64-kodat i
audio.delta-meddelanden - Servern börjar generera innan den tar emot
text.done - Varje textdelta är begränsat till 60 000 tecken
- Att koppla en streaming-LLM till en streaming-TTS ger lägst latens