API de TranscritorAi
Tous les points de terminaison de l'API, ce que fait chacun et s'il nécessite une connexion. Les mêmes données sont aussi disponibles dans les formats automatiques ci-dessous.
L'URL de base est l'adresse de ce site lui-même (même origine : il n'existe pas de domaine d'API séparé).
Les endpoints marqués "Connexion requise" attendent l'en-tête Authorization: Bearer
Comptes avec vérification en deux étapes : POST /api/auth/login répond requer_2fa: true et un desafio (défi) ; envoyez le défi et le code à 6 chiffres à POST /api/auth/login/2fa pour recevoir le jeton. Sur le site web, la session vit dans un cookie HttpOnly ; l'API pour scripts continue d'utiliser 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 pour développeurs (v1)
Utilisez une clé d'API pour transcrire depuis votre propre système. Créez la clé dans Mon compte, onglet Options. Les appels utilisent le quota de crédits du forfait API du compte et le résultat apparaît aussi dans Mes fichiers.
Envoyez la clé dans Authorization: Bearer tr_live_.... Elle ne vaut que sur /api/v1 : la connexion du site n'y vaut pas et la clé ne vaut pas sur les autres routes de l'API.
Le traitement est asynchrone : la création répond aussitôt avec l'id et status: queued. Suivez l'avancement avec GET ou recevez un webhook à la fin. Le texte arrive dans result.text.
Exemple : créer une 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": "..."}, ...}
Chaque notification webhook porte l'en-tête X-Transcritor-Signature: t=...,v1=..., le HMAC-SHA256 de t.corps avec votre secret (whsec_..., onglet Options de Mon compte). Vérifiez la signature et refusez les notifications dont le t est ancien. Adresses https publiques uniquement. Si votre système ne répond pas 2xx, nous réessayons jusqu'à 4 fois ; ensuite, consultez avec GET.
Vérifier la signature d'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"])
La limite de requêtes par minute dépend du forfait et vaut par clé (réponse 429 avec Retry-After). Quota de crédits épuisé : réponse 402 cota_esgotada. Un envoi à la fois par compte : si vous recevez 409 envio_em_andamento, réessayez dans quelques secondes.
Forfaits de l'API
L'API a son propre quota, distinct de celui du site. Les crédits sont les mêmes que sur le site (1 crédit par fichier, ou par tranche de 5 minutes de vidéo) et sont remis à zéro chaque mois. La limite de requêtes par minute vaut par clé. Les glossaires dans l'API sont disponibles à partir de Startup.
Startup et Business se souscrivent par carte, via Mercado Pago, dans Offres (onglet API), en mensuel ou en annuel (l'annuel coûte 10 mensualités). Le forfait ne prend effet qu'après l'approbation du paiement et se renouvelle automatiquement sur la carte enregistrée ; si le renouvellement est refusé pendant plus de 3 jours, le compte revient à Developer. Vous pouvez résilier quand vous voulez sur le même écran. Startup est aussi inclus dans le Combo Complet + API. Enterprise est sur devis : contactez le support.
Routes
POST /api/v1/transcriptions·POST /api/v1/transcriptions/upload: Crée une transcription à partir d'une adresse (JSON) ou d'un fichier (multipart). Accepte glossary_id, webhook_url et metadata.GET /api/v1/transcriptions/{id}: État (queued, processing, completed, failed, canceled) et, une fois prête, le texte dans result.text.GET /api/v1/transcriptions: Liste paginée des transcriptions faites par API, sans le texte.DELETE /api/v1/transcriptions/{id}: Si elle est en cours, l'annule ; puis la retire de la liste. Le texte reste dans Mes fichiers.GET /api/v1/usage: Forfait, limite du mois, utilisé, restant, crédits supplémentaires et limite par minute.POST|GET /api/v1/webhooks·DELETE /api/v1/webhooks/{id}·GET /api/v1/webhooks/deliveries: Enregistre les adresses de notification (https) et consulte l'historique des envois.GET|POST /api/v1/glossaries·GET|POST /api/v1/glossaries/{id}/terms: Glossaires et termes par lot (jusqu'à 500 par appel), pour bien reconnaître noms et termes techniques.POST|GET /api/v1/transcriptions/{id}/studio: Mode Studio par l'API : génère les chapitres YouTube (chapters), les show notes (show_notes) ou les hooks (hooks) d'une transcription, avec la clé d'IA du compte. Consomme 5 crédits d'API par kit (les autres produits du même épisode dans le mois ne coûtent rien de plus) et prévient par les webhooks (studio.completed et studio.failed). Le GET renvoie le kit prêt.