API de Transcrição: Visão Geral, Autenticação e Limites
Como usar a API REST do VozParaTexto: quem tem acesso, como funcionam as chaves vpt_live_, autenticação Bearer, limites de requisição e cobrança em ciclos.
A API REST do VozParaTexto permite enviar áudios por URL e receber a transcrição pronta no seu sistema, sem passar pelo site. Ela usa as mesmas engines e cobra os mesmos ciclos das transcrições feitas no painel.
Quem pode usar
A API é liberada 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 sua conta não for elegível, as rotas de chave retornam o erro 403 PLAN_NOT_ELIGIBLE.
Chaves de API
Crie a chave
Copie o segredo imediatamente
vpt_live_... e é exibida uma única vez, no momento da criação. Nós guardamos apenas um hash dela — não é possível recuperá-la depois.Guarde com segurança
Perdeu a chave? Não há como reexibi-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 uma tela dedicada no painel. Se o seu plano é elegível e você quer começar a usar a API, abra um ticket que a equipe ativa o acesso com você.
Autenticação
Toda requisição leva a chave no header Authorization:
Authorization: Bearer vpt_live_SUA_CHAVE
Requisição sem o header retorna 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 aceitos 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 chega no seu webhook_url — veja Webhooks e notificações.
Use idempotency_key com um identificador seu (ex.: o ID da gravação no seu sistema). Se a mesma requisição for reenviada por engano, o áudio não é processado — nem cobrado — duas vezes.
Limites
| Limite | Valor |
|---|---|
| Requisições por chave | 60 por minuto |
| Áudio baixado por URL | até 500 MB (timeout de 60 s) |
| Áudio via passthrough (engine Premium lê a URL direto) | 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. A URL do áudio precisa ser acessível publicamente.
Os formatos de exportação disponíveis seguem o gate do seu plano, igual ao site — formatos fora do plano voltam 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). Não existe hoje cota mensal de chamadas nem teto de gasto por chave — controle o consumo pelo seu saldo de ciclos. Veja O que São Ciclos e Quanto Custa Cada Minuto.
FAQ
Perdi minha chave de API. Como recupero?
Não dá para recuperar — só o hash fica no banco. Revogue a chave perdida e crie uma nova.
A API cobra mais caro que o site?
Não. O custo em ciclos é idêntico, definido pela engine e pela duração do áudio.
Posso enviar o arquivo direto em vez de uma URL?
O canal principal é por audio_url. Se seus áudios não têm URL pública, 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 hoje apenas os endpoints públicos (estatísticas e transcrições compartilhadas). Para o restante, use 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 — nossa equipe responde rápido.