Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Listar as vozes disponíveis

Aula 3 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Descubra vozes programaticamente
  2. GET /v1/tts/voices
  3. GET /v1/tts/voices/{voice_id}
  4. Escolha a voz certa
  5. Integre a seleção de vozes na sua aplicação
  6. Boas práticas
  7. Pontos-chave

Atualizado em 3 de novembro de 2026, com base na referência da API de Voz da xAI e na página Text to Speech: a resposta do GET /v1/tts/voices inclui voice_id, name e language, e a xAI oferece 28 vozes integradas. Fontes: Voice API · Text to Speech.

Descubra vozes programaticamente

Em vez de codificar rigidamente a lista de vozes na sua aplicação, a API da xAI disponibiliza um endpoint dedicado para obter as vozes disponíveis de forma dinâmica. Desta forma, mantém-se atualizado sempre que são adicionadas novas vozes.

GET /v1/tts/voices

Este endpoint devolve a lista de todas as vozes disponíveis para TTS. Não requer parâmetros no corpo do pedido.

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

A resposta é um objeto JSON que contém um array voices. De acordo com a referência da API, cada voz possui três campos: voice_id, o ID em minúsculas a passar nos seus pedidos; name, um nome de exibição; e language, um código de idioma que pode ser nulo.

Estrutura da resposta

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

As reticências representam valores que a referência não fornece como exemplos: imprima a resposta real uma vez antes de depender dela. O tom e os casos de uso de cada voz não constam nesta resposta; são descritos na página Text to Speech da xAI.

GET /v1/tts/voices/{voice_id}

Para obter os detalhes de uma voz específica, adicione o seu ID ao caminho:

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

Esta chamada devolve os mesmos campos (voice_id, name, language) apenas para a voz solicitada.

Escolha a voz certa

A xAI oferece 28 vozes integradas (a partir de 3 de novembro de 2026) e, para a maioria delas, descreve para que fins são mais adequadas. Algumas indicações dessa página:

  • Conteúdo educativo: luna, cosmo ou lumen, listadas para educação
  • Apoio ao cliente: carina, iris, rigel, celeste, castor, naksh ou aurora, listadas para apoio
  • Publicidade e demonstrações: altair, zenith, perseus, kepler ou lumen, listadas para publicidade; eve, enérgica e otimista, permanece como a voz padrão
  • Narração e audiolivros: orion, zagan, altair, perseus ou lux
  • Bem-estar: carina, helios, lux ou liora

As cinco vozes originais (eve, ara, rex, sal, leo) não têm casos de uso listados: a xAI descreve-as apenas como enérgicas e otimistas (sotaque britânico), calorosas e amigáveis, confiantes e claras, suaves e equilibradas, e autoritárias e poderosas (sotaque britânico).

Integre a seleção de vozes na sua aplicação

Eis um exemplo que carrega as vozes disponíveis dinamicamente:

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

Esta abordagem protege-o contra erros de digitação nos IDs das vozes e permite oferecer aos seus utilizadores uma lista atualizada.

Boas práticas

  • Faça cache da lista de vozes: o endpoint /v1/tts/voices não muda frequentemente, pelo que uma chamada no arranque da sua aplicação é suficiente
  • Ofereça uma pré-visualização: permita aos seus utilizadores ouvir uma amostra de cada voz antes de escolherem
  • Guarde a preferência: assim que um utilizador escolher uma voz, guarde essa escolha para sessões futuras
  • Teste no idioma de destino: uma voz que soa bem em inglês pode soar diferente noutro idioma. Teste sempre no idioma da sua aplicação

Pontos-chave

  • GET /v1/tts/voices lista todas as vozes disponíveis com os seus metadados
  • GET /v1/tts/voices/{voice_id} fornece os detalhes de uma voz específica
  • Estão disponíveis 28 vozes integradas; o seu tom e casos de uso são descritos na página Text to Speech da xAI
  • A resposta de GET /v1/tts/voices fornece voice_id, name e language para cada voz
  • Carregue as vozes dinamicamente em vez de as codificar rigidamente