API di TranscritorAi
Tutti gli endpoint dell'API, cosa fa ciascuno e se serve l'accesso. Gli stessi dati sono disponibili anche nei formati automatici qui sotto.
L'URL di base è l'indirizzo di questo stesso sito (stessa origine: non esiste un dominio API separato).
Gli endpoint contrassegnati "Richiede login" si aspettano l'intestazione Authorization: Bearer
Account con verifica in due passaggi: POST /api/auth/login risponde requer_2fa: true e un desafio (sfida); invia la sfida e il codice a 6 cifre a POST /api/auth/login/2fa per ricevere il token. Sul sito web la sessione sta in un cookie HttpOnly; l'API per gli script continua a usare 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 per sviluppatori (v1)
Usa una chiave API per trascrivere dall'interno del tuo sistema. Crea la chiave in Il mio account, nella scheda Opzioni. Le chiamate usano la quota di crediti del piano API dell'account e il risultato compare anche in I miei file.
Invia la chiave in Authorization: Bearer tr_live_.... Vale solo su /api/v1: il login del sito lì non vale e la chiave non vale sulle altre rotte dell'API.
L'elaborazione è asincrona: la creazione risponde subito con l'id e status: queued. Controlla l'avanzamento con GET o ricevi un webhook al termine. Il testo arriva in result.text.
Esempio: creare una trascrizione
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": "..."}, ...}
Ogni avviso webhook porta l'intestazione X-Transcritor-Signature: t=...,v1=..., l'HMAC-SHA256 di t.corpo con il tuo segreto (whsec_..., nella scheda Opzioni di Il mio account). Verifica la firma e rifiuta gli avvisi con t vecchio. Solo indirizzi https pubblici. Se il tuo sistema non risponde 2xx, riproviamo fino a 4 volte; poi controlla con GET.
Verificare la firma di un 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"])
Il limite di richieste al minuto dipende dal piano e vale per chiave (risposta 429 con Retry-After). Quota di crediti esaurita: risposta 402 cota_esgotada. Un invio alla volta per account: se ricevi 409 envio_em_andamento, riprova tra qualche secondo.
Piani dell'API
L'API ha una quota propria, separata da quella del sito. I crediti sono gli stessi del sito (1 credito per file, o ogni 5 minuti di video) e si azzerano ogni mese. Il limite di richieste al minuto vale per chiave. I glossari nell'API sono disponibili dal piano Startup.
Startup e Business si sottoscrivono con carta, tramite Mercado Pago, in Piani (scheda API), mensili o annuali (l'annuale costa 10 mensilità). Il piano ha effetto solo dopo l'approvazione del pagamento e si rinnova da solo sulla carta salvata; se il rinnovo viene rifiutato per più di 3 giorni, l'account torna a Developer. Puoi annullare quando vuoi nella stessa schermata. Startup è incluso anche nel Combo Completo + API. Enterprise è su richiesta: contatta il supporto.
Rotte
POST /api/v1/transcriptions·POST /api/v1/transcriptions/upload: Crea una trascrizione da un indirizzo (JSON) o da un file (multipart). Accetta glossary_id, webhook_url e metadata.GET /api/v1/transcriptions/{id}: Stato (queued, processing, completed, failed, canceled) e, quando pronta, il testo in result.text.GET /api/v1/transcriptions: Elenco paginato delle trascrizioni fatte via API, senza il testo.DELETE /api/v1/transcriptions/{id}: Se in corso, la annulla; poi la toglie dall'elenco. Il testo resta in I miei file.GET /api/v1/usage: Piano, limite del mese, usato, residuo, crediti extra e limite al minuto.POST|GET /api/v1/webhooks·DELETE /api/v1/webhooks/{id}·GET /api/v1/webhooks/deliveries: Registra gli indirizzi di avviso (https) e mostra la cronologia delle consegne.GET|POST /api/v1/glossaries·GET|POST /api/v1/glossaries/{id}/terms: Glossari e termini in blocco (fino a 500 per chiamata), per azzeccare nomi e termini tecnici.POST|GET /api/v1/transcriptions/{id}/studio: Modalità Studio tramite API: genera i capitoli YouTube (chapters), le show notes (show_notes) o gli hook (hooks) di una trascrizione, con la chiave IA dell'account. Consuma 5 crediti API per kit (gli altri prodotti dello stesso episodio nel mese non costano altro) e avvisa tramite webhook (studio.completed e studio.failed). Il GET restituisce il kit pronto.