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

O endpoint POST /v1/tts

Aula 1 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Transforme texto em áudio com a API do Grok
  2. Estrutura do pedido
  3. A resposta HTTP
  4. Preços
  5. Pontos-chave

Atualizado em 3 de novembro de 2026, com base na página Text to Speech da xAI, na referência da API de Voz e na página de Preços. Fontes: Text to Speech · Voice API · Pricing.

Transforme texto em áudio com a API do Grok

A API de Texto para Fala (Text-to-Speech) da xAI converte qualquer texto em áudio de som natural com uma única chamada HTTP. O ponto de entrada principal é POST /v1/tts, que recebe o seu texto e devolve diretamente um ficheiro de áudio binário.

60,000
Carateres máximos por pedido
28
Vozes integradas
20
Idiomas suportados
$15
Por milhão de carateres

Estrutura do pedido

Envia um pedido POST para https://api.x.ai/v1/tts com um corpo JSON. Eis um exemplo mínimo com curl:

curl -X POST "https://api.x.ai/v1/tts" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, and welcome to Corsen Academy.",
    "voice_id": "eve",
    "language": "en"
  }' \
  --output audio.mp3

O servidor responde com o ficheiro de áudio binário diretamente no corpo da resposta. Não existe nenhum envelope JSON à volta: recebe os bytes brutos do ficheiro de áudio.

Autenticação

Tal como em todos os endpoints da API da xAI, inclua a sua chave de API no cabeçalho Authorization no formato Bearer:

Authorization: Bearer xai-your-api-key

Corpo do pedido

O corpo JSON gira em torno de quatro parâmetros principais:

  • text (obrigatório): o texto a converter, até 60.000 carateres. Suporta as etiquetas expressivas que aprenderá nas próximas lições.
  • voice_id (opcional): o ID da voz. O valor predefinido é eve. Os valores não distinguem maiúsculas de minúsculas.
  • language (obrigatório): o código do idioma no formato BCP-47 (en, fr, de, …) ou auto para deteção automática.
  • output_format (opcional): um objeto que configura o codec, a taxa de amostragem e a taxa de bits.

Outras definições, todas opcionais, completam o pedido: speed (velocidade de reprodução, de 0,7 a 1,5, sendo 1,0 o valor predefinido), replace (uma tabela de substituições que corrige a pronúncia de uma palavra sem alterar o texto que envia), with_timestamps (carimbos de data/hora por caratere), text_normalization (soletrar números, abreviaturas e símbolos antes da síntese) e optimize_streaming_latency ("1" para reduzir a espera antes do primeiro bloco de áudio, à custa de uma ligeira perda de qualidade nas junções).

A resposta HTTP

Em caso de sucesso (estado 200), o servidor devolve o ficheiro de áudio com o tipo de conteúdo correspondente ao formato solicitado:

  • audio/mpeg para MP3 (predefinido)
  • audio/wav para WAV
  • audio/pcm para PCM bruto
  • audio/basic para G.711 μ-law (mulaw)
  • audio/alaw para G.711 A-law (alaw)

A resposta não transporta metadados, apenas bytes de áudio. A única exceção é with_timestamps: a resposta torna-se então um objeto JSON que contém o áudio em base64, a sua duração e o carimbo de data/hora de cada caratere. Pode escrever a resposta diretamente num ficheiro ou transmiti-la em fluxo para um leitor de áudio.

Exemplo em Python

import requests

response = requests.post(
    "https://api.x.ai/v1/tts",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "text": "Here's an example of speech synthesis.",
        "voice_id": "rex",
        "language": "en"
    }
)

with open("output.mp3", "wb") as f:
    f.write(response.content)

Exemplo em JavaScript (Node.js)

const response = await fetch("https://api.x.ai/v1/tts", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Here's an example of speech synthesis.",
    voice_id: "rex",
    language: "en"
  })
});

const buffer = await response.arrayBuffer();
fs.writeFileSync("output.mp3", Buffer.from(buffer));

Preços

O TTS custa $15 por milhão de carateres (preços da xAI a 3 de novembro de 2026). É cobrado pelos carateres que envia em text, incluindo as etiquetas expressivas; uma tabela replace não altera essa contagem. Com uma média de 1.000 carateres por pedido, isso resulta em cerca de $0,015 por chamada.

Pontos-chave

  • O endpoint POST /v1/tts é o ponto de entrada principal para a síntese de fala
  • A resposta é um ficheiro de áudio binário, não JSON
  • O texto está limitado a 60.000 carateres por pedido HTTP; o WebSocket não tem limite total
  • Autentica-se com o cabeçalho Authorization: Bearer
  • Custa $15 por milhão de carateres