Salt la conținutul principal
Română— Alege o limbă
Meniu

Listarea vocilor disponibile

Lecția 3 din 14 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Descoperirea vocilor programatic
  2. GET /v1/tts/voices
  3. GET /v1/tts/voices/{voice_id}
  4. Alegerea vocii potrivite
  5. Integrarea selecției vocilor în aplicația dumneavoastră
  6. Cele mai bune practici
  7. Puncte cheie

Actualizat la 3 noiembrie 2026, pe baza referinței API Voice de la xAI și a paginii Text to Speech: răspunsul la GET /v1/tts/voices conține voice_id, name și language, iar xAI oferă 28 de voci integrate. Surse: Voice API · Text to Speech.

Descoperirea vocilor programatic

În loc să codificați rigid lista de voci în aplicația dumneavoastră, API-ul xAI pune la dispoziție un endpoint dedicat pentru preluarea dinamică a vocilor disponibile. Astfel, rămâneți la curent ori de câte ori sunt adăugate voci noi.

GET /v1/tts/voices

Acest endpoint returnează lista tuturor vocilor disponibile pentru TTS. Nu necesită niciun parametru în corpul cererii.

curl -X GET "https://api.x.ai/v1/tts/voices" \
  -H "Authorization: Bearer $XAI_API_KEY"

Răspunsul este un obiect JSON care conține un tablou voices. Conform referinței API, fiecare voce are trei câmpuri: voice_id, identificatorul cu litere mici pe care trebuie să îl transmiteți în cererile dumneavoastră; name, un nume afișat; și language, un cod de limbă care poate fi null.

Structura răspunsului

{
  "voices": [
    {"voice_id": "eve", "name": "…", "language": "…"},
    {"voice_id": "ara", "name": "…", "language": "…"}
  ]
}

Punctele de suspensie înlocuiesc valorile pe care referința nu le oferă ca exemple: afișați răspunsul real o dată înainte de a vă baza pe el. Tonul și cazurile de utilizare ale fiecărei voci nu se regăsesc în acest răspuns; acestea sunt descrise pe pagina xAI Text to Speech.

GET /v1/tts/voices/{voice_id}

Pentru a obține detaliile unei voci specifice, adăugați ID-ul acesteia în calea URL-ului:

curl -X GET "https://api.x.ai/v1/tts/voices/rex" \
  -H "Authorization: Bearer $XAI_API_KEY"

Această apelare returnează aceleași câmpuri (voice_id, name, language) doar pentru vocea solicitată.

Alegerea vocii potrivite

xAI oferă 28 de voci integrate (la data de 3 noiembrie 2026) și, pentru majoritatea acestora, descrie scenariile pentru care sunt cele mai potrivite. Iată câteva indicații de pe acea pagină:

  • Conținut educațional: luna, cosmo sau lumen, listate pentru educație
  • Suport pentru clienți: carina, iris, rigel, celeste, castor, naksh sau aurora, listate pentru suport
  • Publicitate și demo-uri: altair, zenith, perseus, kepler sau lumen, listate pentru publicitate; eve, energică și plină de entuziasm, rămâne vocea implicită
  • Narațiune și audiobooks: orion, zagan, altair, perseus sau lux
  • Bunăstare (Wellness): carina, helios, lux sau liora

Cele cinci voci originale (eve, ara, rex, sal, leo) nu au cazuri de utilizare listate: xAI le descrie doar ca fiind energice și pline de entuziasm (accent britanic), calde și prietenoase, încrezătoare și clare, fluide și echilibrate, respectiv autoritare și puternice (accent britanic).

Integrarea selecției vocilor în aplicația dumneavoastră

Iată un exemplu care încarcă vocile disponibile dinamic:

import requests

def get_available_voices(api_key):
    response = requests.get(
        "https://api.x.ai/v1/tts/voices",
        headers={"Authorization": f"Bearer {api_key}"}
    )
    response.raise_for_status()
    return response.json()["voices"]

def synthesize(api_key, text, voice_id="eve", language="en"):
    voices = get_available_voices(api_key)
    valid_ids = [v["voice_id"] for v in voices]

    if voice_id.lower() not in valid_ids:
        raise ValueError(f"Unknown voice '{voice_id}'. Available: {valid_ids}")

    response = requests.post(
        "https://api.x.ai/v1/tts",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"text": text, "voice_id": voice_id, "language": language}
    )
    return response.content

Această abordare vă protejează împotriva erorilor de tastare în ID-urile vocilor și vă permite să le oferiți utilizatorilor o listă actualizată.

Cele mai bune practici

  • Stocați în cache lista de voci: endpoint-ul /v1/tts/voices nu se modifică des, astfel încât o singură apelare la pornirea aplicației este suficientă
  • Oferiți o previzualizare: permiteți utilizatorilor să asculte un sample pentru fiecare voce înainte de a o alege
  • Salvați preferința: odată ce un utilizator a ales o voce, stocați această alegere pentru sesiunile viitoare
  • Testați în limba țintă: o voce care sună excelent în engleză poate suna diferit într-o altă limbă. Testați întotdeauna în limba aplicației dumneavoastră

Puncte cheie

  • GET /v1/tts/voices listează toate vocile disponibile împreună cu metadatele lor
  • GET /v1/tts/voices/{voice_id} oferă detaliile unei voci specifice
  • Sunt disponibile 28 de voci integrate; tonul și cazurile lor de utilizare sunt descrise pe pagina xAI Text to Speech
  • Răspunsul la GET /v1/tts/voices oferă voice_id, name și language pentru fiecare voce
  • Încărcați vocile dinamic în loc să le codificați rigid