API Grok STT e TTS: transcreva, narre e baixe

Use o Grok STT para transcrever uma gravação existente e o Grok TTS para fazer uma voz predefinida ler um roteiro. Teste os dois primeiro no Playground da SpicyAPI e depois chame-os por código ou por um agente. É um fluxo com arquivos salvos; para conversa de voz ao vivo, você precisa de um transporte em tempo real. O STT custa cerca de US$ 0,002 por minuto de áudio; o TTS, US$ 0,018 por 1.000 caracteres. Nos nossos testes de setembro de 2026, as duas rotas processaram gravações e roteiros para adultos exatamente como escritos, sem recusas, mascaramento nem clipes cortados.

Preços, limites e o que cada rota retorna

Uma gravação mais longa ou maior precisa de uma URL pública. A URL também pode apontar para M4A, FLAC, OGG, Opus, AAC, MP4 ou MKV, mas precisa devolver o próprio arquivo de áudio, não um player nem uma página de compartilhamento. O STT não aceita PCM, μ-law nem A-law sem cabeçalho.

Uma hora de áudio custa cerca de US$ 0,12, e uma gravação de 90 segundos, cerca de US$ 0,003. A tarefa reserva primeiro o máximo de duas horas, cerca de US$ 0,24, e libera a diferença quando a duração real é conhecida. Um roteiro de 1.800 caracteres custa US$ 0,0324; duas tomadas completas mais uma regravação de 240 caracteres custam US$ 0,06912. Espaços, pontuação e tags de dicção contam como caracteres, e a cotação exibida antes de uma execução de TTS é a cobrança final.

Teste primeiro no Playground

Transcrever. Abra a página do Grok STT e fique na aba Playground.

1. Em Input audio, envie seu MP3 ou WAV (até 90 MB) ou mude para Asset URL e clique em Add URL para uma gravação hospedada em outro lugar.
2. Abra Advanced parameters só se precisar de Language, Normalize text, Key terms, Keep filler words ou Transcribe channels separately.
3. Confira a estimativa de preço, faça login e execute. A transcrição aparece no painel Output, com uma visualização JSON para o tempo de cada palavra.

Narrar. Abra a página do Grok TTS.

1. Cole ou edite o roteiro em Text (o botão Sample script preenche um exemplo), com as tags de dicção que quiser.
2. Escolha uma Voice; o menu mostra de cada uma o nome, o gênero e o idioma. Em Advanced parameters ficam Speed, Output format, Bitrate e Language.
3. Execute, ouça a tomada no painel Output e use Download para guardá-la.

Teste aqui o seu nome ou a sua frase mais difícil antes de escrever o roteiro de uma narração inteira; o que soa errado no Playground soará igualmente errado pela API.

Opções de transcrição que mudam o resultado

Language (language) pode ser omitido para detecção automática. Normalize text (text_normalization) escreve números, preços e datas em algarismos (“March 14”, “$1,250”) e exige language; deixe desativado se precisar das palavras exatas como foram faladas.

Keep filler words (filler_words: true) mantém os “hum” e “é...”, que por padrão são removidos. Key terms (keyterms) orientam a grafia para nomes inventados e marcas, até 100 termos de 50 caracteres. Envie-os como objetos, [{"term":"Mara"},{"term":"Jon"}], e não como strings simples.

Transcribe channels separately (multichannel: true) transcreve separadamente cada canal de um arquivo, até oito. Com a opção desativada, uma gravação estéreo com um falante diferente em cada lado pode voltar sem um deles. Leia output.transcript.channels para as palavras e os tempos de cada lado; o texto combinado tem uma linha por canal e não é um diálogo pronto. Ele não separa duas pessoas misturadas em um único canal mono, e a rota não retorna rótulos de falante: para entrevistas em mono, use canais gravados separadamente ou uma ferramenta de diarização.

Depois, chame por código

Instale o SDK Python (pip install spicyapi, Python 3.11+), defina SPICY_API_KEY e execute este fluxo da transcrição à narração. Troque o caminho do arquivo por uma gravação que você esteja autorizado a usar.

import uuid

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

# 1. Transcribe a local recording (uploads are free and kept for one day)
source = client.upload_file("./interview.mp3")
stt = client.create_task(
    model="xai/grok-stt/speech-to-text",
    input_data={"audio_url": source["uri"], "multichannel": True},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
done = client.wait_for_terminal(stt["taskId"])
if done["state"] != "succeeded":
    raise RuntimeError(f"STT task {stt['taskId']} ended as {done['state']}")
print(done["output"]["text"])  # edit this into your script

# 2. Narrate the edited script
script = "Chapter Three. The storm kept them in the cabin. [breath] <slow>Neither of them pretended to be reading.</slow>"
tts = client.create_task(
    model="xai/grok-tts/text-to-speech",
    input_data={"text": script, "voice_id": "rex", "language": "en", "speed": 0.9},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
final = client.wait_for_terminal(tts["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"TTS task {tts['taskId']} ended as {final['state']}")

# 3. Copy the MP3 link to your own storage now; generated audio is kept for 14 days
print(output_assets(final)[0]["url"])

Reutilize uma chave de idempotência apenas para repetir a mesma requisição depois de uma resposta perdida. Uploads, espera, erros, novas tentativas e renovação de um link de download expirado estão na referência do SDK Python e no guia de tarefas.

Ou deixe um agente executar

Se um assistente deve transcrever e narrar por você, dê a ele a CLI ou o servidor MCP. Ambos mostram o preço e pedem sua confirmação antes de uma chamada paga. A Skill acrescenta instruções por cima de qualquer um dos dois.

• CLI. spicyapi executa uma tarefa no terminal (npx @spicyapi/cli funciona sem instalar):

``bash spicyapi files upload ./interview.mp3 # prints a spicy:// URI spicyapi tasks create --model xai/grok-stt/speech-to-text \ --input-json '{"audio_url": "spicy://YOUR-UPLOAD-URI", "multichannel": true}' --wait ``

• Servidor MCP. Adicione o servidor MCP ao seu assistente e peça: “Transcribe ./interview.mp3 with Grok STT, with each channel separate.” Ele chama spicyapi_upload_file, depois spicyapi_task_create (que para para você confirmar o preço) e então spicyapi_task_wait.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill instala a Agent Skill, que ensina um assistente de programação a ler o schema atual e a reutilizar chaves de idempotência. Ela não executa tarefas sozinha; use-a junto com a CLI ou o MCP.

Da transcrição ao roteiro e à voz

Edite a transcrição antes da síntese: corrija nomes, pontuação e tudo o que você quiser que seja lido de outro jeito. Vale incluir uma lista curta de key terms para nomes inventados, mas a transcrição continua refletindo o que a gravação diz; por isso, confira os nomes no áudio.

O TTS tem 71 vozes predefinidas. eve é a padrão; eve, ara, leo, rex e sal falam todos os idiomas compatíveis, enquanto as outras 66 são ajustadas para um único idioma e aparecem na API como IDs opacos. Escolha-as no menu de vozes da página do modelo Grok TTS, que mostra de cada uma o nome, o gênero e o idioma. Teste um trecho curto com o seu nome mais difícil antes de sintetizar uma narração inteira.

A dicção é escrita no roteiro. As tags em linha produzem um som onde você as coloca: [pause], [long-pause], [breath], [inhale], [exhale], [sigh], [laugh], [chuckle], [giggle], [cry]. As tags que envolvem o texto mudam como as palavras dentro delas são lidas: <whisper>, <soft>, <slow>, <loud>, <build-intensity> e outras. As tags são executadas, não lidas em voz alta, mas contam no preço. Por exemplo:

{"text": "Chapter Three. The storm kept them in the cabin for two more days. [breath] By the second night, <slow>neither of them pretended to be reading anymore.</slow>", "voice_id": "rex", "speed": 0.9, "language": "en"}

speed vai de 0,7 a 1,5. bitrate só vale para MP3. Use MP3 para reprodução e WAV para edição; os formatos brutos pcm, mulaw e alaw a 8 kHz são para sistemas de telefonia e não tocam no navegador. SSML não é compatível; use as tags acima.

Para uma cena com dois personagens, sintetize separadamente as falas de cada um com vozes diferentes e junte na edição; uma requisição lê uma única voz. Mantenha pausas naturais nas emendas em vez de cortá-las a zero.

Para conferir uma tomada, passe o áudio gerado de volta pelo STT e compare com o roteiro: palavras faltando ou trocadas, um final cortado ou uma tag lida em voz alta costumam aparecer, e um clipe curto custa uma fração de centavo. Depois ouça o começo, o final e qualquer linha apontada. Se as predefinições do Grok não bastarem, o catálogo de modelos tem outras opções de voz; o comparativo “Uncensored text-to-speech APIs compared” por enquanto só existe em inglês.

Problemas comuns e soluções

Os timestamps de palavras do STT pertencem à gravação original. O TTS devolve áudio sem tempos por palavra, então alterar o texto ou a velocidade invalida os timestamps antigos; alinhe as legendas à tomada sintetizada final.