WebSocket-üzenetek: szöveg és hang
Ezen az oldalon
Frissítve: 2026. november 3., az xAI Text to Speech oldala alapján: legfeljebb 60 000 karakteres delták, megszakítás (
text.clear,audio.clear) és kiejtési tábla (session.update,session.updated). Forrás: Text to Speech.
A TTS üzenetprotokoll
Miután a WebSocket-kapcsolat létrejött, a kommunikáció JSON-üzenetek cseréjével zajlik. Te küldesz szöveget, a szerver pedig base64-kódolt hanggal válaszol. Ennek a protokollnak a megértése elengedhetetlen a TTS-streamelés helyes megvalósításához.
Kliensről szerverre irányuló üzenetek
Az alkalmazásod négyféle üzenetet küld a szervernek: text.delta és text.done a szöveghez, text.clear a megszakításhoz, valamint session.update a konfiguráláshoz.
text.delta: szövegrész küldése
A text.delta üzenet egy átalakítandó szövegrészletet küld. A szöveget egymást követő darabokban is elküldheted:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Minden delta legfeljebb 60 000 karaktert tartalmazhat, míg a teljes szöveg hossza korlátlan. A szerver akkor kezdi el generálni a hangot, amint elegendő kontextusa van a természetes kiejtés biztosításához.
text.done: a szöveg végének jelzése
A text.done üzenet jelzi a szervernek, hogy befejezted a szöveg küldését ehhez a szekvenciához:
{"type": "text.done"}
Amint a szerver megkapja ezt az üzenetet, befejezi a hanggenerálást, és küld egy audio.done üzenetet. Ezt követően új deltákat kezdhetsz küldeni egy új szekvenciához.
text.clear: az aktuális szekvencia megszakítása
A text.clear megszakítja az aktuális szekvenciát: a szerver leállítja a hanggenerálást, eldobja a memóriában lévő adatokat, és audio.clear üzenettel válaszol. A kapcsolat azonnal készen áll a következő szekvenciára, új WebSocket-kézfogás nélkül; az xAI szerint ez távoli kliensek esetén kb. 600 ms megtakarítást jelent. Ez a megszakítási („barge-in“) mechanizmus arra az esetre, amikor a felhasználó közbeszól.
{"type": "text.clear"}
session.update: kiejtés javítása
A session.update telepíti vagy lecseréli a kapcsolat replace táblázatát: minden olyan kifejezést, amely szerepel a szövegben, a rendszer lecserél a beszélt alakjára szintézis előtt, anélkül, hogy megváltoztatná az elküldött szöveget vagy a számlázott karakterek számát. Küldd el az első text.delta előtt, hogy az egész kapcsolatra vonatkozzon; a szekvencia közben érkezett frissítés csak a következő szekvenciától lép életbe.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Szerverről kliensre irányuló üzenetek
A szerver ötféle üzenettel válaszol: audio.delta, audio.done és error (ezeket lentebb részletezzük), valamint audio.clear, amely megerősíti a megszakítást, illetve session.updated, amely visszaadja az érvényes replace táblázatot.
audio.delta: hangrészlet
Az audio.delta üzenet egy base64-kódolt hangrészletet tartalmaz:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Minden delta egy érvényes hangrészlet, amelyet azonnal dekódolhatsz és lejátszhatsz. A delták a generálás előrehaladtával érkeznek.
audio.done: a generálás befejeződött
Az audio.done üzenet jelzi, hogy az elküldött szövegszekvencia összes hangja elkészült:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
A trace_id a szekvencia egyedi azonosítója, amely hibakereséshez és nyomon követéshez hasznos.
error: hiba történt
Ha valami hiba történik, a szerver hibaüzenetet küld:
{
"type": "error",
"message": "Invalid text encoding"
}
A teljes kommunikációs folyamat
Így néz ki egy tipikus munkamenet:
Kliens Szerver
| |
|-- text.delta ("Hello, ") ----->|
|-- text.delta ("how are ") ---->|
|-- text.delta ("you?") -------->|
|<-- audio.delta (1. rész) -----|
|<-- audio.delta (2. rész) -----|
|-- text.done ----------------->|
|<-- audio.delta (3. rész) -----|
|<-- audio.done ----------------|
A szerver már akkor is elkezdheti az audio.delta üzenetek küldését, mielőtt még elküldenéd a text.done üzenetet. Ez a streamelés lényege: a generálás a lehető legkorábban elindul.
Teljes megvalósítás Pythonban
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:
# Szöveg küldése 2000 karakteres darabokban
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
}))
# Szöveg végének jelzése
await ws.send(json.dumps({"type": "text.done"}))
# Hangrészek fogadása
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"Generálás befejeződött (trace: {data['trace_id']})")
break
elif data["type"] == "error":
raise Exception(f"TTS hiba: {data['message']}")
# Teljes hang összeállítása
return b"".join(audio_chunks)
Megvalósítás JavaScriptben (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", () => {
// Szöveg küldése
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);
});
}
Több delta kezelése
Folyamatosan generált szöveg (például egy LLM kimenete) esetén minden tokent azonnal küldj el a TTS WebSocketnek:
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"}))
Ez a „streamelt LLM streamelt TTS-be“ architektúra biztosítja a lehető legalacsonyabb késleltetést: a felhasználó már akkor hallja a választ, amikor az LLM még mindig generál.
Főbb megállapítások
- Négy kliensüzenet:
text.delta(szöveg küldése),text.done(szöveg vége),text.clear(megszakítás) éssession.update(replacetábla) - Öt szerverüzenet:
audio.delta(hangrészlet),audio.done(vége),audio.clear(megszakítás megerősítve),session.updatedéserror - A hang base64-kódolva érkezik az
audio.deltaüzenetekben - A szerver a
text.donefogadása előtt elkezdi a generálást - Minden szövegdelta legfeljebb 60 000 karakter lehet
- Egy streamelt LLM láncolása egy streamelt TTS-hez adja a legalacsonyabb késleltetést