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

Aloita Text-to-Speech-API:n käyttö

Oppitunti 6 / 14 Päivitetty 3. marraskuuta 2026 Keskitasoinen
Tällä sivulla
  1. Tekstiä sisään, ääntä ulos
  2. HTTP tai WebSocket: kaksi tapaa kutsua palvelua
  3. HTTP-pyynnön parametrit
  4. Valitse tulostusmuoto
  5. Kysy ääniluetteloa
  6. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n Text to Speech - ja Pricing-sivujen perusteella. Lähteet: Text to Speech · Pricing.

Tekstiä sisään, ääntä ulos

Grok Text-to-Speech -API tekee yhtä asiaa, ja se on siinä erinomainen: se muuntaa tekstin laadukkaaksi ääneksi. Kun Voice Agent hallitsee vuoropuhelua vuoroineen ja keskeytyksineen, TTS toimii ehdottomasti yksisuuntaisesti: lähetät tekstiä ja saat vastineeksi ääntä. Tämä yksinkertaisuus tekee siitä oikean työkalun tilanteisiin, joissa koneelle ei puhuta takaisin: kuten artikkeleiden lukemiseen, puhelinvastaajien tervehdyksiin, e-oppimismoduulien ääniraitoihin ja ääni-ilmoituksiin.

$15
per million characters
20
supported languages
28
built-in voices
60,000
max characters per request

HTTP tai WebSocket: kaksi tapaa kutsua palvelua

HTTP-tila on suoraviivaisin. Lähetät POST-pyynnön tekstilläsi, ja vastaus sisältää koko äänitiedoston, oletusarvoisesti MP3-muodossa:

curl -X POST "https://api.x.ai/v1/tts" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -o output.mp3 \
  -d '{
    "text": "Hello and welcome to Corsen Academy.",
    "voice_id": "ara",
    "language": "en"
  }'

Huomaa -o output.mp3: vastauksen sisältö on raakaa ääntä, ei linkkiä sisältävää JSON-käärettä. Tämä tila sopii täydellisesti taustagenerointiin, kuten yölliseen eräajoon, joka tuottaa artikkeleidesi ääniversiot, sillä kukaan ei odota tulosta näytön edessä.

WebSocket-tila vastaa eri tarpeeseen: haluat kuulla äänen ennen kuin koko teksti on syntetisoitu. Avaat yhteyden ja välität parametrit URL-osoitteessa:

wss://api.x.ai/v1/tts?language=en&voice=ara&codec=mp3

Lähetät sitten tekstin osissa käyttäen text.delta:a, ilmoitat lopun text.done:lla, ja ääni palaa base64-koodattuina palasina audio.delta:n kautta. Striimaus poistaa HTTP-tilan pituusrajoituksen ja ennen kaikkea mahdollistaa syntetisoinnin lennossa, mikä on välttämätöntä, kun tekstiä itsessään generoi vielä malli.

HTTP-pyynnön parametrit

ParametriTyyppiPakollinenKuvaus
textstringKylläMuunnettava teksti, enintään 60 000 merkkiä
voice_idstringEiKäytettävä ääni (oletus: eve)
languagestringKylläBCP-47-koodi (en, fr, de, …) tai auto
output_formatobjectEiKoodekki, näytetaajuus ja bittinopeus
speednumberEiToistonopeus välillä 0,7–1,5 (oletus: 1,0)

Kaksi kohtaa ansaitsee erityistä huomiota. language on pakollinen, mikä yllättää usein: palvelu ei arvaa tekstisi kieltä, ellei sitä nimenomaisesti pyydä arvolla auto. voice_id käyttää täsmälleen samoja ääniä kuin Voice Agent (28 sisäänrakennettua ääntä 3. marraskuuta 2026 mennessä, mukaan lukien eve, ara, rex, sal ja leo, sekä omat mukautetut äänesi), ja se ei välitä kirjainkoosta. Sama äänipersoona voi siis voimistaa sekä keskustelevaa agenttiasi että nauhoitettua sisältöäsi, mikä kannattaa hyödyntää brändin yhtenäisyyden vuoksi.

Valitse tulostusmuoto

Kenttä output_format ohjaa koodekkia ja laatua:

{
  "text": "Text to convert.",
  "voice_id": "rex",
  "language": "en",
  "output_format": {
    "codec": "wav",
    "sample_rate": 44100
  }
}

Valitse koodekki sen perusteella, mitä tiedostolle tehdään seuraavaksi. mp3 sopii yleiskäyttöön: se on hyvin pakattu ja toistuu kaikkialla, joten se on järkevä oletusarvo verkkosivustolle tai podcastille. wav on häviötön, joten raskaampi, mutta se on välttämätön, jos editori aikoo muokata raitaa uudelleen. pcm tuottaa raakaa ääntä prosessointiputkille, jotka eivät tarvitse säilöntää. Lopuksi mulaw ja alaw ovat G.711-puhelinkoodekkeja telejärjestelmille, jotka niitä vaativat.

Näytetaajuudet vaihtelevat 8 000–48 000 Hz:n välillä, oletuksena 24 000 Hz, mikä kattaa valtaosan käyttötarkoituksista. MP3:n bittinopeus on 32 000–192 000 bps, oletuksena 128 000. Nostaminen 192 000:een puheäänellesi lisää kuuntelukokemukseen mitättömän vähän ja kasvattaa tiedostojasi kolmanneksella: säästä tuo vara sisällölle, joka yhdistää musiikkia ja puhetta.

Kysy ääniluetteloa

API paljastaa kaksi kirjoitussuojattua päätepistettä, jotka täydentävät generointia. GET /v1/tts/voices palauttaa kaikki saatavilla olevat äänet metatietoineen, ja GET /v1/tts/voices/{voice_id} palauttaa samat kentät (voice_id, name, language) yksittäiselle äänelle; kunkin äänen sävy ja käyttötarkoitukset on kuvattu xAI:n Text to Speech -sivulla. Älä kovakoodaa äänien nimiä käyttöliittymääsi, vaan täytä äänivalitsimesi näistä päätepisteistä, jolloin sovelluksesi pysyy oikeana myös luettelon muuttuessa.

Keskeiset asiat

  • TTS muuntaa tekstin ääneksi HTTP:n (yksinkertainen) tai WebSocketin (striimaus) kautta
  • Hinta on 15 dollaria miljoonaa merkkiä kohden, enimmäismäärä 60 000 merkkiä HTTP-pyyntöä kohden
  • 28 sisäänrakennettua ääntä, viisi koodekkia ja kuusi näytetaajuutta tarjoavat paljon joustavuutta
  • WebSocket-tilassa ei ole rajoitusta tekstin kokonaispituudelle (jokainen delta on rajoitettu 60 000 merkkiin)
  • Kielen määrittämiseen vaaditaan BCP-47-koodi (tai auto automaattista tunnistusta varten)