Una API legible por máquinas: OpenAPI 3.1, documentación en Markdown y llms.txt
Si integras Transloadit sin uno de nuestros SDK, hasta ahora has tenido que leer la documentación y escribir a mano cada llamada HTTP, cuerpo de solicitud y manejador de webhooks. Ahora toda la API está publicada como un documento OpenAPI 3.1, incluido el webhook que te enviamos, y cada página de nuestro sitio web también está disponible en Markdown. Genera un cliente tipado en tu lenguaje, importa la API en Postman, comprueba las cargas útiles de los webhooks con esquemas reales y dirige a tu agente de programación con IA a documentación que realmente pueda leer.
Qué abarca la especificación
El documento está en https://api2.transloadit.com/openapi.json. El mismo archivo tiene una copia en
https://transloadit.com/openapi.json. Utiliza OpenAPI 3.1.2 para la versión 2.0.0 de nuestra API y
contiene 43 operaciones distribuidas en 26 rutas:
- Assemblies: crear, consultar el estado, cancelar y reejecutar. Las Assembly Notifications también se pueden listar y reenviar.
- Templates, credenciales de Template y Auth Keys con sus ámbitos.
- Subidas reanudables mediante el protocolo tus, estadísticas de Assemblies, facturación y estadísticas de las colas.
POST /tokenpara tokens Bearer de OAuth 2.0 mediante credenciales de cliente. Cada operación indica el ámbito que necesita, comotemplates:read.
Los esquemas de solicitud incluyen las Assembly
Instructions completas. Cada Step se describe mediante el esquema de parámetros de su
Robot. Las respuestas enumeran los códigos de error que cada
endpoint puede devolver, como TEMPLATE_LIST_ERROR. A día de hoy, la sección
webhooks de la especificación también describe la Assembly Notification
que enviamos mediante POST a tu notify_url.
Genera un cliente tipado
Esta es la opción para TypeScript, con openapi-typescript para los
tipos y su complemento openapi-fetch para las llamadas:
mkdir my-app && cd my-app
npm init -y && npm pkg set type=module
npm install openapi-fetch @transloadit/utils ajv
npm install -D openapi-typescript typescript @types/node
npx openapi-typescript https://api2.transloadit.com/openapi.json \
--default-non-nullable false -o transloadit-api.d.ts
De forma predeterminada, openapi-typescript marca como obligatoria toda propiedad que tenga un
valor predeterminado. Eso te obligaría a pasar parámetros de Robot que son opcionales en la
especificación. --default-non-nullable false los mantiene opcionales. Nuestro
tsconfig.json establece skipLibCheck, porque el archivo generado
contiene un tipo recursivo para valores JSON que, de otro modo, TypeScript señala como error:
{
"compilerOptions": {
"module": "nodenext",
"target": "esnext",
"strict": true,
"noEmit": true,
"skipLibCheck": true,
"allowImportingTsExtensions": true,
"erasableSyntaxOnly": true,
"verbatimModuleSyntax": true
}
}
Este script list-templates.ts lista tus Templates.
Utiliza autenticación con firma, y la función auxiliar signParams de
@transloadit/utils se encarga de la firma:
import { signParams } from '@transloadit/utils'
import createClient from 'openapi-fetch'
import type { paths } from './transloadit-api.d.ts'
const { TRANSLOADIT_KEY: key, TRANSLOADIT_SECRET: secret } = process.env
if (!key || !secret) throw new Error('Set TRANSLOADIT_KEY and TRANSLOADIT_SECRET')
const client = createClient<paths>({ baseUrl: 'https://api2.transloadit.com' })
const expires = new Date(Date.now() + 5 * 60_000).toISOString()
const params = JSON.stringify({ auth: { key, expires }, pagesize: 3 })
const signature = await signParams(params, secret)
const { data, error } = await client.GET('/templates', {
params: { query: { params, signature } },
})
if (error) throw new Error(`${error.error}: ${error.message}`)
console.log(`${data.count} Templates, showing ${data.items.length}:`)
for (const template of data.items) console.log(`- ${template.id} ${template.name}`)
npx tsc -p . comprueba los tipos del script. Node.js 22.18 y versiones posteriores
pueden ejecutar directamente el archivo TypeScript:
$ TRANSLOADIT_KEY=MY_AUTH_KEY TRANSLOADIT_SECRET=MY_SECRET_KEY node list-templates.ts
1726 Templates, showing 3:
- 1329f8… image-enhancer-v6
- d253c5… webm-to-mp4-v6
- e751d2… convert-an-image-from-avif-to-jpg-v6
Los tipos proceden de la especificación, por lo que tsc detecta una ruta
mal escrita, como '/templats', o un campo mal escrito, como
template.nmae, antes de que se envíe la solicitud. Tras la comprobación de
if (error), se sabe que data es la respuesta de éxito.
Como publicamos OpenAPI 3.1 estándar, también puedes usar el generador de tu propio lenguaje.
Postman, Insomnia y herramientas similares importan el documento desde su URL. Para comprobarlo,
pasamos la especificación por el conversor openapi-to-postmanv2 de Postman. Produjo una
colección con las 43 solicitudes en 12 carpetas. En un cliente de API, los tokens Bearer son la
forma más sencilla de iniciar sesión: obtén uno de
POST /token y envíalo como
Authorization: Bearer ….
Webhooks tipados y eventos de estado en tiempo real
Enviamos cada Assembly Notification a tu notify_url como dos campos de
formulario. transloadit contiene el Assembly Status en formato JSON.
signature es un HMAC-SHA1 hexadecimal en minúsculas de esa cadena exacta,
generado con tu Auth Secret. El esquema de la carga útil figura en la especificación como
assemblyNotificationPayload y también está publicado como un JSON Schema independiente.
Verifica la firma y, después, puedes comprobar la carga útil con
ese esquema y obtener un resultado tipado:
import { Ajv } from 'ajv'
import type { components } from './transloadit-api.d.ts'
type AssemblyNotification = components['schemas']['assemblyNotificationPayload']
const url = 'https://transloadit.com/api-reference/schemas/webhooks/verified-json-payload.json'
const response = await fetch(url)
if (!response.ok) throw new Error(`GET ${url} failed with HTTP ${response.status}`)
const validate = new Ajv({ strict: false }).compile<AssemblyNotification>(await response.json())
// Call this only after verifying `signature` over the raw `transloadit` field
export function parseNotification(transloadit: string): AssemblyNotification {
const payload: unknown = JSON.parse(transloadit)
if (!validate(payload)) throw new Error(`Unexpected payload: ${validate.errors?.[0]?.message}`)
return payload
}
Probamos esto con una Assembly real que utilizaba los
Robots
🤖 /http/import y 🤖 /image/resize.
Su estado final pasó la validación. TypeScript
acotó entonces su tipo mediante ok === 'ASSEMBLY_COMPLETED', lo que nos dio acceso a
results.resized. Una carga útil con un valor inventado de
ok fue rechazada con must be equal to one of the allowed values.
Para consultar el progreso en tiempo real, cada Assembly Status incluye un
update_stream_url. Envía una solicitud GET con
Accept: text/event-stream a esa URL y recibirás Server-Sent Events mientras se ejecuta la
Assembly: assembly_upload_finished, assembly_result_finished,
assembly_execution_progress, assembly_error y un mensaje de cierre
assembly_finished. La referencia del stream
documenta cada evento y enlaza un JSON Schema para la carga útil de cada uno.
Cada página en Markdown y llms.txt para agentes
Los agentes de programación con IA escriben mejores integraciones cuando leen Markdown limpio
en lugar de extraer contenido del HTML. Cada página pública de transloadit.com tiene ahora una
versión equivalente en Markdown. Para obtenerla, sustituye la barra final por
.md, de modo que /docs/api/webhooks/ se convierte en
/docs/api/webhooks.md. También puedes enviar Accept: text/markdown a la URL
habitual. Las respuestas HTML anuncian la versión equivalente en un encabezado
Link con rel="alternate", para que las herramientas que
leen los encabezados de respuesta puedan descubrirla.
$ curl -fsSL https://transloadit.com/docs/robots/image-resize.md
# Convert, resize, or watermark images
Robot: `/image/resize`
🤖/image/resize resizes, crops, changes colorization, rotation, and applies text and watermarks to images.
Stage: ga
…
Para descubrir el contenido, /llms.txt ofrece
un índice compacto. Enlaza nuestras páginas de inicio, la documentación en Markdown de cada
Robot e índices específicos para la documentación, la API, los Robots, los SDK y las preguntas
frecuentes. También enlaza índices temáticos de video, imágenes, audio, documentos, subidas,
almacenamiento y resolución de problemas. Además, dirige a los agentes a la especificación:
$ curl -fsSL https://transloadit.com/llms.txt | grep -E 'OpenAPI|API endpoints'
- [Agent integration options](https://transloadit.com/mcp/): Upload, import, process, export, or retrieve files through MCP, OpenAPI, or an SDK.
- [API endpoints](https://transloadit.com/docs/api/llms.txt): Learn how you can leverage Transloadit’s file processing services most effectively
- [OpenAPI document](https://transloadit.com/openapi.json): Typed REST schema for generated clients and tools.
Seguimos publicando /llms-full.txt, un único archivo de unos 1,5 MB. Los agentes
suelen obtener mejores resultados cuando empiezan por llms.txt y recuperan
solo las páginas que necesitan. Escribimos más sobre ese enfoque en
Cómo hacer que las API y la documentación sean más accesibles para las herramientas de IA. Si quieres
que tu agente suba y procese archivos por sí mismo en lugar de escribir código, utiliza el
Transloadit MCP Server o nuestras
Skills para agentes. Nuestra
guía de agentes de IA te ayuda a elegir entre estas opciones.
Qué debes tener en cuenta
- Con la autenticación con firma,
paramses una cadena JSON firmada. TypeScript comprueba la solicitud y la respuesta, pero no comprueba lo que incluyes enparams. La API lo valida cuando envías la solicitud. POST /assembliesrecibemultipart/form-data. Nos resultó más sencillo enviar un cuerpoFormDataconfetchsin más y usar los tipos generados para la respuesta.- OpenAPI 3.1 no puede definir tipos para los eventos individuales de un stream. Por eso, el stream
de estado está documentado en su página de referencia y en los esquemas de eventos, en lugar de
figurar como una ruta normal en
openapi.json. - Para las subidas desde navegadores y dispositivos móviles, nuestros SDK siguen siendo la vía más corta. Añaden subidas reanudables, reintentos e informes de progreso sobre la misma API.
Importa https://api2.transloadit.com/openapi.json en tu generador o cliente de API, consulta la
referencia de la API y crea una cuenta gratuita
para probarla con tu propia Auth Key. Si un generador encuentra algún problema en el documento,
avísanos.