Documentación de la API

Usa https://api.transcript1.com/v1 como URL base para llamar a la API.

• El cuerpo de los requests y de las respuestas es JSON. Los nombres de campo usan snake_case.
• Las fechas y horas siguen ISO 8601 en UTC: por ejemplo, 2026-10-13T09:30:00.000Z.
• Las duraciones y las marcas de tiempo de la transcripción se expresan en segundos.
• Los errores comparten una estructura; aprende a leerla en Errores.
• Las respuestas a requests autenticados llevan los headers X-RateLimit-Limit y X-RateLimit-Remaining. Revisa Facturación y límites.
• Con source=auto, se buscan primero subtítulos en el idioma original en YouTube, X, TikTok, Bluesky, Dailymotion y LinkedIn. Si no se pueden usar, se transcribe el audio con IA. No todos los videos tienen subtítulos. El modo source=captions (solo subtítulos) nunca descarga audio ni pasa a STT; si falta una pista válida, falla con no_captions. Para transcribir directamente el audio, usa source=stt o activa la identificación de hablantes. En Fuentes y opciones puedes revisar las restricciones de cada plataforma y cuáles incluyen marcas de tiempo por segmento o por palabra.

Para herramientas e integraciones, descarga la especificación OpenAPI en el formato que necesites:

• JSON
• YAML

Autentica cada request con el header Authorization, usando Authorization: Bearer <token>.

• Las claves de API empiezan con t1_ y dan acceso a todos los endpoints. Crea la tuya en “API keys”.
• Los tokens de acceso OAuth empiezan con t1o_. Claude, ChatGPT y otros clientes MCP reciben uno al conectarse. Sus permisos son transcriptions:read y transcriptions:write.

Permiso (scope)	Endpoints disponibles
transcriptions:read	GET /v1/transcriptions, GET /v1/transcriptions/:id, GET /v1/transcriptions/:id/upload y GET /v1/account
transcriptions:write	POST /v1/transcriptions, DELETE /v1/transcriptions/:id y POST /v1/transcriptions/:id/upload/complete

• Si al token le falta el permiso necesario, recibirás 403 insufficient_scope.
• Si no envías una credencial o no es válida, recibirás 401 unauthorized.

Los requests para enviar partes de un archivo usan otra credencial: autentica PUT /v1/transcriptions/:id/upload/chunks/:index con X-Upload-Token. Ese token se entrega al crear la subida. Consulta Cómo subir archivos.

Agrega el header Idempotency-Key a POST /v1/transcriptions para poder repetir el request sin crear otra transcripción.

Elige un valor de 1 a 255 caracteres. Debe ir en el header, no en los parámetros de la URL.

• Si repites la clave y los parámetros, recuperas la transcripción original sin pagar de nuevo.
• Si conservas la clave pero cambias los parámetros, recibirás 409 idempotency_conflict.
• Para una subida por partes, repetir el request de creación con la misma clave devuelve un nuevo token de subida.

• Si el error viene del request, la API no aceptó la llamada.
• Si falla la transcripción, la API sí aceptó el request, pero no pudo terminar de transcribir. El objeto queda con status en failed.

Cómo leer un error

Cuando /v1 rechaza un request, devuelve un objeto error con los campos code, message y retryable.

• Usa code para decidir qué debe hacer tu aplicación.
• Muestra la explicación de message al usuario, pero no bases tu lógica en ese texto: puede cambiar.
• Si retryable es true, puedes volver a enviar el mismo request más adelante.

Según el error, encontrarás otros campos junto a retryable:

Campo	Aparece en	Qué indica
action_url	insufficient_minutes	Enlace para contratar un plan o comprar minutos.
minutes_needed, minutes_remaining	insufficient_minutes	Minutos necesarios para el request y saldo disponible. El primero es null si aún no se sabe cuántos minutos necesita.
supported_platforms	unsupported_platform	Valores de plataforma admitidos: ["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"].
missing_chunks	upload_incomplete	Índices de las partes del archivo que faltan por recibir.
max_bytes	media_too_large	Tamaño máximo de archivo que puedes enviar, en bytes.
params	invalid_request	Objeto que detalla el problema de cada campo al validar el cuerpo o los parámetros de la URL.

Cuando la API rechaza el request

Código HTTP	code	¿Reintentar?	Qué ocurrió
400, 422	invalid_request	No	Falta un campo o parámetro, su valor no es válido o el cuerpo no es JSON válido. También ocurre al combinar diarize con source: "captions", o reuse_recent con webhook_url.
422	invalid_url	No	El enlace no se admite o no corresponde a platform. Usa YouTube, X, TikTok, Instagram, Facebook, Bluesky u otra plataforma de Fuentes y opciones.
422	unsupported_platform	No	El valor de platform no está entre los admitidos.
422	unsupported_media	No	La extensión del archivo no está admitida.
401	unauthorized	No	Falta la credencial, no es válida, venció o se revocó. También puede indicar que el token de subida no es válido o venció.
403	insufficient_scope	No	El token OAuth no tiene el permiso transcriptions:read o transcriptions:write necesario.
403	email_not_verified	No	Debes verificar tu correo antes de crear una transcripción.
402	insufficient_minutes	No	Tu saldo disponible es 0 o no alcanza para esta transcripción.
402	no_active_plan	No	No puedes comprar una recarga sin un plan de pago activo. Este error viene del endpoint de facturación del panel, no de los endpoints de transcripción.
404	not_found	No	No existe esa transcripción o es de otro equipo.
409	upload_incomplete	No	Faltan partes del archivo. Envíalas y vuelve a confirmar la subida.
409	invalid_state	No	La transcripción ya no espera una subida. No puedes enviar más partes ni confirmar que terminaste.
409	idempotency_conflict	No	Usaste antes el mismo Idempotency-Key con parámetros diferentes.
413	media_too_large	No	El archivo pesa más de lo permitido. Revisa Cómo subir archivos.
413	invalid_request	No	El cuerpo JSON supera 1 MB. Para archivos demasiado grandes, el código es media_too_large.
429	rate_limited	Sí	Superaste los requests por minuto. Espera el tiempo en segundos que indica Retry-After.
429	too_many_active_jobs	Sí	Llegaste al límite de transcripciones en curso o de subidas abiertas. Espera los segundos indicados en Retry-After.
500	internal_error	Sí	Falló algo en transcript1. Espera un momento y vuelve a intentarlo.
503	service_unavailable	Sí	El servicio no está disponible por el momento. Prueba de nuevo más tarde.

Si el navegador se autentica con una cookie de sesión, también se comprueba el origen. Un request desde otro sitio devuelve 403 forbidden_origin.

Esta comprobación no afecta a las llamadas que usan el header Authorization.

El header Retry-After aparece en todas las respuestas 429 e indica cuántos segundos debes esperar. Puedes consultar los límites de tu plan en Facturación y límites.

Cuándo volver a intentarlo

• Reenvía el request solo si retryable es true: rate_limited, too_many_active_jobs, internal_error o service_unavailable.
• Si hay Retry-After, respétalo. Si no, aumenta la espera entre intentos.
• Si repites POST /v1/transcriptions, conserva el mismo header Idempotency-Key. Así no pagas dos veces si el primer request sí se completó.
• Para los demás códigos, primero corrige lo que causó el error.

Cuando falla la transcripción

Si status es failed, encontrarás el motivo en el objeto error, con code y message.

La transcripción puede fallar después de que la API haya respondido al request de creación. Comprueba error al consultar el estado o al recibir el webhook transcription.failed.

error.code	Qué ocurrió	¿Qué puedes hacer?
media_unavailable	El video no existe o dejó de estar disponible.	No repitas el mismo envío; revisa la URL.
media_private	No se puede acceder porque el video es privado.	Usa una publicación pública o, en YouTube, un video público o no listado.
login_required	Hay que iniciar sesión en la plataforma para ver el video.	Es un fallo permanente; no se reintenta.
no_audio	El video no contiene una pista de audio.	Es un fallo permanente; no se reintenta.
age_restricted	La plataforma restringe el video por edad.	No repitas el enlace; sube el archivo.
live_stream	La transmisión sigue en vivo o todavía no empieza.	Espera a que termine para volver a enviarla.
no_captions	Pediste captions en source, pero no hay una pista de subtítulos que se pueda usar.	Cambia a source: "auto" o "stt".
media_too_long	La grabación supera las 5 horas que admite voz a texto.	Divide la grabación antes de enviarla.
unsupported_media	No se puede leer el archivo o le falta una pista de audio.	Envía un archivo en un formato admitido.
no_speech	No se detectó habla.	No lo reintentes.
unsupported_language	El idioma de la grabación no está admitido.	Configura language con un código admitido o "auto" antes de volver a enviarla.
insufficient_minutes	El saldo se agotó antes de cobrar la transcripción.	Recarga minutos y vuelve a intentarlo.
fetch_failed	No se pudo descargar la grabación después de varios intentos.	Puedes probar de nuevo más tarde.
transcription_failed	La transcripción de voz a texto falló después de varios intentos.	Puedes probar de nuevo más tarde.

Si la transcripción falla o la cancelas, no pagas nada. Si ya se habían descontado minutos, vuelven a tu saldo.

Incluye webhook_url al crear la transcripción para recibir el aviso en tu servidor. Cuando termine o falle, transcript1 enviará un POST firmado a esa URL.

Esta opción solo está en la API REST. El servidor MCP no acepta un parámetro para webhooks.

Configura dónde recibir el aviso

La ubicación de webhook_url en POST /v1/transcriptions depende de lo que envíes:

• Si envías un enlace de video admitido o reservas una subida por partes, inclúyelo en el cuerpo JSON.
• Si subes el archivo completo en un request, inclúyelo como campo del formulario.

Usa una URL que cumpla estos requisitos:

• El protocolo es HTTPS.
• No lleva usuario ni contraseña.
• Resuelve a una dirección pública.

Las direcciones privadas, loopback, link-local y cualquier otra dirección no pública devuelven 422 invalid_request. La API comprueba la dirección al crear la transcripción y antes de cada envío.

No combines webhook_url con reuse_recent=true.

Eventos

type	Cuándo lo recibes
transcription.completed	Cuando la transcripción pasa a completed.
transcription.failed	Cuando pasa a failed. Revisa code y message en data.error.

Si cancelas la transcripción, no se envía un webhook.

Qué contiene el request

El aviso llega con un cuerpo JSON que incluye:

• created_at: la fecha y hora de creación del evento.
• data: el objeto de transcripción, sin el campo transcript.

Para obtener el texto, toma el id de data y consulta GET /v1/transcriptions/:id.

El request lleva estos headers:

• Content-Type: application/json
• User-Agent: transcript1-webhooks/1.0
• X-Transcript1-Signature, la firma que se explica en la siguiente sección.

Comprueba la firma antes de leer el JSON

Busca el header X-Transcript1-Signature en cada envío. Su valor tiene el formato t=<unix seconds>,v1=<hex digest>.

• t indica cuándo se firmó el request, en segundos Unix.
• v1 contiene el HMAC-SHA256 en hexadecimal de "<t>.<raw body>". Para calcularlo, concatena el valor de t, un punto y el cuerpo exacto que recibiste. Usa tu secreto de firma completo como clave, sin quitar el prefijo whsec_.

Comprueba la firma con los bytes originales del cuerpo, antes de parsear el JSON. Si lo parseas y vuelves a serializar, los espacios o el orden de las claves pueden cambiar y la firma dejará de coincidir.

• Haz la comparación en tiempo constante.
• Rechaza los requests cuyo t se aleje demasiado de la hora actual. Los ejemplos aceptan una diferencia de hasta 5 minutos.
• En Express, recibe el cuerpo como texto sin parsearlo primero.
• En Flask, obtén el cuerpo con request.get_data(as_text=True) y pásalo a raw_body.

Dónde consultar o rotar el secreto

El secreto empieza con whsec_ y es compartido por todo el equipo: firma los webhooks de todas sus transcripciones.

Abre “Webhooks” en el panel para verlo o rotarlo.

Si lo rotas, el cambio es inmediato. Todos los envíos posteriores usan el secreto nuevo.

Respuestas, reintentos y duplicados

• Responde con cualquier código 2xx para confirmar la recepción.
• Otro código HTTP, un error de conexión o más de 10 segundos sin respuesta cuentan como un intento fallido.
• Si falla el envío, transcript1 vuelve a intentarlo hasta completar 6 intentos en total. Espera 2, 4, 8, 16 y 32 minutos entre intentos; el último ocurre aproximadamente una hora después del primero.
• Configura la URL final. transcript1 no sigue redirecciones: un 3xx también cuenta como fallo.
• Puedes recibir el mismo aviso más de una vez, por ejemplo si tu servidor responde después del timeout. Usa la combinación de data.id y type para detectar e ignorar duplicados.