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

Päätepiste POST /v1/tts

Oppitunti 1 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Muuta teksti ääneksi Grok API:n avulla
  2. Pyynnön rakenne
  3. HTTP-vastaus
  4. Hinnoittelu
  5. Keskeiset asiat

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

Muuta teksti ääneksi Grok API:n avulla

xAI:n Text-to-Speech-API muuttaa minkä tahansa tekstin luonnolliselta kuulostavaksi ääneksi yhdellä HTTP-kutsulla. Tärkein sisäänmenopiste on POST /v1/tts, joka ottaa vastaan tekstisi ja palauttaa suoraan binäärimuotoisen äänitiedoston.

60,000
Merkkien enimmäismäärä pyyntöä kohden
28
Sisäänrakennettuja ääniä
20
Tuettuja kieliä
$15
Miljoonaa merkkiä kohden

Pyynnön rakenne

Lähetät POST-pyynnön osoitteeseen https://api.x.ai/v1/tts JSON-rungolla. Tässä on minimaalinen esimerkki curlilla:

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

Palvelin vastaa palauttamalla binäärimuotoisen äänitiedoston suoraan vastauksen rungossa. Sen ympärillä ei ole JSON-koteloa: saat äänitiedoston raakatavut sellaisinaan.

Todennus

Kuten kaikissa muissakin xAI:n API-päätepisteissä, sisällytä API-avaimesi Authorization-otsikkoon Bearer-muodossa:

Authorization: Bearer xai-your-api-key

Pyynnön runko

JSON-runko pyörii neljän pääparametrin ympärillä:

  • text (pakollinen): muunnettava teksti, enintään 60 000 merkkiä. Se tukee ilmaisutageja, joista opit lisää seuraavissa oppitunneissa.
  • voice_id (valinnainen): äänen tunniste. Oletusarvo on eve. Arvot eivät ole kirjainkokoherkkiä.
  • language (pakollinen): kielikoodi BCP-47-muodossa (en, fr, de, …) tai auto automaattista tunnistusta varten.
  • output_format (valinnainen): objekti, joka määrittää koodekin, näytteenottotaajuuden ja bittinopeuden.

Muut asetukset, jotka kaikki ovat valinnaisia, täydentävät pyyntöä: speed (toistonopeus, välillä 0,7–1,5, oletus 1,0), replace (korvaustaulukko, joka korjaa sanan ääntämisen muuttamatta lähetettyä tekstiä), with_timestamps (merkkikohtaiset aikaleimat), text_normalization (numeroiden, lyhenteiden ja symbolien kirjoittaminen auki ennen synteesiä) ja optimize_streaming_latency ("1" lyhentää odotusaikaa ennen ensimmäistä äänipätkää hieman laadun kärsiessä liitoskohdissa).

HTTP-vastaus

Onnistuessaan (tila 200) palvelin palauttaa äänitiedoston pyydettyä muotoa vastaavalla sisältötyypillä:

  • audio/mpeg MP3:lle (oletus)
  • audio/wav WAV:lle
  • audio/pcm raakalle PCM:lle
  • audio/basic G.711 μ-lawille (mulaw)
  • audio/alaw G.711 A-lawille (alaw)

Vastaus ei sisällä metadataa, vain äänitavuja. Ainoa poikkeus on with_timestamps: tällöin vastaus on JSON-objekti, joka sisältää äänen base64-koodattuna, sen keston ja kunkin merkin aikaleiman. Voit kirjoittaa vastauksen suoraan tiedostoon tai suoratoistaa sen äänisoittimeen.

Python-esimerkki

import requests

response = requests.post(
    "https://api.x.ai/v1/tts",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "text": "Here's an example of speech synthesis.",
        "voice_id": "rex",
        "language": "en"
    }
)

with open("output.mp3", "wb") as f:
    f.write(response.content)

JavaScript-esimerkki (Node.js)

const response = await fetch("https://api.x.ai/v1/tts", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Here's an example of speech synthesis.",
    voice_id: "rex",
    language: "en"
  })
});

const buffer = await response.arrayBuffer();
fs.writeFileSync("output.mp3", Buffer.from(buffer));

Hinnoittelu

TTS maksaa 15 dollaria miljoonaa merkkiä kohden (xAI:n hinnasto 3. marraskuuta 2026). Sinulta veloitetaan text-kenttään lähettämäsi merkit, ilmaisutagit mukaan lukien; replace-taulukko ei muuta tätä määrää. Keskimäärin 1 000 merkin pyynnöillä hinta on noin 0,015 dollaria kutsua kohden.

Keskeiset asiat

  • POST /v1/tts on puheensynteesin tärkein sisäänmenopiste
  • Vastaus on binäärinen äänitiedosto, ei JSON
  • Tekstin raja on 60 000 merkkiä HTTP-pyyntöä kohden; WebSocketilla ei ole kokonaisrajaa
  • Todennus tapahtuu Authorization: Bearer -otsikolla
  • Hinta on 15 dollaria miljoonaa merkkiä kohden