Mesaje WebSocket: text și audio
Pe această pagină
Actualizat la 3 noiembrie 2026, pe baza paginii Text to Speech de la xAI: delte de până la 60.000 de caractere, anulare (
text.clear,audio.clear) și tabelul de pronunție (session.update,session.updated). Sursă: Text to Speech.
Protocolul de mesaje TTS
Odată ce conexiunea WebSocket este deschisă, comunicarea funcționează prin schimbul de mesaje JSON. Dumneavoastră trimiteți text, iar serverul răspunde cu audio codificat în base64. Înțelegerea acestui protocol este esențială pentru implementarea corectă a streaming-ului TTS.
Mesaje de la client la server
Aplicația dumneavoastră trimite serverului patru tipuri de mesaje: text.delta și text.done pentru text, text.clear pentru anulare și session.update pentru configurare.
text.delta: trimiterea unui fragment de text
Mesajul text.delta trimite un fragment de text care urmează să fie convertit. Puteți trimite textul în bucăți succesive:
{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}
Fiecare deltă poate conține până la 60.000 de caractere, iar textul total nu are nicio limită. Serverul începe generarea audio imediat ce are suficient context pentru a produce o pronunție naturală.
text.done: semnalarea sfârșitului textului
Mesajul text.done informează serverul că ați terminat de trimis textul pentru această secvență:
{"type": "text.done"}
Odată primit acest mesaj, serverul finalizează generarea audio și trimite un mesaj audio.done. Apoi puteți începe să trimiteți noi delte pentru o nouă secvență.
text.clear: anularea secvenței curente
text.clear anulează secvența curentă: serverul oprește generarea audio, șterge datele din memorie și răspunde cu audio.clear. Conexiunea este imediat pregătită pentru următoarea secvență, fără un nou handshake WebSocket; xAI estimează economisirea la aproximativ 600 ms pentru un client distant. Acesta este mecanismul de întrerupere („barge-in“) pentru momentele în care utilizatorul intervine.
{"type": "text.clear"}
session.update: fixarea pronunției
session.update instalează sau înlocuiește tabelul replace al conexiunii: fiecare frază găsită în text este înlocuită cu forma sa rostită înainte de sinteză, fără a modifica textul pe care îl trimiteți sau numărul de caractere pentru care vi se facturează. Trimiteți-l înainte de primul text.delta pentru a acoperi întreaga conexiune; o actualizare primită la mijlocul unei secvențe se aplică doar de la secvența următoare.
{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}
Mesaje de la server la client
Serverul răspunde cu cinci tipuri de mesaje: audio.delta, audio.done și error, detaliate mai jos, plus audio.clear, care confirmă o anulare, și session.updated, care returnează tabelul replace activ.
audio.delta: un fragment de audio
Mesajul audio.delta conține un fragment de audio codificat în base64:
{
"type": "audio.delta",
"delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}
Fiecare deltă este o bucată validă de audio pe care o puteți decoda și reda imediat. Deltele sosesc pe măsură ce generarea progresează.
audio.done: generare finalizată
Mesajul audio.done semnalează că tot audio-ul pentru secvența de text trimisă a fost generat:
{
"type": "audio.done",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
trace_id este un ID unic pentru secvență, util pentru depanare și urmărire.
error: a apărut o eroare
Dacă ceva nu merge bine, serverul trimite un mesaj de eroare:
{
"type": "error",
"message": "Invalid text encoding"
}
Fluxul complet de comunicare
Iată cum se desfășoară o sesiune tipică:
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 ----------------|
Serverul poate începe să trimită mesaje audio.delta înainte chiar ca dumneavoastră să fi trimis text.done. Aceasta este ideea principală a streaming-ului: generarea începe cât mai devreme posibil.
Implementare completă în 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:
# Trimiteți textul în bucăți de 2.000 de caractere
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
}))
# Semnalați sfârșitul textului
await ws.send(json.dumps({"type": "text.done"}))
# Primiți fragmentele audio
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']}")
# Asamblați audio-ul complet
return b"".join(audio_chunks)
Implementare în 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", () => {
// Trimiteți textul
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);
});
}
Gestionarea mai multor delte
Pentru textul generat progresiv (de exemplu, ieșirea unui LLM), trimiteți fiecare token direct către WebSocket-ul TTS:
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"}))
Această arhitectură de „streaming LLM în streaming TTS“ oferă cea mai mică latență posibilă: utilizatorul aude răspunsul în timp ce LLM-ul încă generează conținut.
Puncte cheie
- Patru mesaje de la client:
text.delta(trimitere text),text.done(sfârșit text),text.clear(anulare) șisession.update(tabelreplace) - Cinci mesaje de la server:
audio.delta(fragment audio),audio.done(sfârșit),audio.clear(anulare confirmată),session.updatedșierror - Audio-ul este codificat în base64 în mesajele
audio.delta - Serverul începe generarea înainte de a primi
text.done - Fiecare deltă de text este limitată la 60.000 de caractere
- Înlănțuirea unui LLM cu streaming într-un TTS cu streaming oferă cea mai mică latență