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

Começar a utilizar a API de Síntese de Voz (Text-to-Speech)

Aula 6 de 14 Atualizada a 3 de novembro de 2026 Intermediario
Nesta página
  1. Texto entra, áudio sai
  2. HTTP ou WebSocket: duas formas de aceder ao serviço
  3. Parâmetros do pedido HTTP
  4. Escolher o formato de saída
  5. Consultar o catálogo de vozes
  6. Pontos-chave

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.

$15
por milhão de carateres
20
idiomas suportados
28
vozes integradas
60.000
máximo de carateres por pedido

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âmetroTipoObrigatórioDescrição
textstringSimO texto a converter, até 60.000 carateres
voice_idstringNãoA voz a utilizar (predefinição: eve)
languagestringSimCódigo BCP-47 (en, fr, de, …) ou auto
output_formatobjetoNãoCodec, taxa de amostragem e taxa de bits
speednúmeroNãoVelocidade 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 auto para deteção automática)