Премини към основното съдържание
Български— Изберете език
Меню

Списък с наличните гласове

Урок 3 от 14 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Програмно откриване на гласовете
  2. GET /v1/tts/voices
  3. GET /v1/tts/voices/{voice_id}
  4. Избор на подходящия глас
  5. Вграждане на избора на глас във вашето приложение
  6. Най-добри практики
  7. Ключови изводи

Обновено на 3 ноември 2026 г. въз основа на справочника за xAI Voice API и страницата Text to Speech: отговорът от GET /v1/tts/voices съдържа voice_id, name и language, а xAI предлага 28 вградени гласа. Източници: Voice API · Text to Speech.

Програмно откриване на гласовете

Вместо да кодирате списъка с гласове статично във вашето приложение, API на xAI предоставя специализиран крайна точка за динамично извличане на наличните гласове. По този начин ще сте винаги актуални, когато се добавят нови гласове.

GET /v1/tts/voices

Тази крайна точка връща списък с всички налични гласове за TTS. Тя не изисква параметри в тялото на заявката.

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

Отговорът е JSON обект, съдържащ масив voices. Според справочника на API, всеки глас има три полета: voice_id – идентификаторът в малки букви, който предавате във вашите заявки; name – име за показване; и language – код на езика, който може да бъде null.

Структура на отговора

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

Точките заместват стойности, които справочникът не дава като примери: разпечатайте реалния отговор веднъж, преди да разчитате на него. Тонът и случаите на употреба за всеки глас не са включени в този отговор; те са описани на страницата Text to Speech на xAI.

GET /v1/tts/voices/{voice_id}

За да получите детайли за конкретен глас, добавете неговия ID към пътя:

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

Това извикване връща същите полета (voice_id, name, language) само за поискания глас.

Избор на подходящия глас

xAI предлага 28 вградени гласа (към 3 ноември 2026 г.) и за повечето от тях описва за какво са най-подходящи. Ето няколко насоки от тази страница:

  • Образователно съдържание: luna, cosmo или lumen, изброени за образование
  • Поддръжка на клиенти: carina, iris, rigel, celeste, castor, naksh или aurora, изброени за поддръжка
  • Реклама и демонстрации: altair, zenith, perseus, kepler или lumen, изброени за реклама; eve, енергичен и позитивен, остава гласът по подразбиране
  • Разказване и аудиокниги: orion, zagan, altair, perseus или lux
  • Благополучие: carina, helios, lux или liora

Петте оригинални гласа (eve, ara, rex, sal, leo) нямат изброени случаи на употреба: xAI ги описва само като енергични и позитивни (британски акцент), топли и приятелски, уверени и ясни, гладки и балансирани, както и авторитетни и мощни (британски акцент).

Вграждане на избора на глас във вашето приложение

Ето пример, който зарежда наличните гласове динамично:

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

Този подход ви предпазва от правописни грешки в ID-тата на гласовете и ви позволява да предложите на потребителите си актуален списък.

Най-добри практики

  • Кеширайте списъка с гласове: крайната точка /v1/tts/voices не се променя често, така че едно извикване при стартиране на приложението е достатъчно
  • Предложете предварителен преглед: позволете на потребителите да чуят мостра от всеки глас, преди да направят избор
  • Запазете предпочитанието: след като потребителят избере глас, съхранете избора за бъдещи сесии
  • Тествайте на целевия език: глас, който звучи отлично на английски, може да звучи различно на друг език. Винаги тествайте на езика на вашето приложение

Ключови изводи

  • GET /v1/tts/voices изброява всички налични гласове с техните метаданни
  • GET /v1/tts/voices/{voice_id} предоставя детайли за конкретен глас
  • Налични са 28 вградени гласа; техният тон и случаи на употреба са описани на страницата Text to Speech на xAI
  • Отговорът от GET /v1/tts/voices дава voice_id, name и language за всеки глас
  • Зареждайте гласовете динамично, вместо да ги кодирате статично