Introdução
Envie uma URL de áudio e, se quiser, o idioma falado, uma lista de termos-chave e três chaves: números com algarismos, palavras de preenchimento e transcrição por canal. A tarefa devolve a transcrição como texto, mais uma transcrição estruturada com tempos por palavra, o idioma detectado e a duração do áudio; nenhum arquivo é gerado. O SpicyAPI não aplica nenhum filtro de conteúdo: a fala sem filtro é transcrita como foi falada. A cobrança é por segundo de áudio.
| Campo | Valor |
|---|---|
| Entrada | Áudio |
| Saída | Texto |
| Campo obrigatório |
|
| Campos opcionais | language (25 códigos), |
| Resultado | Transcrição em texto, mais output.transcript com tempos por palavra, idioma e duração; por canal com multichannel |
| Quantidade cobrada | Segundos de áudio; um arquivo enviado é reservado pela duração, uma URL pelo máximo de duas horas |
| Tempo típico | Cerca de 3 segundos para um clipe de 10 segundos, cerca de 15 segundos para uma hora |
| Retenção | O áudio enviado é excluído depois de um dia; a transcrição é apagada com os dados do prompt |
Parâmetros da requisição
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
audio_url | Sim | O áudio a transcrever: um MP3 ou WAV enviado, ou uma URL pública para MP3, WAV, M4A, FLAC, OGG, Opus, AAC, MP4 ou MKV. De 1 segundo a 2 horas. pelo menos 1 caracteres |
language | Não | O idioma falado como código de idioma. Deixe vazio para detectar o idioma automaticamente; a fala em qualquer idioma compatível é transcrita nos dois casos. |
text_normalization | Não | Quando ativado, números, preços, datas e unidades falados são escritos com algarismos — "$1,250" e "March 14" em vez das palavras. Precisa de language. Valor padrão: |
keyterms | Não | Até 100 palavras ou expressões curtas (50 caracteres cada) que a transcrição deve favorecer — nomes, marcas, jargão. Não altera o preço. Valor padrão: |
filler_words | Não | Quando ativado, palavras de preenchimento como um e uh ficam na transcrição; desativado (padrão), elas são removidas. Não altera o preço. Valor padrão: |
multichannel | Não | Quando ativado, cada canal de um arquivo multicanal (até 8) é transcrito separadamente e volta na própria linha, na ordem dos canais. Valor padrão: |
Preços
$0.00003 / segundo de áudio
Cobrança por segundo de áudio. Ao criar a tarefa, é reservado o preço da duração real de um áudio enviado, ou o do máximo de duas horas para uma URL de áudio; você paga a duração real e o restante é liberado. Uma solicitação que falha não é cobrada.
Casos de uso
Notas de voz e histórias em áudio
A fala sem filtro é transcrita como foi falada, então mensagens de voz, gravações de roleplay e histórias em áudio podem ser pesquisadas, legendadas ou editadas como texto.
Gravações de chamadas
Gravações com cada lado no próprio canal voltam como uma linha por lado quando multichannel está ativado. Sem ele, nossos testes devolveram só um dos dois lados, então ative-o em chamadas com canais separados.
Conferir fala gerada
Passe um resultado de texto para fala de volta pelo modelo e compare a transcrição com o roteiro: palavras puladas, um final cortado ou uma tag lida em voz alta aparecem na hora.
Nomes, marcas e números
Liste nomes incomuns como termos-chave e ative a normalização de texto: a transcrição escreve os nomes do seu jeito e os preços e datas como $1,250 ou March 14.
Guia de prompt e dicas práticas
Aponte
audio_urlpara o áudioEnvie um MP3 ou WAV, ou passe uma URL pública que responda com o próprio áudio — uma página de player ou link de compartilhamento que devolve HTML falha. De 1 segundo a 2 horas.
Adicione o que você sabe
Defina language se souber o idioma, liste nomes e marcas em keyterms e ative
text_normalizationse quiser os números com algarismos.text_normalizationprecisa de language.Leia o texto na tarefa
A transcrição chega como texto no resultado da tarefa, e output.transcript lista cada palavra com seu tempo de início e fim. Com multichannel, há uma linha por canal, na ordem dos canais. Copie para o seu próprio armazenamento se for precisar dela depois.
O que volta
A transcrição como texto no resultado da tarefa, mais output.transcript: o idioma detectado e seu código, a duração do áudio em segundos e cada palavra com seu tempo de início e fim em segundos. Com multichannel, output.transcript.channels traz o mesmo para cada canal. Nenhum arquivo é gerado e nada entra no armazenamento de mídia. Rótulos de locutor não vêm no resultado.
Enviar o áudio
audio_url aceita um MP3 ou WAV enviado, ou uma URL pública para MP3, WAV, M4A, FLAC, OGG, Opus, AAC, MP4 ou MKV, de 1 segundo a 2 horas. A URL precisa responder com o próprio áudio. Áudio bruto sem cabeçalho de arquivo (PCM, μ-law, A-law) não é aceito.
Idioma e números
Se language ficar vazio, o idioma é detectado; a fala em qualquer um dos 25 idiomas compatíveis é transcrita nos dois casos. Defina-o e ative text_normalization para ter números, preços, datas e unidades na forma escrita — no nosso teste, "one thousand two hundred fifty dollars on March fourteenth" virou "$1,250 on March 14". text_normalization precisa de language.
Termos-chave e palavras de preenchimento
keyterms aceita até 100 termos de até 50 caracteres, um por linha. No nosso teste, "Xandrelle" e "Qorvessa" voltaram como "Xandrel" e "Corvessa" sem eles e exatamente certos com eles. filler_words mantém um e uh, que são removidos por padrão.
Vários canais
Ative multichannel em gravações com cada pessoa no próprio canal. Cada canal é transcrito separadamente e volta na própria linha, na ordem dos canais. Deixe desativado só quando todos os canais carregam o mesmo som: nos nossos testes, um arquivo estéreo com uma pessoa diferente em cada lado voltou sem uma das duas.
Cobrança
Cobrança por segundo de áudio. Ao criar a tarefa, é reservado o preço da duração real de um áudio enviado, ou o do máximo de duas horas para uma URL de áudio; você paga a duração real e o restante é liberado. Nenhuma opção altera o preço. Solicitações que falham não são cobradas.
Conteúdo
A SpicyAPI não adiciona filtro de conteúdo. Em nossos testes, a fala sem filtro voltou palavra por palavra, sem asteriscos, bipes ou lacunas.
O SpicyAPI não adiciona filtro de conteúdo: a fala é transcrita como foi falada, em vez de mascarada ou recusada. Você é responsável pelos direitos sobre o áudio que envia e pelo consentimento das pessoas gravadas.
Início rápido da API
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "xai/grok-stt/speech-to-text",
"input": {
"audio_url": "https://example.com/reference.mp3"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
Consulte a referência da API para autenticação, esquema completo, polling e tratamento de erros.





