Automatizar Transcrições com a API: Exemplos Práticos
Receitas de automação com a API do VozParaTexto: enviar gravações por URL, escolher a engine e os formatos, usar idempotency_key e metadata, e receber tudo por webhook.
Com a API, pode transformar qualquer fonte de gravações — telefonia, gravador de reuniões, sistema interno — em texto pesquisável, sem intervenção manual. Este artigo apresenta o fluxo recomendado e receitas prontas. Antes, consulte 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).
- Descarregue os ficheiros exportados pelos links do resultado — eles têm validade de 7 dias.
Evite polling: com o limite de 60 requisições/minuto por chave, consultar o estado num ciclo desperdiça cota. O webhook entrega o desfecho sozinho, com até 6 reentregas se o seu servidor estiver fora do ar.
Receita 1 — transcrever qualquer 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"
}'
- O campo
metadataé devolvido no webhook — use-o para correlacionar o resultado com o registo 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 de 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 | apenas https, pública, até 500 MB (download) ou 5 GB via passthrough com a engine Premium |
| Formatos | seguem o limite do seu plano; os não permitidos são devolvidos em exports_skipped |
| Links de download | expiram em 7 dias (a transcrição continua no arquivo) |
| Ciclos | os mesmos custos do site, debitados no mesmo saldo |
Monitorize o seu saldo de ciclos: não existe atualmente um teto de gasto por chave. Uma automação com loop descontrolado consome saldo real. O idempotency_key é a sua primeira linha de defesa.
FAQ
Como recebo o texto final — no webhook ou preciso de o descarregar?
O webhook traz o desfecho e os links dos ficheiros exportados nos formatos pedidos. Descarregue os ficheiros até 7 dias; depois disso, o conteúdo continua disponível no arquivo do site.
Posso definir o idioma do áudio?
Sim, pelo campo language. Sem ele, vale o padrão da conta; a deteçã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 — a nossa equipa responde rápido.