Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Loetle saadaolevad hääled

Õppetund 3 / 14 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Avasta hääled programmeeritavalt
  2. GET /v1/tts/voices
  3. GET /v1/tts/voices/{voice_id}
  4. Vali õige hääl
  5. Loo hääle valik oma rakendusse
  6. Parimad tavad
  7. Peamised punktid

Uuendatud 3. novembril 2026, tuginedes xAI Voice API referentsile ja lehele Text to Speech: päringu GET /v1/tts/voices vastus sisaldab välju voice_id, name ja language; xAI pakub 28 sisseehitatud häält. Allikad: Voice API · Text to Speech.

Avasta hääled programmeeritavalt

Selle asemel, et kodeerida häälte loend oma rakendusse jäigalt, pakub xAI API spetsiaalset lõpppunkti saadaolevate häälte dünaamiliseks hankimiseks. Nii püsid kursis, kui lisanduvad uued hääled.

GET /v1/tts/voices

See lõpppunkt tagastab kõigi TTS-i jaoks saadaolevate häälte loendi. Päringu keha parameetreid ei vaja.

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

Vastuseks on JSON-objekt, mis sisaldab massiivi voices. API referentsi kohaselt on igal häälel kolm välja: voice_id (väiketähtedes ID, mille edastad oma päringutes), name (kuvatav nimi) ja language (keelekood, mis võib olla null).

Vastuse struktuur

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

Kolmepunktid tähistavad väärtusi, mida referents näidetena ei paku: prindi tegelik vastus üks kord enne, kui sellele tugined. Iga hääle tooni ja kasutusjuhte selles vastuses ei kirjeldata; need on toodud xAI lehel Text to Speech.

GET /v1/tts/voices/{voice_id}

Kindla hääle üksikasjade saamiseks lisa selle ID teeossa:

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

See kutse tagastab samad väljad (voice_id, name, language) ainult taotletud hääle kohta.

Vali õige hääl

xAI pakub (seisuga 3. november 2026) 28 sisseehitatud häält ja enamiku puhul kirjeldatakse, milleks need kõige paremini sobivad. Mõned soovitused sellelt lehelt:

  • Haridussisu: luna, cosmo või lumen (loetletud hariduse kategoorias)
  • Klienditugi: carina, iris, rigel, celeste, castor, naksh või aurora (loetletud toe kategoorias)
  • Reklaam ja demo: altair, zenith, perseus, kepler või lumen (loetletud reklaami kategoorias); eve on energiline ja rõõmsameelne ning jääb vaikimisi hääleks
  • Jutustamine ja heliraamatud: orion, zagan, altair, perseus või lux
  • Heaolu: carina, helios, lux või liora

Viiele algsele häälele (eve, ara, rex, sal, leo) pole konkreetseid kasutusjuhte määratud: xAI kirjeldab neid vaid kui energilist ja rõõmsameelset (Briti aktsent), sooja ja sõbralikku, enesekindlat ja selget, sujuvat ja tasakaalukat ning autoriteetset ja võimsat (Briti aktsent).

Loo hääle valik oma rakendusse

Siin on näide, kuidas laadida saadaolevad hääled dünaamiliselt:

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

See lähenemine kaitseb sind hääle ID-de trükivigade eest ja võimaldab pakkuda kasutajatele ajakohast loendit.

Parimad tavad

  • Puhverda häälte loend: lõpppunkt /v1/tts/voices ei muutu sageli, seega piisab ühest kutsest rakenduse käivitamisel
  • Paku eelkuulamist: lase kasutajatel enne valikut kuulata iga hääle näidist
  • Salvesta eelistus: kui kasutaja on hääle valinud, salvesta see valik tulevaste sessioonide jaoks
  • Testi sihtkeeles: hääl, mis kõlab inglise keeles suurepäraselt, võib teises keeles kõlada teisiti. Testi alati oma rakenduse keeles

Peamised punktid

  • GET /v1/tts/voices loetleb kõik saadaolevad hääled koos nende metaandmetega
  • GET /v1/tts/voices/{voice_id} annab kindla hääle üksikasjad
  • Saadaval on 28 sisseehitatud häält; nende toon ja kasutusjuhud on kirjeldatud xAI lehel Text to Speech
  • Vastus päringule GET /v1/tts/voices annab iga hääle kohta voice_id, name ja language
  • Laadi hääled dünaamiliselt, mitte ära kodeeri neid jäigalt