Съобщения през WebSocket: текст и аудио
На тази страница
Обновено на 3 ноември 2026 г., въз основа на страницата Text to Speech на xAI: делти до 60 000 знака, отмяна (
text.clear,audio.clear) и таблица за произношение (session.update,session.updated). Източник: Text to Speech.
Протокол за съобщения на TTS
След като връзката през WebSocket се установи, комуникацията протича чрез размяна на JSON съобщения. Вие изпращате текст, а сървърът отговаря с аудио, кодирано в base64. Разбирането на този протокол е от съществено значение за правилното внедряване на потоково предаване на TTS.
Съобщения от клиент към сървър
Вашето приложение изпраща четири типа съобщения до сървъра: text.delta и text.done за текста, text.clear за отмяна и session.update за конфигуриране.
text.delta: изпращане на част от текста
Съобщението text.delta изпраща фрагмент от текст за преобразуване. Можете да изпращате текста на последователни части:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Всяка делта може да съдържа до 60 000 знака, като общият текст няма ограничение. Сървърът започва да генерира аудио веднага щом разполага с достатъчно контекст, за да произведе естествено произношение.
text.done: сигнализиране на края на текста
Съобщението text.done информира сървъра, че сте приключили с изпращането на текст за тази последователност:
{"type": "text.done"}
След получаването на това съобщение сървърът завършва генерирането на аудиото и изпраща съобщение audio.done. След това можете да започнете да изпращате нови делти за нова последователност.
text.clear: отмяна на текущата последователност
text.clear отменя текущата последователност: сървърът спира генерирането на аудио, изтрива данните в паметта си и отговаря с audio.clear. Връзката е незабавно готова за следващата последователност без ново ръкостискане на WebSocket; xAI оценява спестеното време на около 600 ms за отдалечен клиент. Това е механизмът за прекъсване („barge-in“), когато потребителят се намеси.
{"type": "text.clear"}
session.update: коригиране на произношението
session.update инсталира или заменя таблицата replace на връзката: всяка фраза, открита в текста, се заменя с нейната говорима форма преди синтеза, без да се променя изпратеният от Вас текст или броят на таксуваните знаци. Изпратете го преди първия text.delta, за да обхване цялата връзка; актуализация, получена по средата на последователност, важи едва от следващата последователност.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Съобщения от сървър към клиент
Сървърът отговаря с пет типа съобщения: audio.delta, audio.done и error, описани по-долу, плюс audio.clear, което потвърждава отмяната, и session.updated, което връща активната таблица replace.
audio.delta: част от аудио
Съобщението audio.delta съдържа аудио фрагмент, кодиран в base64:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Всяка делта представлява валиден аудио фрагмент, който можете да декодирате и възпроизведете незабавно. Делтите пристигат в процеса на генериране.
audio.done: генерирането приключи
Съобщението audio.done сигнализира, че цялото аудио за изпратената от Вас текстова последователност е генерирано:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
trace_id е уникален идентификатор за последователността, полезен за отстраняване на грешки и проследяване.
error: възникнала е грешка
Ако нещо се обърка, сървърът изпраща съобщение за грешка:
{
"type": "error",
"message": "Invalid text encoding"
}
Пълният поток на комуникация
Ето как протича типична сесия:
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 ----------------|
Сървърът може да започне да изпраща съобщения audio.delta, преди дори да сте изпратили text.done. Това е същинската идея на потоковото предаване: генерирането започва възможно най-рано.
Пълна реализация на 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:
# Изпращане на текста на части от 2000 знака
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
}))
# Сигнализиране на края на текста
await ws.send(json.dumps({"type": "text.done"}))
# Получаване на аудио частите
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']}")
# Сглобяване на пълното аудио
return b"".join(audio_chunks)
Реализация на 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", () => {
// Изпращане на текста
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);
});
}
Обработка на множество делти
За текст, генериран прогресивно (например изход от LLM), изпращайте всеки токен директно към 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"}))
Тази архитектура „потоков LLM към потоков TTS“ осигурява най-ниската възможна латентност: потребителят чува отговора, докато LLM все още генерира.
Ключови изводи
- Четири клиентски съобщения:
text.delta(изпращане на текст),text.done(край на текста),text.clear(отмяна) иsession.update(таблицаreplace) - Пет сървърни съобщения:
audio.delta(аудио част),audio.done(край),audio.clear(потвърждение за отмяна),session.updatedиerror - Аудиото е кодирано в base64 в съобщенията
audio.delta - Сървърът започва генерирането, преди да получи
text.done - Всяка текстова делта е ограничена до 60 000 знака
- Свързването на потоков LLM към потоков TTS осигурява най-ниската латентност