Listar as vozes disponíveis
Nesta página
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/voicesincluivoice_id,nameelanguage, 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,cosmooulumen, listadas para educação - Apoio ao cliente:
carina,iris,rigel,celeste,castor,nakshouaurora, listadas para apoio - Publicidade e demonstrações:
altair,zenith,perseus,kepleroulumen, listadas para publicidade;eve, enérgica e otimista, permanece como a voz padrão - Narração e audiolivros:
orion,zagan,altair,perseusoulux - Bem-estar:
carina,helios,luxouliora
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/voicesnã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/voiceslista todas as vozes disponíveis com os seus metadadosGET /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/voicesfornecevoice_id,nameelanguagepara cada voz - Carregue as vozes dinamicamente em vez de as codificar rigidamente