Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

TTS srautinis perdavimas per WebSocket

Paskaita 9 iš 14 Atnaujinta 2026 m. lapkričio 3 d. Vidutinis lygis
Šiame puslapyje
  1. Kodėl srautinis perdavimas keičia patirtį
  2. Užmegzk ryšį
  3. Žinučių protokolas
  4. Pilnas įgyvendinimas
  5. Žinotinos ribos
  6. HTTP ar WebSocket
  7. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 3 d., remiantis xAI Text to Speech puslapiu. Šaltinis: Text to Speech.

Kodėl srautinis perdavimas keičia patirtį

HTTP režimu TTS grąžina valdymą tik tada, kai visas garso įrašas sugeneruotas. Dviejų sakinių pranešimui niekas nepastebi laukimo. Tačiau tinklaraščio įrašui, knygos skyriui arba nuolat slenkamam naujienų srautui laukimas tampa didžiausiu tavo produkto trūkumu: vartotojai paspaudžia, o tada kelias sekundes žiūri į besisukantį įkrovos indikatorių.

WebSocket režimas pašalina šį laukimą, siųsdamas garso duomenis jiems sintezuojant. Atkūrimas prasideda nuo pirmųjų žodžių, nors teksto pabaiga dar nėra apdorota. Tai skirtumas tarp puslapio, kuris atrodo užstrigęs, ir garso, kuris groja iškart.

Užmegzk ryšį

Ryšys užmezgamas adresu wss://api.x.ai/v1/tts, o visa konfigūracija nurodoma URL užklausos eilutėje, o ne inicializavimo žinutėje.

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

Štai priimtini parametrai:

  • language (būtinas): BCP-47 kodas arba auto
  • voice (nebūtinas, numatytasis: eve): balso ID
  • codec (nebūtinas, numatytasis: mp3): išvesties garso formatas
  • sample_rate (nebūtinas, numatytasis: 24000): diskretizavimo dažnis Hz
  • bit_rate (nebūtinas, numatytasis: 128000): bitų sparta bps (tik MP3)

Šie nustatymai galioja visai sesijai: negali keisti balso ar kodeko sesijos metu. Jei tavo programai reikia pakaitomis naudoti du pasakotojus, atidaryk du atskirus ryšius.

Žinučių protokolas

Siuntimo pusėje sintezei valdyti pakanka dviejų tipų žinučių. Pirmoji siunčia teksto dalį, antroji praneša, kad tekstas baigtas.

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

Gali siųsti tiek text.delta žinučių, kiek reikia, kiekviena iki 60 000 simbolių. Visgi geriau neišnaudoti šios ribos iki galo: teksto skaidymas į kelių sakinių dalis leidžia pirmąjį garso fragmentą gauti daug greičiau, o tai ir yra srautinio perdavimo esmė. Viena didelė kelių tūkstančių simbolių dalis grąžina tave prie HTTP režimo elgsenos.

Priėmimo pusėje kiekvienas audio.delta perduoda base64 koduoto garso fragmentą tuo kodeku, kurį nustatei jungdamasis. Iššifruok jį ir pridėk prie savo atkūrimo buferio.

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

Įvykis audio.done žymi sintezės pabaigą. Jo trace_id yra identifikatorius, kurį turi pateikti palaikymo tarnybai arba įrašyti į savo žurnalus, jei generavimas veikia netinkamai. Jei tekstas neteisingas arba viršijai savo kvotą, vietoj to gausi klaidos pranešimą.

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

Pilnas įgyvendinimas

Toliau pateiktame pavyzdyje ilgas tekstas padalijamas į pastraipas, visos jos išsiunčiamos, o gauti garso fragmentai surenkami į MP3 failą.

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

Atkreipk dėmesį į para + " ": be to tarpo vienos pastraipos pabaiga susilietų su kitos pradžia, ir variklis abu žodžius perskaitytų kartu, neįkvėpdamas.

Žinotinos ribos

RodiklisReikšmė
Tekstas vienam deltaMaks. 60 000 simbolių
Visas tekstasNeribota
Vienalaikės sesijos50 vienai komandai
Sesijos leidimas600 sekundžių
Ryšio laiko limitasNėra

xAI puslapyje teigiama, kad ryšys neturi laiko limito, ir atskirai minimas 600 sekundžių „sesijos leidimas“, nepaaiškinant, kas nutinka jam pasibaigus. Saugumo sumetimais užmegzk ryšį tik tada, kai turi siųsti tekstą, o ne puslapiui įsikrovus, ir numatyk galimybę prisijungti iš naujo. Taip pat planuok darbą atsižvelgdamas į 50 vienalaikių sesijų vienai komandai ribą: garso biblioteka, foniniu režimu konvertuojanti savo katalogą, turėtų eiliuoti savo užduotis, o ne atidaryti du šimtus lygiagrečių ryšių.

HTTP ar WebSocket

HTTP režimas vis dar yra tinkamas pasirinkimas trumpiems tekstams, vienkartiniam generavimui ir ten, kur svarbiausias integracijos paprastumas: viena užklausa, vienas atsakymas, nereikia valdyti būsenos. WebSocket yra tinkamas kelias, kai tekstas ilgas, kai garso įrašas turi būti grojamas jo generavimo metu arba kai pats turinys ateina kaip srautas – paprastai tai kalbos modelio išvestis, kurią įgarsini generavimo metu.

Svarbiausi punktai

  • WebSocket TTS leidžia gauti srautinį garso įrašą nelaukiant, kol generavimas baigsis
  • Konfigūracijos parametrai nurodomi ryšio URL užklausos eilutėje
  • Protokolas paprastas: text.delta tekstui siųsti, audio.delta garso priėmimui
  • WebSocket sesijos apribotos iki 50 vienalaikių vienai komandai; numatyk galimybę prisijungti iš naujo
  • Ilgiems tekstams ir realaus laiko klausymosi patirčiai teik pirmenybę WebSocket