TTS srautinis perdavimas per WebSocket
Šiame puslapyje
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
| Rodiklis | Reikšmė |
|---|---|
| Tekstas vienam delta | Maks. 60 000 simbolių |
| Visas tekstas | Neribota |
| Vienalaikės sesijos | 50 vienai komandai |
| Sesijos leidimas | 600 sekundžių |
| Ryšio laiko limitas | Nė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.deltatekstui siųsti,audio.deltagarso 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