Salt la conținutul principal
Română— Alege o limbă
Meniu

Mesaje WebSocket: text și audio

Lecția 10 din 14 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Protocolul de mesaje TTS
  2. Mesaje de la client la server
  3. Mesaje de la server la client
  4. Fluxul complet de comunicare
  5. Implementare completă în Python
  6. Implementare în JavaScript (Node.js)
  7. Gestionarea mai multor delte
  8. Puncte cheie

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) și session.update (tabel replace)
  • Cinci mesaje de la server: audio.delta (fragment audio), audio.done (sfârșit), audio.clear (anulare confirmată), session.updated și error
  • 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ță