Parâmetros do pedido TTS
Nesta página
Atualizado a 3 de novembro de 2026, com base na página Text to Speech da xAI e na referência da API de Voz. Fontes: Text to Speech · Voice API.
Afine a sua síntese de voz
O endpoint POST /v1/tts centra-se em quatro parâmetros principais no corpo do pedido JSON, além de algumas definições opcionais. Cada um deles oferece-lhe um controlo preciso sobre o áudio gerado e, ao compreendê-los, poderá adaptar a síntese ao seu caso de uso.
O parâmetro text
Juntamente com language, o text é o único parâmetro obrigatório. Aceita uma cadeia de caracteres com até 60 000 caracteres, que pode conter texto simples ou etiquetas expressivas (abordadas na secção seguinte).
{
"text": "Hello and welcome. Today, we're going to talk about artificial intelligence."
}
Acima de 60 000 caracteres, o pedido HTTP é rejeitado. Para textos mais longos, a xAI recomenda o uso de WebSocket, que não tem limite de comprimento total (lições 9 a 12), ou a divisão do texto em segmentos cujo áudio será concatenado. Faça a divisão em limites naturais (finais de frases, finais de parágrafos) para obter um resultado fluido.
O parâmetro voice_id
Este parâmetro define a voz utilizada para a síntese. É opcional e tem como valor predefinido eve. Os identificadores não distinguem maiúsculas de minúsculas: Eve, EVE e eve são equivalentes.
A xAI oferece 28 vozes integradas (a partir de 3 de novembro de 2026), as mesmas do agente de voz, além de vozes personalizadas criadas com a API de Vozes Personalizadas. As cinco vozes originais, conforme descritas pela xAI:
- eve: enérgica e otimista, sotaque britânico
- ara: calorosa e amigável
- rex: confiante e clara
- sal: suave e equilibrada
- leo: autoritária e poderosa, sotaque britânico
As outras 23 (carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora e liora) são descritas, com os seus casos de uso, na página Text to Speech da xAI; o endpoint GET /v1/tts/voices devolve a lista atual (lição 3).
{
"text": "Welcome to this tutorial.",
"voice_id": "rex",
"language": "en"
}
Segundo a xAI, todas as vozes falam todos os idiomas suportados. A sua escolha de voz não afeta o preço, que se baseia no número de caracteres.
O parâmetro language
Este parâmetro é obrigatório. Aceita um código BCP-47 ou o valor especial auto para deteção automática do idioma.
Os 20 idiomas suportados são:
| Código | Idioma | Código | Idioma |
|---|---|---|---|
en | Inglês | ko | Coreano |
fr | Francês | hi | Hindi |
de | Alemão | bn | Bengali |
es-ES | Espanhol (Espanha) | ar-EG | Árabe (Egito) |
es-MX | Espanhol (México) | ar-SA | Árabe (Arábia Saudita) |
pt-BR | Português (Brasil) | ar-AE | Árabe (EAU) |
pt-PT | Português (Portugal) | tr | Turco |
it | Italiano | id | Indonésio |
ru | Russo | vi | Vietnamita |
zh | Chinês | ja | Japonês |
A deteção automática (auto) funciona bem para textos num único idioma, mas para textos que misturam vários idiomas, indique explicitamente o idioma principal.
O parâmetro output_format
Este parâmetro opcional é um objeto JSON que controla o formato de saída do áudio. Possui três subparâmetros.
codec
O codec define o formato de codificação:
mp3(predefinido): formato comprimido, ideal para a web e streamingwav: formato sem perdas, melhor qualidade mas ficheiros maiorespcm: áudio bruto sem cabeçalho, para pipelines de processamentomulaw/ulaw: codec G.711 mu-law para telefoniaalaw: codec G.711 A-law para telefonia
sample_rate
A taxa de amostragem em hertz. Valores aceites: 8000, 16000, 22050, 24000 (predefinido), 44100, 48000.
bit_rate
A taxa de bits em bits por segundo, apenas para o codec MP3. Valores aceites: 32000, 64000, 96000, 128000 (predefinido), 192000.
{
"text": "High-quality audio for production.",
"voice_id": "ara",
"language": "en",
"output_format": {
"codec": "wav",
"sample_rate": 48000
}
}
O parâmetro speed
O speed define a velocidade de reprodução: 1.0 é a velocidade normal (predefinida) e o intervalo varia de 0.7 a 1.5. Um ritmo ligeiramente mais lento ajuda em conteúdos educativos densos; acima de 1.2, ouça sempre o resultado novamente.
Combinações recomendadas
| Caso de uso | codec | sample_rate | bit_rate |
|---|---|---|---|
| Web / streaming | mp3 | 24000 | 128000 |
| Produção de áudio | wav | 48000 | — |
| Telefonia VoIP | mulaw | 8000 | — |
| Pipeline de ML | pcm | 16000 | — |
Pontos-chave
textelanguagesão os únicos parâmetros obrigatóriosvoice_idé opcional (predefinido:eve) e não distingue maiúsculas de minúsculasoutput_formatcontrola o codec, a taxa de amostragem e a taxa de bits;speeddefine a velocidade (0.7 a 1.5)- MP3 a 24 kHz / 128 kbps é um bom equilíbrio predefinido entre qualidade e tamanho
- Para telefonia, utilize
mulawoualawa 8 kHz