API de Transcrição: Visão Geral, Autenticação e Limites
Como utilizar a API REST do VozParaTexto: quem tem acesso, como funcionam as chaves vpt_live_, autenticação Bearer, limites de pedidos e cobrança em ciclos.
A API REST do VozParaTexto permite-lhe enviar áudios por URL e receber a transcrição pronta no seu sistema, sem passar pelo site. Utiliza as mesmas engines e debita os mesmos ciclos das transcrições feitas no painel.
Quem pode usar
A API está disponível a partir do plano Profissional (R$ 39,90/mês). Têm acesso: Profissional, Premium, todos os planos Empresariais (mensais e anuais) e os planos legados equivalentes. Se a sua conta não for elegível, as rotas de chave devolvem o erro 403 PLAN_NOT_ELIGIBLE.
Chaves de API
Crie a chave
Copie o segredo imediatamente
vpt_live_... e é apresentada uma única vez, no momento da criação. Guardamos apenas um hash dela — não é possível recuperá-la depois.Guarde-a com segurança
Perdeu a chave? Não é possível voltar a vê-la. Revogue a chave antiga e crie uma nova. Chaves comprometidas devem ser revogadas imediatamente.
A criação de chaves pessoais ainda não tem um ecrã dedicado no painel. Se o seu plano é elegível e quiser começar a utilizar a API, abra um ticket para a equipa ativar o acesso consigo.
Autenticação
Todos os pedidos incluem a chave no cabeçalho Authorization:
Authorization: Bearer vpt_live_SUA_CHAVE
Um pedido sem esse cabeçalho devolve 401 MISSING_API_KEY.
Enviar um áudio para transcrição
O endpoint de transcrição fica no gateway api.voxscriber.com:
curl -X POST https://api.voxscriber.com/v1/transcriptions \
-H "Authorization: Bearer vpt_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://exemplo.com/gravacoes/reuniao.mp3",
"webhook_url": "https://seusistema.com/webhooks/vozparatexto",
"formats": ["txt", "srt"]
}'
Campos aceites no corpo: audio_url, webhook_url, engine (ASSEMBLYAI, WHISPER ou ELEVENLABS), language, formats (txt, json, srt, vtt, docx, pdf), metadata e idempotency_key. O resultado é entregue no seu webhook_url — veja Webhooks e notificações.
Utilize uma idempotency_key com um identificador seu (ex.: o ID da gravação no seu sistema). Se o mesmo pedido for reenviado por engano, o áudio não é processado — nem cobrado — duas vezes.
Limites
| Limite | Valor |
|---|---|
| Pedidos por chave | 60 por minuto |
| Áudio transferido por URL | até 500 MB (timeout de 60 s) |
| Áudio via passthrough (engine Premium lê a URL diretamente) | até 5 GB |
| Chaves ativas por conta | 20 |
Regras de segurança nas URLs: apenas https, sem redirecionamentos, e endereços internos/privados são bloqueados. O URL do áudio tem de estar acessível publicamente.
Os formatos de exportação disponíveis seguem as permissões do seu plano, tal como no site — formatos fora do plano são devolvidos listados em exports_skipped.
Cobrança
A API debita os mesmos ciclos de uma transcrição feita no site, conforme a engine escolhida (Padrão/Whisper: 1 ciclo/min; Premium: 4 ciclos/min; Ultra: 10 ciclos/min). Atualmente não existe quota mensal de chamadas nem limite de gastos por chave — controle o consumo através do seu saldo de ciclos. Veja O Que São Ciclos e Quanto Custa Cada Minuto.
FAQ
Perdi a minha chave de API. Como posso recuperá-la?
Não é possível recuperá-la — apenas o hash fica na base de dados. Revogue a chave perdida e crie uma nova.
A API é mais cara do que o site?
Não. O custo em ciclos é idêntico, determinado pela engine e pela duração do áudio.
Posso enviar o ficheiro diretamente em vez de um URL?
O canal principal é através de audio_url. Se os seus áudios não tiverem um URL público, fale com o suporte para avaliar o melhor fluxo para o seu caso.
Existe documentação OpenAPI?
A spec pública em /.well-known/openapi.json cobre atualmente apenas os endpoints públicos (estatísticas e transcrições partilhadas). Para o resto, utilize esta central e o suporte.
Artigos relacionados
- Webhooks e notificações
- Automatizar com a API
- O Que São Ciclos e Quanto Custa Cada Minuto
- Exportar para outras ferramentas
Não resolveu? Abra um ticket — a nossa equipa responde rapidamente.