TTS-suoratoisto WebSocketin yli
Tällä sivulla
Päivitetty 3. marraskuuta 2026 xAI:n Text to Speech -sivun perusteella. Lähde: Text to Speech.
Miksi suoratoisto muuttaa kokemusta
HTTP-tilassa TTS palauttaa hallinnan vasta, kun koko ääni on tuotettu. Kahden lauseen ilmoituksessa kukaan ei huomaa odotusta. Blogikirjoituksen, kirjan luvun tai jatkuvasti vierivän uutisvirran kohdalla odotus muuttuu tuotteesi suurimmaksi virheeksi: käyttäjät napsauttavat, sitten tuijottavat latausindikaattoria useita sekunteja.
WebSocket-tila poistaa tämän odotuksen työntämällä äänen ulos sitä mukaa, kun sitä syntetisoidaan. Toisto alkaa ensimmäisistä sanoista, vaikka tekstin loppua ei ole vielä käsitelty. Siinä on ero sivun välillä, joka näyttää jäätyneeltä, ja äänen, joka toistuu heti.
Avaa yhteys
Yhteys avataan osoitteeseen wss://api.x.ai/v1/tts, ja kaikki määritykset annetaan URL:n kyselymerkkijonossa eikä alustusviestissä.
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
}
}
);
Nämä ovat hyväksytyt parametrit:
- language (vaadittu): BCP-47-koodi tai
auto - voice (valinnainen, oletus:
eve): äänen tunniste - codec (valinnainen, oletus:
mp3): lähtöäänimuoto - sample_rate (valinnainen, oletus:
24000): näytetaajuus hertseinä - bit_rate (valinnainen, oletus:
128000): bittinopeus bps (vain MP3)
Nämä asetukset koskevat koko istuntoa: et voi vaihtaa ääntä tai koodekkia kesken kaiken. Jos sovelluksesi tarvitsee vuorotella kahden kertojan välillä, avaa kaksi yhteyttä.
Viestintäprotokolla
Lähetyksen puolella tarvitset vain kaksi viestiä synteesin ohjaamiseen. Ensimmäinen lähettää tekstikatkalon; toinen ilmoittaa tekstin olevan valmis.
{ "type": "text.delta", "delta": "Hello and welcome " }
{ "type": "text.done" }
Voit lähettää niin monta text.delta-viestiä kuin tarvitset, kukin enintään 60 000 merkkiä. Silti on parempi olla käyttämättä rajaa maksimaalisesti: tekstin jakaminen muutaman lauseen katkoihin tuo ensimmäisen äänikatkalon luoksesi paljon nopeammin, mikä on koko suoratoiston pointti. Yksi useiden tuhansien merkkien delta palauttaa sinut HTTP-tilan toimintaan.
Vastaanoton puolella kukin audio.delta kuljettaa osan base64-koodatusta äänestä siinä koodekissa, jonka asetit yhteyden muodostamisen yhteydessä. Pura se ja liitä se toistopuskuriisi.
{ "type": "audio.delta", "delta": "<base64 audio>" }
{ "type": "audio.done", "trace_id": "trace-uuid" }
audio.done-tapahtuma merkitsee synteesin päättymisen. Sen trace_id on tunniste, joka annetaan tuelle tai kirjataan lokeihin, kun generointi toimii virheellisesti. Jos teksti on virheellinen tai olet ylittänyt kiintiösi, saat virheilmoituksen sen sijaan.
{ "type": "error", "message": "description of the error" }
Täydellinen toteutus
Alla oleva esimerkki jakaa pitkän tekstin kappaleisiin, lähettää ne kaikki ja kokoaa vastaanotetut äänikatkalot MP3-tiedostoksi.
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();
}
});
Huomaa para + " ": ilman tätä välilyöntiä yhden kappaleen loppu juoksee seuraavan alkuun, ja moottori lukee kaksi sanaa yhtenä ilman hengähdystaukoa.
Huomioitavat rajat
| Mittari | Arvo |
|---|---|
| Tekstiä per delta | Enintään 60 000 merkkiä |
| Tekstiä yhteensä | Rajoittamaton |
| Samanaikaiset istunnot | 50 tiimiä kohden |
| Istuntolupa | 600 sekuntia |
| Yhteyden aikakatkaisu | Ei ole |
xAI:n sivu kertoo, että yhteydellä ei ole aikakatkaisua, ja mainitsee erikseen 600 sekunnin “istuntoluvan” selittämättä, mitä tapahtuu sen loputtua. Varmuuden vuoksi muodosta yhteys silloin, kun sinulla on lähetettävää tekstiä, äläkä sivun latautuessa, ja varaudu uudelleenyhteyden muodostamiseen. Suunnittele myös 50 samanaikaisen istunnon raja tiimiä kohden samalla tavalla: äänikirjasto, joka muuntaa luetteloaan taustalla, pitäisi jonottaa tehtävänsä sen sijaan, että se avaisi kaksisataa yhteyttä rinnakkain.
HTTP vai WebSocket
HTTP-tila on edelleen oikea valinta lyhyille teksteille, kertaluonteisille generoinneille ja kaikkialle, missä integraation yksinkertaisuus on tärkeintä: yksi pyyntö, yksi vastaus, ei tilaa hallittavana. WebSocket on oikea tie, kun teksti pitenee, kun äänen on toistuttava sen tuottamisen aikana tai kun sisältö itse saapuu virtana, tyypillisesti kielimallin tuottamana, jonka puheeksi muunnat sen generoituessa.
Keskeiset asiat
- WebSocket-TTS:n avulla voit vastaanottaa suoratoistettua ääntä odottamatta generoinnin valmistumista
- Määritysparametrit annetaan yhteys-URL:n kyselymerkkijonossa
- Protokolla on yksinkertainen:
text.deltatekstin lähettämiseen,audio.deltaäänen vastaanottamiseen - WebSocket-istunnot on rajoitettu 50 samanaikaiseen tiimiä kohden; varaudu uudelleenyhteyden muodostamiseen
- Suosi WebSocketiä pitkille teksteille ja reaaliaikaisille kuuntelukokemuksille