Poruke WebSocketa: tekst i zvuk
Na ovoj stranici
Ažurirano 3. studenoga 2026., na temelju stranice xAI Text to Speech: delte do 60.000 znakova, otkazivanje (
text.clear,audio.clear) i tablica izgovora (session.update,session.updated). Izvor: Text to Speech.
Protokol poruka za TTS
Čim se WebSocket veza uspostavi, komunikacija funkcionira razmjenom JSON poruka. Ti šalješ tekst, a poslužitelj odgovara zvukom kodiranim u base64 formatu. Razumijevanje ovog protokola ključno je za ispravnu implementaciju strujanja TTS-a.
Poruke od klijenta prema poslužitelju
Tvoja aplikacija šalje četiri vrste poruka poslužitelju: text.delta i text.done za tekst, text.clear za otkazivanje te session.update za konfiguraciju.
text.delta: slanje dijela teksta
Poruka text.delta šalje fragment teksta na pretvorbu. Tekst možeš slati u uzastopnim dijelovima:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Svaka delta može sadržavati do 60.000 znakova, a ukupni tekst nema ograničenje. Poslužitelj počinje generirati zvuk čim ima dovoljno konteksta za prirodan izgovor.
text.done: signaliziranje kraja teksta
Poruka text.done obavještava poslužitelj da si završio slati tekst za ovaj slijed:
{"type": "text.done"}
Čim poslužitelj primi ovu poruku, dovršava generiranje zvuka i šalje poruku audio.done. Nakon toga možeš početi slati nove delte za novi slijed.
text.clear: otkazivanje trenutnog slijeda
text.clear otkazuje trenutni slijed: poslužitelj prestaje generirati zvuk, odbacuje ono što je imao u memoriji i odgovara s audio.clear. Veza je odmah spremna za sljedeći slijed, bez novog WebSocket rukovanja; xAI procjenjuje uštedu na oko 600 ms za udaljene klijente. To je mehanizam prekida („barge-in“) za trenutke kada korisnik upadne u riječ.
{"type": "text.clear"}
session.update: ispravljanje izgovora
session.update instalira ili zamjenjuje tablicu replace za vezu: svaka fraza pronađena u tekstu zamjenjuje se svojim govornim oblikom prije sinteze, bez promjene teksta koji šalješ ili broja znakova za koje se naplaćuje. Pošalji je prije prve text.delta kako bi pokrila cijelu vezu; ažuriranje primljeno usred slijeda vrijedi tek od sljedećeg slijeda.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Poruke od poslužitelja prema klijentu
Poslužitelj odgovara s pet vrsta poruka: audio.delta, audio.done i error, koje su detaljno opisane u nastavku, plus audio.clear, koja potvrđuje otkazivanje, te session.updated, koja vraća aktivnu tablicu replace.
audio.delta: dio zvuka
Poruka audio.delta sadrži fragment zvuka kodiran u base64 formatu:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Svaka delta je valjani dio zvuka koji možeš odmah dekodirati i reproducirati. Delte pristižu kako generiranje napreduje.
audio.done: generiranje završeno
Poruka audio.done signalizira da je sav zvuk za tekstualni slijed koji si poslao generiran:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
trace_id je jedinstveni ID za slijed, koristan za otklanjanje pogrešaka i praćenje.
error: dogodila se pogreška
Ako nešto pođe po zlu, poslužitelj šalje poruku o pogrešci:
{
"type": "error",
"message": "Invalid text encoding"
}
Potpuni tijek komunikacije
Evo kako tipična sesija izgleda:
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 ----------------|
Poslužitelj može početi slati poruke audio.delta prije nego što si uopće poslao text.done. U tome i jest cijela poanta strujanja: generiranje počinje što je ranije moguće.
Potpuna implementacija u 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:
# Send the text in pieces of 2,000 characters
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
}))
# Signal the end of the text
await ws.send(json.dumps({"type": "text.done"}))
# Receive the audio pieces
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']}")
# Assemble the complete audio
return b"".join(audio_chunks)
Implementacija u 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", () => {
// Send the text
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);
});
}
Rukovanje s mnogo delta
Za tekst koji se generira progresivno (npr. izlaz LLM-a), pošalji svaki token izravno na 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"}))
Ova arhitektura „strujanja LLM-a u strujanje TTS-a“ nudi najnižu moguću latenciju: korisnik čuje odgovor dok LLM još uvijek generira sadržaj.
Ključne točke
- Četiri klijentske poruke:
text.delta(slanje teksta),text.done(kraj teksta),text.clear(otkazivanje) isession.update(tablicareplace) - Pet poslužiteljskih poruka:
audio.delta(dio zvuka),audio.done(kraj),audio.clear(potvrda otkazivanja),session.updatedierror - Zvuk je kodiran u base64 formatu unutar poruka
audio.delta - Poslužitelj počinje generirati prije nego što primi
text.done - Svaka tekstualna delta ograničena je na 60.000 znakova
- Lančano povezivanje strujanja LLM-a sa strujanjem TTS-a daje najnižu latenciju