O endpoint POST /v1/tts
Nesta página
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.
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, …) ouautopara 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/mpegpara MP3 (predefinido)audio/wavpara WAVaudio/pcmpara PCM brutoaudio/basicpara G.711 μ-law (mulaw)audio/alawpara 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