Endpointul POST /v1/tts
Pe această pagină
Actualizat la 3 noiembrie 2026, pe baza paginii xAI Text to Speech, a referinței API Voice și a paginii de Prețuri. Surse: Text to Speech · Voice API · Pricing.
Transformați textul în audio cu API-ul Grok
API-ul Text-to-Speech de la xAI transformă orice text în audio cu sunet natural printr-o singură apelare HTTP. Punctul principal de intrare este POST /v1/tts, care primește textul dumneavoastră și returnează direct un fișier audio binar.
Structura cererii
Trimiteți o cerere POST către https://api.x.ai/v1/tts cu un corp JSON. Iată un exemplu minimal folosind curl:
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
Serverul răspunde direct cu fișierul audio binar în corpul răspunsului. Nu există nicio anvelopă JSON în jurul său: primiți octeții brute ai fișierului audio.
Autentificare
Ca în cazul fiecărui endpoint API xAI, includeți cheia API în antetul Authorization în format Bearer:
Authorization: Bearer xai-your-api-key
Corpul cererii
Corpul JSON se articulează în jurul a patru parametri principali:
text(obligatoriu): textul de convertit, până la 60.000 de caractere. Suportă etichetele expresive pe care le veți învăța în lecțiile următoarevoice_id(opțional): ID-ul vocii. Valoarea implicită esteeve. Valorile nu fac distincție între majuscule și minusculelanguage(obligatoriu): codul limbii în format BCP-47 (en,fr,de, …) sauautopentru detectare automatăoutput_format(opțional): un obiect care configurează codec-ul, rata de eșantionare și rata de biți
Alte setări, toate opționale, completează cererea: speed (viteza de redare, de la 0,7 la 1,5, implicit 1,0), replace (un tabel de substituții care corectează pronunția unui cuvânt fără a modifica textul trimis), with_timestamps (marcaje temporale per caracter), text_normalization (scrierea cu litere a numerelor, abrevierilor și simbolurilor înainte de sinteză) și optimize_streaming_latency ("1" pentru a scurta așteptarea înainte de primul fragment audio, cu costul unei ușoare pierderi de calitate la joncțiuni).
Răspunsul HTTP
În caz de succes (status 200), serverul returnează fișierul audio cu tipul de conținut care corespunde formatului solicitat:
audio/mpegpentru MP3 (implicit)audio/wavpentru WAVaudio/pcmpentru PCM brutaudio/basicpentru G.711 μ-law (mulaw)audio/alawpentru G.711 A-law (alaw)
Răspunsul nu conține metadate, doar octeți audio. Singura excepție este with_timestamps: în acest caz, răspunsul devine un obiect JSON care conține audio-ul în base64, durata sa și marcajul temporal pentru fiecare caracter. Puteți scrie răspunsul direct într-un fișier sau îl puteți transmite în flux către un player audio.
Exemplu în Python
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)
Exemplu în JavaScript (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));
Prețuri
Serviciul TTS costă 15 USD per milion de caractere (prețuri xAI la data de 3 noiembrie 2026). Sunteți facturat pentru caracterele trimise în câmpul text, inclusiv etichetele expresive; un tabel replace nu modifică acest număr. Cu o medie de 1.000 de caractere per cerere, costul se ridică la aproximativ 0,015 USD per apel.
Puncte cheie
- Endpointul
POST /v1/ttseste punctul principal de intrare pentru sinteza vocală - Răspunsul este un fișier audio binar, nu JSON
- Textul este limitat la 60.000 de caractere per cerere HTTP; WebSocket nu are o limită totală
- Autentificarea se face cu antetul
Authorization: Bearer - Costul este de 15 USD per milion de caractere