Päätepiste POST /v1/tts
Tällä sivulla
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.
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 oneve. Arvot eivät ole kirjainkokoherkkiä.language(pakollinen): kielikoodi BCP-47-muodossa (en,fr,de, …) taiautoautomaattista 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/mpegMP3:lle (oletus)audio/wavWAV:lleaudio/pcmraakalle PCM:lleaudio/basicG.711 μ-lawille (mulaw)audio/alawG.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/ttson 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