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

Streaming TTS peste WebSocket

Lecția 9 din 14 Actualizată 3 noiembrie 2026 Intermediar
Pe această pagină
  1. De ce streamingul schimbă experiența
  2. Deschiderea conexiunii
  3. Protocolul de mesaje
  4. O implementare completă
  5. Limite de cunoscut
  6. HTTP sau WebSocket
  7. Puncte cheie

Actualizat la 3 noiembrie 2026, pe baza paginii Text to Speech de la xAI. Sursă: Text to Speech.

De ce streamingul schimbă experiența

În modul HTTP, TTS returnează controlul doar după ce tot fișierul audio a fost generat. Pentru o notificare de două propoziții, nimeni nu observă așteptarea. Pentru un articol de blog, un capitol de carte sau un flux de știri care se derulează continuu, această așteptare devine cel mai mare defect al produsului dumneavoastră: utilizatorii dau click, apoi privesc un indicator de încărcare timp de câteva secunde.

Modul WebSocket elimină această așteptare prin transmiterea audio pe măsură ce este sintetizat. Redarea începe la primele cuvinte, înainte ca sfârșitul textului să fi fost procesat. Aceasta este diferența dintre o pagină care pare blocată și un audio care pornește imediat.

Deschiderea conexiunii

Conexiunea se stabilește la wss://api.x.ai/v1/tts, iar toată configurația se transmite în șirul de interogare (query string) al URL-ului, nu într-un mesaj de inițializare.

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=en&voice=ara&codec=mp3&sample_rate=24000",
  {
    headers: {
      "Authorization": "Bearer " + XAI_API_KEY
    }
  }
);

Aceștia sunt parametrii acceptați:

  • language (obligatoriu): un cod BCP-47 sau auto
  • voice (opțional, implicit: eve): ID-ul vocii
  • codec (opțional, implicit: mp3): formatul audio de ieșire
  • sample_rate (opțional, implicit: 24000): frecvența de eșantionare în Hz
  • bit_rate (opțional, implicit: 128000): rata de biți în bps (doar pentru MP3)

Aceste setări se aplică pe întreaga durată a sesiunii: nu puteți schimba vocea sau codec-ul pe parcurs. Dacă aplicația dumneavoastră trebuie să alterneze între doi naratori, deschideți două conexiuni separate.

Protocolul de mesaje

În partea de emitere, aveți nevoie de doar două tipuri de mesaje pentru a gestiona sinteza. Primul trimite un fragment de text; al doilea anunță că textul s-a încheiat.

{ "type": "text.delta", "delta": "Hello and welcome " }
{ "type": "text.done" }

Puteți trimite câte mesaje text.delta doriți, fiecare având până la 60.000 de caractere. Totuși, este preferabil să nu atingeți această limită maximă: divizarea textului în fragmente de câteva propoziții vă permite să primiți primul fragment audio mult mai repede, ceea ce reprezintă chiar scopul streamingului. Un singur delta de câteva mii de caractere vă readuce la comportamentul specific modului HTTP.

În partea de recepție, fiecare mesaj audio.delta conține un fragment de audio codificat în base64, în codec-ul specificat la conectare. Decodați-l și adăugați-l în buffer-ul de redare.

{ "type": "audio.delta", "delta": "<base64 audio>" }
{ "type": "audio.done", "trace_id": "trace-uuid" }

Evenimentul audio.done marchează sfârșitul sintezei. Câmpul său trace_id este identificatorul pe care trebuie să îl furnizați suportului tehnic sau să îl înregistrați în jurnalele dumneavoastră (logs) în cazul în care o generare funcționează defectuos. Dacă textul este invalid sau ați depășit cota alocată, veți primi în schimb un mesaj de eroare.

{ "type": "error", "message": "description of the error" }

O implementare completă

Exemplul de mai jos divizează un text lung în paragrafe, le trimite pe toate, apoi asamblează fragmentele audio primite într-un fișier MP3.

const WebSocket = require("ws");
const fs = require("fs");

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3",
  { headers: { "Authorization": "Bearer " + process.env.XAI_API_KEY } }
);

const audioChunks = [];

ws.on("open", () => {
  const paragraphs = longText.split("\n\n");
  for (const para of paragraphs) {
    ws.send(JSON.stringify({
      type: "text.delta",
      delta: para + " "
    }));
  }
  ws.send(JSON.stringify({ type: "text.done" }));
});

ws.on("message", (data) => {
  const msg = JSON.parse(data);
  if (msg.type === "audio.delta") {
    audioChunks.push(Buffer.from(msg.delta, "base64"));
  } else if (msg.type === "audio.done") {
    fs.writeFileSync("output.mp3", Buffer.concat(audioChunks));
    ws.close();
  }
});

Rețineți utilizarea lui para + " ": fără acel spațiu, sfârșitul unui paragraf se va lipi de începutul următorului, iar motorul va citi cele două cuvinte împreună, fără o pauză de respirație.

Limite de cunoscut

MetricăValoare
Text per deltaMaxim 60.000 de caractere
Text totalNelimitat
Sesiuni concurente50 per echipă
Permis de sesiune600 de secunde
Timeout conexiuneNiciunul

Pagina xAI menționează că conexiunea nu are timeout și indică separat un „permis de sesiune“ de 600 de secunde, fără a explica ce se întâmplă la expirarea acestuia. Pentru siguranță, conectați-vă doar atunci când aveți text de trimis, nu la încărcarea paginii, și planificați reconectarea. Gestionați limita de 50 de sesiuni concurente per echipă în același mod: o bibliotecă audio care își convertește catalogul în fundal ar trebui să pună job-urile la coadă, în loc să deschidă două sute de conexiuni în paralel.

HTTP sau WebSocket

Modul HTTP rămâne alegerea corectă pentru texte scurte, generări unice și orice situație în care simplitatea integrării este prioritară: o cerere, un răspuns, fără stare de gestionat. WebSocket este soluția indicată atunci când textul devine lung, când audio-ul trebuie redat în timp ce este produs sau când conținutul însuși sosește sub formă de flux, fiind tipic rezultatul unui model lingvistic pe care îl transformați în voce pe măsură ce generează.

Puncte cheie

  • TTS prin WebSocket vă permite să primiți audio în flux fără a aștepta finalizarea generării
  • Parametrii de configurare se transmit în șirul de interogare al URL-ului de conexiune
  • Protocolul este simplu: text.delta pentru trimiterea textului, audio.delta pentru recepția audio
  • Sesiunile WebSocket sunt limitate la 50 de conexiuni concurente per echipă; planificați reconectarea
  • Preferați WebSocket pentru texte lungi și experiențe de ascultare în timp real