Ziņojumi WebSocket: teksts un audio
Šajā lapā
Atjaunināts 2026. gada 3. novembrī, pamatojoties uz xAI Text to Speech lapu: deltas līdz 60 000 rakstzīmēm, atcelšana (
text.clear,audio.clear) un izrunas tabula (session.update,session.updated). Avots: Text to Speech.
TTS ziņojumu protokols
Kad WebSocket savienojums ir atvērts, komunikācija notiek, apmainoties ar JSON ziņojumiem. Tu sūti tekstu, un serveris atbild ar audio, kas kodēts base64 formātā. Šī protokola izpratne ir būtiska, lai pareizi ieviestu TTS straumēšanu.
Ziņojumi no klienta uz serveri
Tava lietotne serverim sūta četru veidu ziņojumus: text.delta un text.done tekstam, text.clear atcelšanai un session.update konfigurēšanai.
text.delta: teksta fragmenta sūtīšana
Ziņojums text.delta nosūta teksta fragmentu pārveidošanai. Tekstu vari sūtīt pa daļām:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Katrs deltas var saturēt līdz 60 000 rakstzīmēm, un kopējam tekstam nav limita. Serveris sāk ģenerēt audio tiklīdz tam ir pietiekami daudz konteksta, lai nodrošinātu dabisku izrunu.
text.done: teksta beigšanas signalizēšana
Ziņojums text.done informē serveri, ka esi pabeidzis sūtīt tekstu šai secībai:
{"type": "text.done"}
Saņemot šo ziņojumu, serveris pabeidz audio ģenerēšanu un nosūta ziņojumu audio.done. Pēc tam vari sākt sūtīt jaunus deltas jaunai secībai.
text.clear: pašreizējās secības atcelšana
text.clear atceļ pašreizējo secību: serveris pārtrauc audio ģenerēšanu, dzēš atmiņā esošo datus un atbild ar audio.clear. Savienojums ir nekavējoties gatavs nākamajai secībai bez jauna WebSocket rokas spiediena; xAI norāda, ka tas ietaupa aptuveni 600 ms attālinātiem klientiem. Tas ir pārtraukšanas („barge-in”) mehānisms gadījumiem, kad lietotājs iejaucas.
{"type": "text.clear"}
session.update: izrunas labošana
session.update instalē vai aizstāj savienojuma replace tabulu: katrs tekstā atrastais teikums tiek nomainīts pret tā runāto formu pirms sintēzes, nemainot nosūtīto tekstu vai rakstzīmju skaitu, par kuru tiek rēķināts. Nosūti to pirms pirmā text.delta, lai tas attiektos uz visu savienojumu; atjauninājums, kas saņemts secības vidū, stājas spēkā tikai no nākamās secības.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Ziņojumi no servera uz klientu
Serveris atbild ar piecu veidu ziņojumiem: audio.delta, audio.done un error, kas detalizēti aprakstīti tālāk, kā arī audio.clear, kas apstiprina atcelšanu, un session.updated, kas atgriež spēkā esošo replace tabulu.
audio.delta: audio fragments
Ziņojums audio.delta satur audio fragmentu, kas kodēts base64 formātā:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Katrs deltas ir derīgs audio fragments, ko vari atkodēt un atskaņot uzreiz. Deltas tiek saņemti, noritot ģenerēšanai.
audio.done: ģenerēšana pabeigta
Ziņojums audio.done signalizē, ka viss audio nosūtītajai teksta secībai ir ģenerēts:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
trace_id ir unikāls secības ID, kas noderīgs atkļūdošanai un izsekošanai.
error: radusies kļūda
Ja kaut kas noiet greizi, serveris nosūta kļūdas ziņojumu:
{
"type": "error",
"message": "Invalid text encoding"
}
Pilna komunikācijas plūsma
Lūk, kā norisinās tipiska sesija:
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 ----------------|
Serveris var sākt sūtīt audio.delta ziņojumus pat pirms esi nosūtījis text.done. Tieši tāda ir straumēšanas jēga: ģenerēšana sākas pēc iespējas ātrāk.
Pilna implementācija valodā 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:
# Sūti tekstu pa 2000 rakstzīmju gabaliem
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
}))
# Signalizē teksta beigas
await ws.send(json.dumps({"type": "text.done"}))
# Saņem audio gabalus
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']}")
# Saliec kopā pilnu audio
return b"".join(audio_chunks)
Implementācija valodā 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", () => {
// Sūti tekstu
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);
});
}
Daudzu deltas apstrāde
Tekstam, kas tiek ģenerēts pakāpeniski (piemēram, LLM izeja), sūti katru tokeni tieši TTS WebSocket:
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"}))
Šī „straumējoša LLM uz straumējošu TTS” arhitektūra nodrošina viszemāko iespējamo latentumu: lietotājs dzird atbildi, kamēr LLM vēl ģenerē.
Galvenās atziņas
- Četri klienta ziņojumi:
text.delta(teksta sūtīšana),text.done(teksta beigas),text.clear(atcelšana) unsession.update(replacetabula) - Pieci servera ziņojumi:
audio.delta(audio fragments),audio.done(beigas),audio.clear(atcelšana apstiprināta),session.updatedunerror - Audio ir kodēts base64 formātā ziņojumos
audio.delta - Serveris sāk ģenerēšanu pirms saņem
text.done - Katrs teksta deltas ir ierobežots līdz 60 000 rakstzīmēm
- Straumējoša LLM ķēdēšana uz straumējošu TTS nodrošina viszemāko latentumu