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

TTS-pyynnön parametrit

Oppitunti 2 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Hienosäädä puheesynteesiäsi
  2. text-parametri
  3. voice_id-parametri
  4. language-parametri
  5. output_format-parametri
  6. speed-parametri
  7. Suositellut yhdistelmät
  8. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n Text to Speech -sivun ja Voice API -viitteen perusteella. Lähteet: Text to Speech · Voice API.

Hienosäädä puheesynteesiäsi

POST /v1/tts -päätepiste pyörii neljän JSON-pyyntörunnon pääparametrin sekä muutaman valinnaisen asetuksen ympärillä. Jokainen niistä antaa sinulle tarkan hallinnan tuotetusta äänestä, ja niiden ymmärtäminen mahdollistaa synteesin räätälöinnin käyttötarkoitukseesi.

text-parametri

language-parametrin lisäksi text on ainoa pakollinen parametri. Se hyväksyy merkkijonon, jonka pituus on enintään 60 000 merkkiä ja joka voi sisältää pelkkää tekstiä tai ilmaisumerkkejä (käsitellään seuraavassa osiossa).

{
  "text": "Hello and welcome. Today, we're going to talk about artificial intelligence."
}

Jos merkkimäärä ylittää 60 000, HTTP-pyyntö hylätään. Pidempiä tekstejä varten xAI suosittelee WebSocket-yhteyden käyttöä, jossa ei ole kokonaispituusrajoitusta (tunnit 9–12), tai tekstin jakamista osiin, joiden ääniraidat yhdistetään jälkikäteen. Jaa teksti luonteviin kohtiin (lauseiden tai kappaleiden loppuun) sujuvan lopputuloksen saavuttamiseksi.

voice_id-parametri

Tämä parametri määrittää synteesissä käytettävän äänen. Se on valinnainen, ja oletusarvo on eve. Tunnisteet eivät ole kirjainkokoherkkiä: Eve, EVE ja eve ovat samanarvoisia.

xAI tarjoaa 28 sisäänrakennettua ääntä (tilanne 3.11.2026), sama määrä kuin voice agentissa, sekä Custom Voices API:n avulla luotuja mukautettuja ääniä. xAI:n kuvailemat viisi alkuperäistä ääntä ovat:

  • eve: energinen ja iloinen, brittiaksentti
  • ara: lämmin ja ystävällinen
  • rex: itsevarma ja selkeä
  • sal: sujuva ja tasapainoinen
  • leo: auktoriteettinen ja voimakas, brittiaksentti

Muut 23 ääntä (carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora ja liora) on kuvattu käyttötarkoituksineen xAI:n Text to Speech -sivulla; GET /v1/tts/voices palauttaa nykyisen listan (tunti 3).

{
  "text": "Welcome to this tutorial.",
  "voice_id": "rex",
  "language": "en"
}

xAI:n mukaan kaikki äänet puhuvat kaikkia tuettuja kieliä. Äänen valinta ei vaikuta hintaan, joka perustuu merkkien määrään.

language-parametri

Tämä parametri on pakollinen. Se hyväksyy BCP-47-koodin tai erityisarvon auto automaattista kielen tunnistusta varten.

Tuetut 20 kieltä ovat:

KoodiKieliKoodiKieli
enenglantikokorea
frranskahihindi
desaksabnbengali
es-ESespanja (Espanja)ar-EGarabia (Egypti)
es-MXespanja (Meksiko)ar-SAarabia (Saudi-Arabia)
pt-BRportugali (Brasilia)ar-AEarabia (Yhdistyneet arabiemiirikunnat)
pt-PTportugali (Portugali)trturkki
ititaliaidindonesia
ruvenäjävivietnam
zhkiinajajapani

Automaattinen tunnistus (auto) toimii hyvin yksikielisissä teksteissä, mutta useampaa kieltä sekoittavissa teksteissä ilmoita pääkieli eksplisiittisesti.

output_format-parametri

Tämä valinnainen parametri on JSON-objekti, joka ohjaa äänen ulostuloformaattia. Siinä on kolme aliparametria.

codec

Codec määrittää koodausformaatin:

  • mp3 (oletus): pakattu formaatti, ihanteellinen verkkoon ja suoratoistoon
  • wav: häviötön formaatti, parempi laatu mutta suuremmat tiedostot
  • pcm: raakaääni ilman otsikkoa, käsittelyputkia varten
  • mulaw / ulaw: G.711 mu-law -codec puhelinkäyttöön
  • alaw: G.711 A-law -codec puhelinkäyttöön

sample_rate

Näytteenottotaajuus hertseinä. Hyväksytyt arvot: 8000, 16000, 22050, 24000 (oletus), 44100, 48000.

bit_rate

Bittinopeus bitteinä sekunnissa, vain MP3-codecia varten. Hyväksytyt arvot: 32000, 64000, 96000, 128000 (oletus), 192000.

{
  "text": "High-quality audio for production.",
  "voice_id": "ara",
  "language": "en",
  "output_format": {
    "codec": "wav",
    "sample_rate": 48000
  }
}

speed-parametri

speed asettaa toistonopeuden: 1.0 on normaali nopeus (oletus), ja alue ulottuu välille 0.7–1.5 Hieman hitaampi tahti auttaa tiheässä oppisisällössä; yli 1.2 nopeuksilla kuuntele tulos aina uudelleen.

Suositellut yhdistelmät

Käyttötarkoituscodecsample_ratebit_rate
Web / suoratoistomp324000128000
Äänituotantowav48000—
VoIP-puhelinliikennemulaw8000—
ML-putkipcm16000—

Keskeiset asiat

  • text ja language ovat ainoat pakolliset parametrit
  • voice_id on valinnainen (oletus: eve) eikä ole kirjainkokoherkkä
  • output_format ohjaa codecia, näytteenottotaajuutta ja bittinopeutta; speed asettaa nopeuden (0,7–1,5)
  • MP3 muodossa 24 kHz / 128 kbps on hyvä oletustasapaino laadun ja koon välillä
  • Puhelinkäyttöä varten käytä mulaw- tai alaw-formaattia 8 kHz taajuudella