API de TranscritorAi
Todos los endpoints de la API, qué hace cada uno y si necesita inicio de sesión. Los mismos datos también están disponibles en los formatos automáticos de abajo.
La URL base es la propia dirección de este sitio (mismo origen: no existe un dominio de API separado).
Los endpoints marcados como "Requiere inicio de sesión" esperan el encabezado Authorization: Bearer
Cuentas con verificación en dos pasos: POST /api/auth/login responde requer_2fa: true y un desafio; envía el desafío y el código de 6 dígitos a POST /api/auth/login/2fa para recibir el token. En el sitio web la sesión vive en una cookie HttpOnly; la API para scripts sigue usando 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 desarrolladores (v1)
Usa una clave de API para transcribir desde dentro de tu sistema. Crea la clave en Mi cuenta, en la pestaña Opciones. Las llamadas usan la cuota de créditos del plan de API de la cuenta y el resultado también aparece en Mis archivos.
Envía la clave en Authorization: Bearer tr_live_.... Solo vale en /api/v1: el inicio de sesión del sitio no vale allí y la clave no vale en las demás rutas de la API.
El procesamiento es asíncrono: la creación responde al instante con el id y status: queued. Consulta el avance con GET o recibe un webhook al terminar. El texto llega en result.text.
Ejemplo: crear una transcripción
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 trae la cabecera X-Transcritor-Signature: t=...,v1=..., el HMAC-SHA256 de t.cuerpo con tu secreto (whsec_..., en la pestaña Opciones de Mi cuenta). Comprueba la firma y rechaza avisos con un t antiguo. Solo direcciones https públicas. Si tu sistema no responde 2xx, reintentamos hasta 4 veces; después, consulta con GET.
Comprobar la firma de 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"])
El límite de solicitudes por minuto depende del plan y vale por clave (respuesta 429 con Retry-After). Cuota de créditos agotada: respuesta 402 cota_esgotada. Un envío a la vez por cuenta: si recibes 409 envio_em_andamento, inténtalo de nuevo en unos segundos.
Planes de la API
La API tiene una cuota propia, separada de la del sitio. Los créditos son los mismos del sitio (1 crédito por archivo, o cada 5 minutos de vídeo) y se reinician cada mes. El límite de solicitudes por minuto vale por clave. Los glosarios en la API valen desde Startup.
Startup y Business se contratan con tarjeta, mediante Mercado Pago, en Planes (pestaña API), mensual o anual (el anual cuesta 10 mensualidades). El plan solo vale cuando se aprueba el pago y se renueva solo en la tarjeta guardada; si la renovación es rechazada durante más de 3 días, la cuenta vuelve a Developer. Puedes cancelar cuando quieras en la misma pantalla. Startup también viene en el Combo Completo + API. Enterprise es bajo consulta: habla con soporte.
Rutas
POST /api/v1/transcriptions·POST /api/v1/transcriptions/upload: Crea una transcripción desde una dirección (JSON) o un archivo (multipart). Acepta glossary_id, webhook_url y metadata.GET /api/v1/transcriptions/{id}: Estado (queued, processing, completed, failed, canceled) y, cuando está lista, el texto en result.text.GET /api/v1/transcriptions: Lista paginada de las transcripciones hechas por API, sin el texto.DELETE /api/v1/transcriptions/{id}: Si está en curso, la cancela; luego la quita de la lista. El texto sigue en Mis archivos.GET /api/v1/usage: Plan, límite del mes, usado, restante, créditos extra y límite por minuto.POST|GET /api/v1/webhooks·DELETE /api/v1/webhooks/{id}·GET /api/v1/webhooks/deliveries: Registra direcciones de aviso (https) y consulta el historial de entregas.GET|POST /api/v1/glossaries·GET|POST /api/v1/glossaries/{id}/terms: Glosarios y términos en lote (hasta 500 por llamada), para acertar nombres y términos técnicos.POST|GET /api/v1/transcriptions/{id}/studio: Modo Estudio por la API: genera los capítulos de YouTube (chapters), los show notes (show_notes) o los ganchos (hooks) de una transcripción, con la clave de IA de la propia cuenta. Gasta 5 créditos de la API por kit (los demás productos del mismo episodio en el mes no cuestan más) y avisa por los webhooks (studio.completed y studio.failed). El GET devuelve el kit listo.