Começar a utilizar a API de Síntese de Voz (Text-to-Speech)
Nesta página
Atualizado a 3 de novembro de 2026, com base nas páginas Text to Speech e Pricing da xAI. Fontes: Text to Speech · Pricing.
Texto entra, áudio sai
A API de Síntese de Voz (Text-to-Speech) do Grok faz uma coisa e fá-la bem: converte texto em áudio de alta qualidade. Enquanto o Agente de Voz gere um diálogo, com turnos de fala e interrupções, a TTS funciona estritamente num sentido: o utilizador envia texto e recebe som em resposta. Essa simplicidade torna-a a ferramenta ideal sempre que ninguém responde à máquina: artigos narrados, mensagens de boas-vindas telefónicas, vozes off para módulos de e-learning ou notificações de áudio.
HTTP ou WebSocket: duas formas de aceder ao serviço
O modo HTTP é o mais direto. O utilizador envia um pedido POST com o seu texto e a resposta contém o ficheiro de áudio completo, em MP3 por predefinição:
curl -X POST "https://api.x.ai/v1/tts" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-o output.mp3 \
-d '{
"text": "Hello and welcome to Corsen Academy.",
"voice_id": "ara",
"language": "en"
}'
Note o parâmetro -o output.mp3: o corpo da resposta é áudio bruto, e não um JSON que envolve uma ligação. Este modo é perfeito para geração em segundo plano, como um lote noturno que produz versões de áudio dos seus artigos, uma vez que ninguém está à espera em frente a um ecrã.
O modo WebSocket responde a uma necessidade diferente: ouvir o som antes de todo o texto ter sido sintetizado. O utilizador abre uma ligação e passa os parâmetros no URL:
wss://api.x.ai/v1/tts?language=en&voice=ara&codec=mp3
Em seguida, envia o texto em pedaços com text.delta, sinaliza o fim com text.done e o áudio retorna como blocos em base64 em audio.delta. A transmissão em fluxo (streaming) elimina o limite de comprimento do modo HTTP e, acima de tudo, permite sintetizar à medida que se avança, o que é essencial quando o próprio texto ainda está a ser gerado por um modelo.
Parâmetros do pedido HTTP
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
text | string | Sim | O texto a converter, até 60.000 carateres |
voice_id | string | Não | A voz a utilizar (predefinição: eve) |
language | string | Sim | Código BCP-47 (en, fr, de, …) ou auto |
output_format | objeto | Não | Codec, taxa de amostragem e taxa de bits |
speed | número | Não | Velocidade de reprodução, de 0,7 a 1,5 (predefinição: 1,0) |
Dois pontos merecem atenção. O parâmetro language é obrigatório, o que muitas vezes surpreende: o serviço não adivinha o idioma do seu texto, a menos que lho peça explicitamente com o valor auto. Além disso, o voice_id utiliza exatamente as mesmas vozes que o Agente de Voz (28 vozes integradas a 3 de novembro de 2026, incluindo eve, ara, rex, sal e leo, além das suas vozes personalizadas) e ignora a distinção entre maiúsculas e minúsculas. A mesma persona de voz pode, portanto, alimentar tanto o seu agente conversacional como o seu conteúdo gravado, o que vale a pena aproveitar para garantir a consistência da marca.
Escolher o formato de saída
O campo output_format controla o codec e a qualidade:
{
"text": "Text to convert.",
"voice_id": "rex",
"language": "en",
"output_format": {
"codec": "wav",
"sample_rate": 44100
}
}
Escolha o codec com base no que acontecerá ao ficheiro a seguir. O mp3 adequa-se a um uso geral: bem comprimido e reproduzível em qualquer lugar, é a predefinição sensata para um website ou um podcast. O wav não tem perdas, sendo por isso mais pesado, mas é o necessário quando um editor vai retrabalhar a faixa. O pcm fornece áudio bruto, para pipelines de processamento que não necessitam de um contentor. Por fim, o mulaw e o alaw são os codecs de telefonia G.711, para sistemas de telecomunicações que os exijam.
As taxas de amostragem variam de 8000 a 48000 Hz, com uma predefinição de 24000 Hz, o que cobre a vasta maioria dos usos. Para MP3, a taxa de bits varia de 32000 a 192000 bps, com uma predefinição de 128000. Subir para 192000 numa voz falada acrescenta quase nada à experiência de audição e torna os seus ficheiros um terço maiores: guarde essa margem para conteúdos que misturam música e voz.
Consultar o catálogo de vozes
A API expõe dois endpoints de apenas leitura que complementam a geração. GET /v1/tts/voices devolve todas as vozes disponíveis com os seus metadados, e GET /v1/tts/voices/{voice_id} devolve os mesmos campos (voice_id, name, language) para uma única voz; o tom e os casos de uso de cada voz estão descritos na página Text to Speech da xAI. Em vez de codificar rigidamente os nomes das vozes na sua interface, preencha o seu seletor de vozes a partir destes endpoints; assim, a sua aplicação manter-se-á correta no dia em que o catálogo mudar.
Pontos-chave
- A TTS converte texto em áudio via HTTP (simples) ou WebSocket (transmissão em fluxo)
- Custa $15 por milhão de carateres, com um máximo de 60.000 carateres por pedido HTTP
- 28 vozes integradas, cinco codecs e seis taxas de amostragem oferecem muita flexibilidade
- O modo WebSocket não tem limite no comprimento total do texto (cada delta está limitado a 60.000 carateres)
- É necessário um código BCP-47 para especificar o idioma (ou
autopara deteção automática)