Žinutės per WebSocket: tekstas ir garsas
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 3 d., remiantis xAI Text to Speech puslapiu: deltų dydis iki 60 000 simbolių, atšaukimas (
text.clear,audio.clear) ir tarimo lentelė (session.update,session.updated). Šaltinis: Text to Speech.
TTS žinučių protokolas
Kai WebSocket ryšys užmegztas, bendravimas vyksta keičiantis JSON žinutėmis. Tu siunti tekstą, o serveris atsako garso duomenimis, koduotais „base64“. Suprasti šį protokolą būtina norint tinkamai įgyvendinti TTS srautinį perdavimą.
Žinutės iš kliento į serverį
Tavo programa siunčia serveriui keturių tipų žinutes: text.delta ir text.done tekstui, text.clear atšaukimui bei session.update konfigūravimui.
text.delta: siųsti teksto dalį
Žinutė text.delta siunčia teksto fragmentą, kurį reikia paversti garsu. Tekstą gali siųsti palaipsniui, dalimis:
{"type": "text.delta", "delta": "Sveiki, ir sveikiname jus "}
{"type": "text.delta", "delta": "mūsų pristatyme apie kalbos sintezę."}
Kiekviena delta gali turėti iki 60 000 simbolių, o bendras teksto ilgis neribojamas. Serveris pradeda generuoti garsą iškart, kai turi pakankamai konteksto natūraliam tarimui užtikrinti.
text.done: signalizuoti teksto pabaigą
Žinutė text.done praneša serveriui, kad baigei siųsti šios sekos tekstą:
{"type": "text.done"}
Gavęs šią žinutę, serveris baigia generuoti garsą ir siunčia žinutę audio.done. Tuomet gali pradėti siųsti naujas deltas kitai sekai.
text.clear: atšaukti dabartinę seką
text.clear atšaukia dabartinę seką: serveris nustoja generuoti garsą, išvalo atmintyje esančius duomenis ir atsako audio.clear. Ryšys iškart paruoštas kitai sekai, nereikia naujo WebSocket rankos paspaudimo; xAI teigia, kad tai nutolusiems klientams sutaupo apie 600 ms. Tai pertraukimo („barge-in“) mechanizmas, kai vartotojas įsiterpia į pokalbį.
{"type": "text.clear"}
session.update: taisyti tarimą
session.update įdiegia arba pakeičia ryšio replace lentelę: kiekviena tekste rasta frazė prieš sintezę pakeičiama jos tariamuoju variantu, nekeičiant siunčiamo teksto ar apskaitomų simbolių skaičiaus. Siųsk ją prieš pirmąją text.delta, kad ji galiotų visam ryšiui; viduryje sekos gautas atnaujinimas įsigalios tik nuo kitos sekos.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Žinutės iš serverio į klientą
Serveris atsako penkių tipų žinutėmis: audio.delta, audio.done ir error, kurios aptartos žemiau, taip pat audio.clear, patvirtinančia atšaukimą, bei session.updated, grąžinančia galiojančią replace lentelę.
audio.delta: garso dalis
Žinutė audio.delta turi garso fragmentą, koduotą „base64“:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Kiekviena delta yra pilnavertis garso gabalas, kurį gali iškart dešifruoti ir paleisti. Deltos atkeliauja generavimo eigai vykstant.
audio.done: generavimas baigtas
Žinutė audio.done signalizuoja, kad visas siųsto teksto sekos garsas sugeneruotas:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
trace_id yra unikalus sekos ID, naudingas derinimui ir stebėsenai.
error: įvyko klaida
Jei kas nors nepavyksta, serveris siunčia klaidos žinutę:
{
"type": "error",
"message": "Invalid text encoding"
}
Pilnas bendravimo srautas
Štai kaip atrodo tipinė sesija:
Client Server
| |
|-- text.delta ("Sveiki, ") ----->|
|-- text.delta ("kaip sekasi ") ---->|
|-- text.delta ("jums?") -------->|
|<-- audio.delta (1 dalis) -----|
|<-- audio.delta (2 dalis) -----|
|-- text.done ----------------->|
|<-- audio.delta (3 dalis) -----|
|<-- audio.done ----------------|
Serveris gali pradėti siųsti audio.delta žinutes dar prieš tau nusiuntus text.done. Būtent tai ir yra srautinio perdavimo esmė: generavimas prasideda kuo anksčiau.
Pilnas įgyvendinimas Python kalba
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:
# Siųsti tekstą 2000 simbolių dalimis
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
}))
# Signalizuoti teksto pabaigą
await ws.send(json.dumps({"type": "text.done"}))
# Gauti garso dalis
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"Generavimas baigtas (sekos ID: {data['trace_id']})")
break
elif data["type"] == "error":
raise Exception(f"TTS klaida: {data['message']}")
# Surinkti visą garsą
return b"".join(audio_chunks)
Įgyvendinimas 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", () => {
// Siųsti 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);
});
}
Daugelio deltų valdymas
Tekstui, kuriamas palaipsniui (pvz., didžiojo kalbos modelio išvestis), siųsk kiekvieną tokeną tiesiai į 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"}))
Ši „srautinio LLM į srautinį TTS“ architektūra užtikrina mažiausią įmanomą delsą: vartotojas girdi atsakymą dar LLM generuojant tekstą.
Svarbiausi punktai
- Keturi kliento pranešimai:
text.delta(siųsti tekstą),text.done(teksto pabaiga),text.clear(atšaukti) irsession.update(replacelentelė) - Penki serverio pranešimai:
audio.delta(garso dalis),audio.done(pabaiga),audio.clear(atšaukimas patvirtintas),session.updatedirerror - Garsas žinutėse
audio.deltakoduotas „base64“ - Serveris pradeda generuoti dar negavęs
text.done - Kiekviena teksto delta ribojama iki 60 000 simbolių
- Srautinio LLM sujungimas su srautiniu TTS užtikrina mažiausią delsą