Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

TTS-suoratoisto WebSocketin yli

Oppitunti 9 / 14 Päivitetty 3. marraskuuta 2026 Keskitasoinen
Tällä sivulla
  1. Miksi suoratoisto muuttaa kokemusta
  2. Avaa yhteys
  3. Viestintäprotokolla
  4. Täydellinen toteutus
  5. Huomioitavat rajat
  6. HTTP vai WebSocket
  7. Keskeiset asiat

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

MittariArvo
Tekstiä per deltaEnintään 60 000 merkkiä
Tekstiä yhteensäRajoittamaton
Samanaikaiset istunnot50 tiimiä kohden
Istuntolupa600 sekuntia
Yhteyden aikakatkaisuEi 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.delta tekstin 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