TTS streamelés WebSocketen keresztül
Ezen az oldalon
Frissítve: 2026. november 3., az xAI Text to Speech oldala alapján. Forrás: Text to Speech.
Miért változtatja meg a streamelés az élményt
HTTP módban a TTS csak akkor adja vissza az irányítást, ha az összes hanganyag elkészült. Két mondatos értesítésnél senki nem veszi észre a várakozást. Viszont blogbejegyzéseknél, könyvfejezeteknél vagy folyamatosan görgetett hírfolyamoknál ez a várakozás a terméked legnagyobb hibájává válik: a felhasználók kattintanak, majd másodpercekig egy töltőanimációt bámulnak.
A WebSocket mód megszünteti ezt a várakozást azáltal, hogy szintézis közben azonnal továbbítja a hangot. A lejátszás már az első szavaknál elindul, miközben a szöveg végét még fel sem dolgozta a rendszer. Ez a különbség a befagyottnak tűnő oldal és az azonnal megszólaló hanganyag között.
Kapcsolat megnyitása
A kapcsolatot a wss://api.x.ai/v1/tts címen nyitod meg, ahol minden konfigurációt nem egy inicializáló üzenetben, hanem közvetlenül az URL lekérdezési paramétereiben (query string) adsz meg.
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
}
}
);
Ezek az elfogadott paraméterek:
- language (kötelező): egy BCP-47 kód vagy az
autoérték - voice (opcionális, alapértelmezett:
eve): a hang azonosítója - codec (opcionális, alapértelmezett:
mp3): a kimeneti hangformátum - sample_rate (opcionális, alapértelmezett:
24000): a mintavételezési frekvencia Hz-ben - bit_rate (opcionális, alapértelmezett:
128000): a bitráta bps-ben (kizárólag MP3 esetén)
Ezek a beállítások a teljes munkamenetre érvényesek: menet közben nem tudod megváltoztatni a hangot vagy a kodeket. Ha az alkalmazásodnak két különböző narrátor között kell váltogatnia, nyiss két külön kapcsolatot.
Az üzenetprotokoll
A küldő oldalon mindössze két üzenettípusra van szükséged a szintézis vezérléséhez. Az első egy szövegrészt küld, a második pedig jelzi, hogy a szöveg véget ért.
{ "type": "text.delta", "delta": "Hello and welcome " }
{ "type": "text.done" }
Annyi text.delta üzenetet küldhetsz, amennyit csak szeretnél, mindegyik maximum 60 000 karakter hosszú lehet. Ennek ellenére érdemes nem kihasználni ezt a limitet: ha néhány mondatos darabokra bontod a szöveget, sokkal hamarabb megérkezik hozzád az első hangrészlet, ami a streamelés lényege. Ha egyetlen deltában több ezer karaktert küldesz, azzal visszakerülsz a HTTP-mód viselkedéséhez.
A fogadó oldalon minden audio.delta üzenet a beállított kodeknek megfelelő, base64-kódolt hangrészletet tartalmaz. Dekódold ezt, és fűzd hozzá a lejátszási pufferhez.
{ "type": "audio.delta", "delta": "<base64 audio>" }
{ "type": "audio.done", "trace_id": "trace-uuid" }
Az audio.done esemény jelzi a szintézis végét. A benne lévő trace_id az az azonosító, amit a támogatásnak kell megadnod, vagy amit a naplóidban rögzítened kell, ha valami hiba történik a generálás során. Ha a szöveg érvénytelen, vagy túllépted a kvótádat, hibaüzenetet kapsz helyette.
{ "type": "error", "message": "description of the error" }
Teljes megvalósítás
Az alábbi példa egy hosszú szöveget bekezdésekre bont, elküldi azokat, majd a kapott hangrészletekből összeállít egy MP3 fájlt.
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();
}
});
Figyeld meg a para + " " részt: e szóköz nélkül az egyik bekezdés vége összeér a következő elejével, és a motor levegővétel nélkül, egyben olvassa fel a két szót.
Ismerendő korlátok
| Metrika | Érték |
|---|---|
| Szöveg deltánként | max. 60 000 karakter |
| Összes szöveg | Korlátlan |
| Egyidejű munkamenetek | 50 csapatonként |
| Munkamenet-engedély | 600 másodperc |
| Kapcsolat időtúllépés | Nincs |
Az xAI dokumentációja szerint a kapcsolatnak nincs időtúllépése, de külön említ egy 600 másodperces „munkamenet-engedélyt“ anélkül, hogy tisztázná, mi történik, ha ez lejár. A biztonság kedvéért csak akkor létesíts kapcsolatot, ha van elküldendő szöveged, ne már az oldal betöltésekor, és tervezz újraconnectelést. Ugyanígy tervezd meg az csapatra vonatkozó 50 egyidejű munkamenet korlátját is: egy háttérben katalógust konvertáló hangkönyvtárnak sorba kell állítania a feladatokat, ahelyett, hogy párhuzamosan kétszáz kapcsolatot nyitna meg.
HTTP vagy WebSocket
A HTTP mód továbbra is a helyes választás rövid szövegeknél, egyszeri generálásoknál, és mindenhol, ahol az integráció egyszerűsége a legfontosabb: egy kérés, egy válasz, nincs kezelendő állapot. A WebSocket akkor jön szóba, ha a szöveg hosszú, ha a hangot gyártás közben kell lejátszani, vagy ha maga a tartalom is streamként érkezik – tipikusan egy nyelvi modell kimeneteként, amit generálás közben alakítasz hanggá.
Főbb megállapítások
- A WebSocket alapú TTS lehetővé teszi a streamelt hangfogadást anélkül, hogy meg kellene várnod a generálás végét
- A konfigurációs paramétereket a kapcsolati URL lekérdezési karakterláncában kell megadni
- A protokoll egyszerű:
text.deltaa szöveg küldéséhez,audio.deltaa hang fogadásához - A WebSocket munkamenetek száma csapatra vetítve 50 egyidejű kapcsolatra korlátozódik; tervezz újraconnectelést
- Hosszú szövegeknél és valós idejű hallgatási élményeknél részesítsd előnyben a WebSocketet