A POST /v1/tts végpont
Ezen az oldalon
Frissítve: 2026. november 3., az xAI Text to Speech oldala, a Voice API referenciája és az Árazás oldal alapján. Források: Text to Speech · Voice API · Pricing.
Szöveg átalakítása hanggá a Grok API-val
Az xAI Text-to-Speech API egyetlen HTTP-hívással alakít át bármilyen szöveget természetesen hangzó audióvá. A fő belépési pont a POST /v1/tts, amely fogadja a szövegedet, és közvetlenül bináris hangfájlt ad vissza.
A kérés felépítése
Egy POST kérést küldesz a https://api.x.ai/v1/tts címre JSON törzzsel. Íme egy minimális példa curllel:
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
A szerver közvetlenül a válasz törzsében adja vissza a bináris hangfájlt. Nincs körülötte JSON burkoló: a hangfájl nyers bájtsorozatát kapod meg.
Hitelesítés
Minden xAI API-végponthoz hasonlóan az API-kulcsodat a Authorization fejlécben kell megadnod Bearer formátumban:
Authorization: Bearer xai-your-api-key
Kérés törzse
A JSON törzs négy fő paraméter köré épül:
text(kötelező): az átalakítandó szöveg, legfeljebb 60 000 karakterig. Támogatja a kifejező címkéket, amelyekkel a következő leckékben ismerkedsz majd megvoice_id(opcionális): a hang azonosítója. Alapértelmezett értéke:eve. Az értékek nem különböztetik meg a kis- és nagybetűketlanguage(kötelező): a nyelvi kód BCP-47 formátumban (en,fr,de, …) vagyautoaz automatikus észleléshezoutput_format(opcionális): egy objektum, amely konfigurálja a kodeket, a mintavételezési rátát és a bitrátát
További, szintén opcionális beállítások egészítik ki a kérést: speed (lejátszási sebesség, 0,7 és 1,5 között, alapértelmezetten 1,0), replace (helyettesítési tábla, amely javítja egy szó kiejtését anélkül, hogy megváltoztatná a küldött szöveget), with_timestamps (karakterenkénti időbélyegek), text_normalization (számok, rövidítések és szimbólumok kiírása szintézis előtt), valamint az optimize_streaming_latency ("1" értékkel csökkenthető a várakozási idő az első hangrészlet előtt, cserébe az illesztéseknél minimális minőségromlás lép fel).
A HTTP válasz
Siker esetén (200-as státuszkód) a szerver visszaadja a hangfájlt azzal a tartalomtípussal, amely megfelel a kért formátumnak:
audio/mpegMP3-hoz (alapértelmezett)audio/wavWAV-hozaudio/pcmnyers PCM-hezaudio/basicG.711 μ-law (mulaw) kódoláshozaudio/alawG.711 A-law (alaw) kódoláshoz
A válasz nem tartalmaz metaadatokat, csak a hangbájtokat. Az egyetlen kivétel a with_timestamps: ekkor a válasz egy JSON-objektum lesz, amely base64 kódolásban tartalmazza a hangot, annak időtartamát és minden egyes karakter időbélyegét. A választ közvetlenül fájlba írhatod, vagy audiólejátszóba streamelheted.
Python példa
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 példa (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));
Árazás
A TTS költsége millió karakterenként 15 USD (xAI árazás 2026. november 3. szerint). A text mezőben elküldött karakterek után számolnak fel díjat, beleértve a kifejező címkéket is; a replace tábla nem módosítja ezt a számlálást. Átlagosan 1000 karakterenkénti kéréssel ez hívásonként körülbelül 0,015 USD-t jelent.
Főbb megállapítások
- A
POST /v1/ttsvégpont a beszédszintézis fő belépési pontja - A válasz egy bináris hangfájl, nem JSON
- A szöveg HTTP-kérésenként 60 000 karakterre korlátozódik; WebSocket esetén nincs teljes limit
- A hitelesítés az
Authorization: Bearerfejléccel történik - A költség millió karakterenként 15 USD