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

Parâmetros do pedido TTS

Aula 2 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Afine a sua síntese de voz
  2. O parâmetro text
  3. O parâmetro voice_id
  4. O parâmetro language
  5. O parâmetro output_format
  6. O parâmetro speed
  7. Combinações recomendadas
  8. Pontos-chave

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ódigoIdiomaCódigoIdioma
enInglêskoCoreano
frFrancêshiHindi
deAlemãobnBengali
es-ESEspanhol (Espanha)ar-EGÁrabe (Egito)
es-MXEspanhol (México)ar-SAÁrabe (Arábia Saudita)
pt-BRPortuguês (Brasil)ar-AEÁrabe (EAU)
pt-PTPortuguês (Portugal)trTurco
itItalianoidIndonésio
ruRussoviVietnamita
zhChinêsjaJaponê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 streaming
  • wav: formato sem perdas, melhor qualidade mas ficheiros maiores
  • pcm: áudio bruto sem cabeçalho, para pipelines de processamento
  • mulaw / ulaw: codec G.711 mu-law para telefonia
  • alaw: 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 usocodecsample_ratebit_rate
Web / streamingmp324000128000
Produção de áudiowav48000—
Telefonia VoIPmulaw8000—
Pipeline de MLpcm16000—

Pontos-chave

  • text e language são os únicos parâmetros obrigatórios
  • voice_id é opcional (predefinido: eve) e não distingue maiúsculas de minúsculas
  • output_format controla o codec, a taxa de amostragem e a taxa de bits; speed define 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 mulaw ou alaw a 8 kHz