API do TranscritorAi
Todos os endpoints da API, com o que cada um faz e se precisa de login. Os mesmos dados também estão disponíveis nos formatos automáticos abaixo.
A URL base é o próprio endereço deste site (mesma origem, não existe um domínio de API separado).
Endpoints marcados "Requer login" esperam o cabeçalho Authorization: Bearer
Contas com verificação em duas etapas: POST /api/auth/login responde com requer_2fa: true e um desafio; envie o desafio e o código de 6 dígitos para POST /api/auth/login/2fa para receber o token. No site, a sessão fica num cookie HttpOnly — a API para scripts segue com Authorization: Bearer.
Contabilização: cada arquivo ou link custa 1 crédito, descontado no envio (primeiro da cota mensal do plano, depois do saldo avulso). Vídeo custa 1 crédito a cada 5 min, áudio a cada 10 min e PDF/DOCX/TXT a cada 100 páginas. Falhas e cancelamentos devolvem os créditos; "pular" um arquivo já processado e reprocessar uma falha não cobram. Consulte GET /api/usuarios/eu/capacidade antes de enviar.
API para desenvolvedores (v1)
Use uma chave de API para transcrever de dentro do seu sistema. Crie a chave em Minha conta, na aba Opções. As chamadas gastam a cota de créditos do plano da API da conta e o resultado também aparece em Meus arquivos.
Envie a chave em Authorization: Bearer tr_live_.... Ela só vale em /api/v1: o login do site não vale ali e a chave não vale nas outras rotas da API.
O processamento é assíncrono: a criação responde na hora com o id e status: queued. Consulte o andamento com GET ou receba um webhook quando terminar. O texto vem em result.text.
Exemplo: criar uma transcrição
curl -X POST https://transcritorai.com/api/v1/transcriptions \
-H "Authorization: Bearer tr_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"source": {"type": "url", "url": "https://exemplo.com/reuniao.mp4"}, "metadata": {"id": "123"}}'
# 202 Accepted
{"id": "...", "status": "queued", "metadata": {"id": "123"}, ...}
curl https://transcritorai.com/api/v1/transcriptions/ID -H "Authorization: Bearer tr_live_SUA_CHAVE"
# {"status": "completed", "result": {"text": "..."}, ...}
Cada aviso de webhook traz o cabeçalho X-Transcritor-Signature: t=...,v1=..., o HMAC-SHA256 de t.corpo com o seu segredo (whsec_..., na aba Opções de Minha conta). Confira a assinatura e recuse avisos com t antigo. Só endereços https públicos. Se o seu sistema não responder 2xx, tentamos até 4 vezes; depois, consulte com GET.
Conferir a assinatura de um webhook
import hashlib, hmac, time
def aviso_valido(segredo, cabecalho, corpo_bytes):
partes = dict(p.split("=", 1) for p in cabecalho.split(","))
esperado = hmac.new(segredo.encode(), partes["t"].encode() + b"." + corpo_bytes, hashlib.sha256).hexdigest()
recente = abs(time.time() - int(partes["t"])) < 300
return recente and hmac.compare_digest(esperado, partes["v1"])
O limite de requisições por minuto depende do plano e vale por chave (resposta 429 com Retry-After). Cota de créditos esgotada: resposta 402 cota_esgotada. Um envio por vez por conta: se receber 409 envio_em_andamento, tente de novo em alguns segundos.
Planos da API
A API tem cota própria, separada da cota do site. Os créditos são os mesmos do site (1 crédito por arquivo, ou a cada 5 minutos de vídeo) e zeram todo mês. O limite de requisições por minuto vale por chave. Glossários na API valem a partir do Startup.
Startup e Business são assinados no cartão, pelo Mercado Pago, em Planos (aba API), mensal ou anual (o anual custa 10 mensalidades). O plano só vale depois que o pagamento é aprovado e renova sozinho no cartão salvo; se a renovação for recusada por mais de 3 dias, a conta volta ao Developer. Você cancela quando quiser na mesma tela. O Startup também vem no Combo Completo + API. O Enterprise é sob consulta: fale com o suporte.
Rotas
POST /api/v1/transcriptions·POST /api/v1/transcriptions/upload: Cria uma transcrição a partir de um endereço (JSON) ou de um arquivo (multipart). Aceita glossary_id, webhook_url e metadata.GET /api/v1/transcriptions/{id}: Situação (queued, processing, completed, failed, canceled) e, quando pronta, o texto em result.text.GET /api/v1/transcriptions: Lista paginada das transcrições feitas por API, sem o texto.DELETE /api/v1/transcriptions/{id}: Se estiver em andamento, cancela; depois tira da lista. O texto continua em Meus arquivos.GET /api/v1/usage: Plano, limite do mês, usado, restante, créditos avulsos e limite por minuto.POST|GET /api/v1/webhooks·DELETE /api/v1/webhooks/{id}·GET /api/v1/webhooks/deliveries: Cadastra endereços de aviso (https) e consulta o histórico de entregas.GET|POST /api/v1/glossaries·GET|POST /api/v1/glossaries/{id}/terms: Glossários e termos em lote (até 500 por chamada), para acertar nomes e termos técnicos.POST|GET /api/v1/transcriptions/{id}/studio: Modo Estúdio pela API: gera os capítulos do YouTube (chapters), os show notes (show_notes) ou os ganchos (hooks) de uma transcrição, com a chave de IA da própria conta. Gasta 5 créditos da API por kit (os outros produtos do mesmo episódio no mês não gastam mais) e avisa pelos webhooks (studio.completed e studio.failed). O GET devolve o kit pronto.