Lähe põhisisu juurde
Eesti— Vali keel
Menüü

TTS-i voogedastus WebSocketi kaudu

Õppetund 9 / 14 Värskendatud 3. november 2026 Kesktase
Sellel lehel
  1. Miks voogedastus kasutajakogemust muudab
  2. Ühenduse loomine
  3. Sõnumiprotokoll
  4. Täielik implementatsioon
  5. Teadaolevad piirangud
  6. HTTP või WebSocket
  7. Peamised punktid

Uuendatud 3. novembril 2026, tuginedes xAI Text to Speech lehele. Allikas: Text to Speech.

Miks voogedastus kasutajakogemust muudab

HTTP-režiimis annab TTS juhtimise tagasi alles siis, kui kogu helifail on valmis. Kahe lause pikkuse teavituse puhul keegi ooteaega ei märka. Blogipostituse, raamatipeatüki või pidevalt keritava uudisvoo puhul muutub ootamine aga sinu toote suurimaks veaks: kasutaja klõpsab ja vaatab seejärel mitu sekundit laadimisikooni.

WebSocketi režiim kõrvaldab selle ooteaja, edastades heli seda sünteesides kohe edasi. Taasesitus algab esimeste sõnade kõlamisega, kuigi teksti lõppu pole veel töödeldud. See ongi erinevus lehe vahel, mis tundub külmutatuna, ja heli vahel, mis mängib kohe.

Ühenduse loomine

Ühendus avatakse aadressil wss://api.x.ai/v1/tts ning kogu konfiguratsioon edastatakse URL-i päringuparameetrites, mitte algatussõnumis.

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
    }
  }
);

Lubatud on järgmised parameetrid:

  • language (kohustuslik): BCP-47 kood või auto
  • voice (valikuline, vaikimisi: eve): hääle ID
  • codec (valikuline, vaikimisi: mp3): väljundheli formaat
  • sample_rate (valikuline, vaikimisi: 24000): diskreetimissagedus Hz-des
  • bit_rate (valikuline, vaikimisi: 128000): bitikiirus bps-des (ainult MP3 puhul)

Need seaded kehtivad kogu seansi vältel: häält või kodeerimist ei saa seansi ajal muuta. Kui sinu rakendus vajab kahe erineva jutustaja vaheldumist, ava kaks eraldi ühendust.

Sõnumiprotokoll

Saatmise poolel piisab sünteesi juhtimiseks kahest sõnumist. Esimene saadab tekstilõigu, teine annab teada, et tekst on lõppenud.

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

Võid saata nii palju text.delta sõnumeid kui vaja, igaüks kuni 60 000 tähemärgi pikkune. Siiski pole mõistlik seda limiiti maksimaalselt ära kasutada: teksti jagamine mõnelauselisteks tükkideks toob esimese helilõigu sinuni palju kiiremini, mis ongi voogedastuse peamine eesmärk. Üksainus mitmetuhande tähemärgine delta viib sind tagasi HTTP-režiimi käitumise juurde.

Vastuvõtu poolel kannab iga audio.delta sõnum baas64-kodeeritud helifragmenti selles formaadis, mille määrasid ühenduse loomisel. Dekodeeri see ja lisa oma taasesituspuhvrisse.

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

Sündmus audio.done tähistab sünteesi lõppu. Selle trace_id on identifikaator, mille edastad tugiteenusele või salvestad oma logidesse, kui genereerimine ei õnnestu. Kui tekst on vigane või oled ületanud oma kvooti, saad selle asemel veateate.

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

Täielik implementatsioon

Allpool toodud näide jagab pika teksti lõikudeks, saadab need kõik ära ja seejärel koondab vastuvõetud helifragmendid MP3-failiks.

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();
  }
});

Pane tähele avaldist para + " ": ilma selle tühikuta jookseb ühe lõigu lõpp kokku järgmise algusega ja mootor loeb kaks sõna ühe hingetõmbega kokku.

Teadaolevad piirangud

NäitajaVäärtus
Teksti maht delta kohtaMax 60 000 tähemärki
Kogu tekstPiiramatu
Samaaegsed seansid50 meeskonna kohta
Seansi luba600 sekundit
Ühenduse aeguminePuudub

xAI lehel on öeldud, et ühendusel puudub aegumine, ning eraldi mainitakse „seansi luba“ 600 sekundi ulatuses, selgitamata, mis juhtub selle lõppedes. Ohutuse huvides loo ühendus siis, kui sul on teksti saata, mitte lehe laadimisel, ja planeeri ühenduse taastamist. Planeeri samamoodi ka meeskonna 50 samaaegse seansi limiiti: heliteek, mis teisendab taustal oma kataloogi, peaks järjekordistama oma tööd, mitte avama kahesaja ühendust paralleelselt.

HTTP või WebSocket

HTTP-režiim on endiselt õige valik lühikeste tekstide, üksikute genereeringute ja kõikjal, kus integratsiooni lihtsus on kõige olulisem: üks päring, üks vastus, olekut pole vaja hallata. WebSocket on aga õige tee, kui tekst on pikk, kui heli peab mängima selle genereerimise ajal või kui sisu ise saabub voona – tüüpiliselt keelemudeli väljundina, mida häälestad selle genereerumise käigus.

Peamised punktid

  • WebSocketi TTS võimaldab vastu võtta voogedastatud heli, ootamata genereerimise lõppu
  • Konfiguratsiooniparameetrid edastatakse ühenduse URL-i päringuparameetrites
  • Protokoll on lihtne: text.delta teksti saatmiseks, audio.delta heli vastuvõtmiseks
  • WebSocketi seansid on piiratud 50 samaaegse seansiga meeskonna kohta; planeeri ühenduse taastamist
  • Eelista WebSocketit pikkade tekstide ja reaalajas kuulamiskogemuste puhul