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.

Abrir no Swagger

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 , o mesmo token devolvido por POST /api/auth/login ou POST /api/auth/registrar. A API usa a mesma conta do site: plano, créditos, histórico e armazenamento são compartilhados.

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.