TranscritorAi API
Every API endpoint, what it does, and whether it needs a login. The same data is also available in the automatic formats below.
The base URL is this site's own address (same origin, there's no separate API domain).
Endpoints marked "Requires login" expect the header Authorization: Bearer
Accounts with two-step verification: POST /api/auth/login answers requer_2fa: true and a desafio (challenge); send the challenge and the 6-digit code to POST /api/auth/login/2fa to receive the token. On the website the session lives in an HttpOnly cookie — the API for scripts keeps using 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 for developers (v1)
Use an API key to transcribe from inside your own system. Create the key in My account, on the Options tab. Calls use the credit quota of the account's API plan and the result also appears in My files.
Send the key in Authorization: Bearer tr_live_.... It only works on /api/v1: the website login does not work there and the key does not work on the other API routes.
Processing is asynchronous: creating a transcription answers right away with the id and status: queued. Check progress with GET or receive a webhook when it ends. The text comes in result.text.
Example: create a transcription
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": "..."}, ...}
Each webhook notification carries the X-Transcritor-Signature: t=...,v1=... header, the HMAC-SHA256 of t.body with your secret (whsec_..., on the Options tab of My account). Check the signature and reject notifications with an old t. Public https addresses only. If your system does not answer 2xx, we try up to 4 times; after that, check with GET.
Checking a webhook signature
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"])
The per-minute request limit depends on the plan and applies per key (a 429 answer with Retry-After). Credit quota used up: a 402 cota_esgotada answer. One submission at a time per account: if you get 409 envio_em_andamento, try again in a few seconds.
API plans
The API has its own quota, separate from the website quota. Credits are the same as on the website (1 credit per file, or per 5 minutes of video) and reset every month. The per-minute request limit applies per key. Glossaries in the API are available from Startup.
Startup and Business are subscribed to by card, through Mercado Pago, on the Plans page (API tab), monthly or annual (the annual plan costs 10 monthly payments). The plan only takes effect after the payment is approved and renews by itself on the saved card; if the renewal is declined for more than 3 days, the account goes back to Developer. You can cancel whenever you want on the same screen. Startup also comes in the Complete + API Combo. Enterprise is on request: contact support.
Routes
POST /api/v1/transcriptions·POST /api/v1/transcriptions/upload: Creates a transcription from an address (JSON) or a file (multipart). Accepts glossary_id, webhook_url and metadata.GET /api/v1/transcriptions/{id}: Status (queued, processing, completed, failed, canceled) and, when ready, the text in result.text.GET /api/v1/transcriptions: Paginated list of transcriptions made through the API, without the text.DELETE /api/v1/transcriptions/{id}: If running, cancels it; then removes it from the list. The text stays in My files.GET /api/v1/usage: Plan, monthly limit, used, remaining, extra credits and the per-minute limit.POST|GET /api/v1/webhooks·DELETE /api/v1/webhooks/{id}·GET /api/v1/webhooks/deliveries: Registers notification addresses (https) and shows the delivery history.GET|POST /api/v1/glossaries·GET|POST /api/v1/glossaries/{id}/terms: Glossaries and terms in batches (up to 500 per call), to get names and technical terms right.POST|GET /api/v1/transcriptions/{id}/studio: Studio Mode through the API: generates the YouTube chapters (chapters), the show notes (show_notes) or the hooks (hooks) of a transcription, with the account's own AI key. It spends 5 API credits per kit (the other products of the same episode in the month cost nothing more) and notifies through webhooks (studio.completed and studio.failed). GET returns the finished kit.