WebSocketi sõnumid: tekst ja heli
Sellel lehel
Uuendatud 3. novembril 2026, tuginedes xAI Text to Speech lehele: deltad kuni 60 000 tähemärki, tühistamine (
text.clear,audio.clear) ja hääldustabel (session.update,session.updated). Allikas: Text to Speech.
TTSi sõnumiprotokoll
Kui WebSocketi ühendus on avatud, toimub suhtlus JSON-sõnumite vahetamise teel. Sa saadad teksti ja server vastab base64-kodeeritud heliga. Selle protokolli mõistmine on hädavajalik TTSi voogedastuse korrektseks rakendamiseks.
Kliendilt serverile sõnumid
Sinu rakendus saadab serverile nelja tüüpi sõnumeid: text.delta ja text.done teksti jaoks, text.clear tühistamiseks ning session.update seadistamiseks.
text.delta: tekstiosa saatmine
Sõnum text.delta saadab serverile teisendamiseks tekstifragmendi. Saad teksti saata järjestikuste tükkidena:
{"type": "text.delta", "delta": "Tere tulemast "}
{"type": "text.delta", "delta": "meie kõnesünteesi esitlusele."}
Iga delta võib sisaldada kuni 60 000 tähemärki ja kogu tekstil pole pikkusepiirangut. Server alustab heli genereerimist niipea, kui tal on loomuliku häälduse jaoks piisavalt konteksti.
text.done: teksti lõpu märkimine
Sõnum text.done annab serverile teada, et oled selle jada jaoks teksti saatmise lõpetanud:
{"type": "text.done"}
Kui server selle sõnumi kätte saab, lõpetab ta heli genereerimise ja saadab sõnumi audio.done. Seejärel saad alustada uute deltade saatmist uue jada jaoks.
text.clear: praeguse jada tühistamine
text.clear tühistab praeguse jada: server lõpetab heli genereerimise, kustutab mälus oleva ja vastab sõnumiga audio.clear. Ühendus on koheselt valmis järgmiseks jadaks, ilma uue WebSocketi käepigistuseta; xAI hinnangul säästab see kaugel asuva kliendi puhul umbes 600 ms. See on katkestusmehhanism („barge-in“) juhuks, kui kasutaja sekeldab vahele.
{"type": "text.clear"}
session.update: häälduse parandamine
session.update paigaldab või asendab ühenduse replace-tabeli: iga tekstist leitud fraas asendatakse enne sünteesi selle kõnevormiga, muutmata sinu saadetud teksti ega arveldatavate tähemärkide arvu. Saada see enne esimest text.delta, et see hõlmaks kogu ühendust; keset jada saabunud värskendus kehtib alles järgmisest jadast alates.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Serverilt kliendile sõnumid
Server vastab viie tüüpi sõnumitega: audio.delta, audio.done ja error (kirjeldatud allpool), lisaks audio.clear, mis kinnitab tühistamist, ja session.updated, mis tagastab kehtiva replace-tabeli.
audio.delta: heliosa
Sõnum audio.delta sisaldab base64-kodeeritud helifragmenti:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Iga delta on kehtiv helitükk, mille saad kohe dekodeerida ja esitada. Deltad saabuvad genereerimise käigus.
audio.done: genereerimine lõpetatud
Sõnum audio.done annab märku, et kogu sinu saadetud tekstijada jaoks mõeldud heli on genereeritud:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
trace_id on jada unikaalne ID, mis on kasulik silumiseks ja jälgimiseks.
error: tekkinud viga
Kui midagi läheb valesti, saadab server veateate:
{
"type": "error",
"message": "Invalid text encoding"
}
Täielik suhtlusvoog
Nii näeb välja tüüpiline seanss:
Klient Server
| |
|-- text.delta ("Tere, ") ----->|
|-- text.delta ("kuidas läheb ") ---->|
|-- text.delta ("sul?") -------->|
|<-- audio.delta (tükk 1) -----|
|<-- audio.delta (tükk 2) -----|
|-- text.done ----------------->|
|<-- audio.delta (tükk 3) -----|
|<-- audio.done ----------------|
Server võib hakata saatma sõnumeid audio.delta enne, kui oled isegi saatnud text.done. See ongi voogedastuse mõte: genereerimine algab nii kiiresti kui võimalik.
Täielik rakendus Pythonis
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:
# Saada tekst 2000 tähemärgi kaupa
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
}))
# Märgi teksti lõpp
await ws.send(json.dumps({"type": "text.done"}))
# Võta vastu helitükid
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"Genereerimine lõpetatud (jälg: {data['trace_id']})")
break
elif data["type"] == "error":
raise Exception(f"TTSi viga: {data['message']}")
# Koosta täielik helifail
return b"".join(audio_chunks)
Rakendus JavaScriptis (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", () => {
// Saada 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);
});
}
Mitme delta haldamine
Järk-järgult genereeritava teksti (näiteks LLM-i väljundi) korral saada iga token otse TTSi WebSocketisse:
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"}))
See „voogedastatava LLM-i ühendamine voogedastatava TTSiga“ arhitektuur pakub võimalikult väikest latentsust: kasutaja kuuleb vastust samal ajal, kui LLM seda veel genereerib.
Peamised punktid
- Neli kliendi sõnumit:
text.delta(saada tekst),text.done(teksti lõpp),text.clear(tühistamine) jasession.update(replace-tabel) - Viis serveri sõnumit:
audio.delta(heliosa),audio.done(lõpp),audio.clear(tühistamine kinnitatud),session.updatedjaerror - Heli on sõnumites
audio.deltabase64-kodeeritud - Server alustab genereerimist enne, kui saab sõnumi
text.done - Iga tekstidelta on piiratud 60 000 tähemärgiga
- Voogedastatava LLM-i ühendamine voogedastatava TTSiga annab väikseima latentsuse