Zprávy WebSocket: text a zvuk
Na této stránce
Aktualizováno 3. listopadu 2026 na základě stránky xAI Text to Speech: delty až do 60 000 znaků, zrušení (
text.clear,audio.clear) a tabulka výslovnosti (session.update,session.updated). Zdroj: Text to Speech.
Protokol zpráv TTS
Jakmile je připojení WebSocket otevřené, komunikace probíhá výměnou zpráv ve formátu JSON. Ty posíláš text a server odpovídá zvukem zakódovaným v base64. Pochopení tohoto protokolu je zásadní pro správnou implementaci streamování TTS.
Zprávy od klienta k serveru
Tvoje aplikace odesílá serveru čtyři typy zpráv: text.delta a text.done pro text, text.clear pro zrušení a session.update pro konfiguraci.
text.delta: odeslání části textu
Zpráva text.delta odešle fragment textu ke konverzi. Text můžeš posílat v postupných částech:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Každá delta může obsahovat až 60 000 znaků a celkový text nemá žádný limit. Server začne generovat zvuk, jakmile má dostatečný kontext pro vytvoření přirozené výslovnosti.
text.done: signalizace konce textu
Zpráva text.done sděluje serveru, že jsi pro tuto sekvenci dokončil odesílání textu:
{"type": "text.done"}
Jakmile server tuto zprávu obdrží, dokončí generování zvuku a odešle zprávu audio.done. Poté můžeš začít odesílat nové delty pro novou sekvenci.
text.clear: zrušení aktuální sekvence
text.clear zruší aktuální sekvenci: server přestane generovat zvuk, zahodí data v paměti a odpoví zprávou audio.clear. Připojení je okamžitě připraveno pro další sekvenci bez nutnosti nového handshake WebSocket; xAI odhaduje úsporu času na přibližně 600 ms pro vzdálené klienty. Jedná se o mechanismus přerušení („barge-in“) pro situace, kdy uživatel vstoupí do řeči.
{"type": "text.clear"}
session.update: oprava výslovnosti
session.update nainstaluje nebo nahradí tabulku replace pro připojení: každá fráze nalezená v textu je před syntézou nahrazena svou mluvenou formou, aniž by se změnil odesílaný text nebo počet znaků, za které se účtuje. Odešli ji před první zprávou text.delta, aby pokryla celé připojení; aktualizace přijatá uprostřed sekvence se projeví až od další sekvence.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Zprávy od serveru ke klientovi
Server odpovídá pěti typy zpráv: audio.delta, audio.done a error, které jsou podrobně popsány níže, dále audio.clear, který potvrzuje zrušení, a session.updated, který vrací aktivní tabulku replace.
audio.delta: část zvuku
Zpráva audio.delta obsahuje fragment zvuku zakódovaný v base64:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Každá delta je platnou částí zvuku, kterou můžeš okamžitě dekódovat a přehrát. Delty přicházejí v průběhu generování.
audio.done: generování dokončeno
Zpráva audio.done signalizuje, že byl vygenerován veškerý zvuk pro sekvenci textu, kterou jsi odeslal:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
trace_id je jedinečné ID pro sekvenci, užitečné pro ladění a sledování.
error: došlo k chybě
Pokud se něco pokazí, server odešle chybovou zprávu:
{
"type": "error",
"message": "Invalid text encoding"
}
Kompletní tok komunikace
Zde je průběh typické relace:
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 ----------------|
Server může začít odesílat zprávy audio.delta dříve, než vůbec odešleš text.done. To je celá podstata streamování: generování začíná co nejdříve.
Kompletní implementace v Pythonu
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:
# Odeslání textu po částech po 2 000 znacích
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
}))
# Signalizace konce textu
await ws.send(json.dumps({"type": "text.done"}))
# Příjem částí zvuku
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']}")
# Sestavení kompletního zvuku
return b"".join(audio_chunks)
Implementace v JavaScriptu (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", () => {
// Odeslání textu
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);
});
}
Zpracování mnoha delt
Pro text generovaný postupně (například výstup LLM) odešli každý token přímo do WebSocketu TTS:
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"}))
Tato architektura „streamování LLM do streamovaného TTS“ nabízí nejnižší možnou latenci: uživatel slyší odpověď, zatímco LLM stále generuje.
Klíčové poznatky
- Čtyři zprávy klienta:
text.delta(odeslání textu),text.done(konec textu),text.clear(zrušení) asession.update(tabulkareplace) - Pět zpráv serveru:
audio.delta(část zvuku),audio.done(konec),audio.clear(potvrzení zrušení),session.updatedaerror - Zvuk je ve zprávách
audio.deltazakódován v base64 - Server začne generovat dříve, než obdrží
text.done - Každá textová delta je omezena na 60 000 znaků
- Řetězení streamovaného LLM do streamovaného TTS poskytuje nejnižší latenci