Automatizar Transcrições com a API: Exemplos Práticos
Receitas de automação com a API do VozParaTexto: enviar gravações por URL, escolher engine e formatos, usar idempotency_key e metadata, e receber tudo por webhook.
Com a API você transforma qualquer fonte de gravações — telefonia, gravador de reuniões, sistema interno — em texto pesquisável, sem intervenção manual. Este artigo traz o fluxo recomendado e receitas prontas. Antes, veja os pré-requisitos em API de transcrição (plano Profissional+ e chave vpt_live_).
O fluxo recomendado
- Envie o áudio por URL com um
webhook_url. - Receba o callback quando terminar (sucesso ou falha).
- Baixe os arquivos exportados pelos links do resultado — eles valem por 7 dias.
Nada de polling: com limite de 60 requisições/minuto por chave, consultar status em loop desperdiça cota. O webhook entrega o desfecho sozinho, com até 6 reentregas se o seu servidor estiver fora do ar.
Receita 1 — transcrever toda gravação nova
curl -X POST https://api.voxscriber.com/v1/transcriptions \
-H "Authorization: Bearer $VPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://storage.suaempresa.com/calls/2026-08-02-0931.mp3",
"webhook_url": "https://api.suaempresa.com/hooks/vpt",
"formats": ["txt", "docx"],
"metadata": { "call_id": "0931", "agente": "maria" },
"idempotency_key": "call-2026-08-02-0931"
}'
metadatavolta no webhook — use para correlacionar o resultado com o registro no seu sistema.idempotency_keygarante que reenvios acidentais (retry do seu lado, deploy no meio do job) não processem nem cobrem o mesmo áudio duas vezes.
Receita 2 — escolher a engine pelo custo
O campo engine aceita ASSEMBLYAI (Premium, padrão), WHISPER (Padrão) e ELEVENLABS (Ultra). Para volume alto em que o custo importa mais que o acabamento, use Whisper — 1 ciclo/min contra 4 do Premium:
-d '{ "audio_url": "...", "webhook_url": "...", "engine": "WHISPER" }'
Regra prática: Premium para reuniões e entrevistas importantes; Padrão (Whisper) para volume alto e áudio com ruído; Ultra quando a separação de falantes precisa ser impecável (disponível no Profissional+).
Receita 3 — legendas automáticas
Peça formats: ["srt", "vtt"] e receba as legendas prontas para YouTube ou players web no próprio webhook. Detalhes de cada formato em Exportar para outras ferramentas.
Limites que afetam automações
| Item | Regra |
|---|---|
| Rate limit | 60 req/min por chave |
audio_url | só https, pública, até 500 MB (download) ou 5 GB via passthrough com a engine Premium |
| Formatos | seguem o gate do seu plano; os não permitidos voltam em exports_skipped |
| Links de download | expiram em 7 dias (a transcrição continua no acervo) |
| Ciclos | mesmos custos do site, debitados do mesmo saldo |
Monitore seu saldo de ciclos: não existe hoje teto de gasto por chave. Uma automação com loop descontrolado consome saldo real. O idempotency_key é sua primeira linha de defesa.
FAQ
Como recebo o texto final — no webhook ou preciso baixar?
O webhook traz o desfecho e os links dos arquivos exportados nos formatos pedidos. Baixe os arquivos em até 7 dias; depois disso, o conteúdo continua disponível no acervo do site.
Posso definir o idioma do áudio?
Sim, pelo campo language. Sem ele, vale o padrão da conta; a detecção automática também é suportada pelas engines.
E se dois sistemas enviarem o mesmo áudio?
Use o mesmo idempotency_key nos dois — só o primeiro processa e cobra.
A automação funciona para membros de organização?
Sim — e o consumo segue as regras do plano da empresa. Para auditoria de chamadas em escala, veja a API dedicada.
Artigos relacionados
Não resolveu? Abra um ticket — nossa equipe responde rápido.