Une API lisible par machine : OpenAPI 3.1, Markdown et llms.txt

Kevin van Zonneveld

Cofondateur · Amsterdam, Pays-Bas · Afficher la bio

Si vous intégrez Transloadit sans l’un de nos SDK, vous avez jusqu’ici dû lire la documentation et écrire à la main chaque appel HTTP, corps de requête et gestionnaire de webhook. Désormais, l’ensemble de l’API est publié sous forme de document OpenAPI 3.1, y compris le webhook que nous vous envoyons, et chaque page de notre site est également disponible en Markdown. Générez un client typé dans votre langage, importez l’API dans Postman, vérifiez les charges utiles des webhooks à l’aide de schémas réels et orientez votre agent de programmation IA vers une documentation qu’il peut réellement lire.

Ce que couvre la spécification

Le document se trouve à l’adresse https://api2.transloadit.com/openapi.json. Le même fichier est disponible à l’adresse https://transloadit.com/openapi.json. Il utilise OpenAPI 3.1.2 pour la version 2.0.0 de notre API et comprend 43 opérations réparties sur 26 chemins :

• Assemblies : créer, consulter le statut, annuler et réexécuter. Les Assembly Notifications peuvent également être listées et renvoyées.
• Templates, entrées d’informations d’accès de Template et Auth Keys avec leurs portées.
• Téléversements tus avec reprise, statistiques des Assemblies, facturation et statistiques des files d’attente.
• POST /token pour les jetons porteurs OAuth 2.0 obtenus avec des identifiants client. Chaque opération indique la portée dont elle a besoin, par exemple templates:read.

Les schémas de requête comprennent l’intégralité des Assembly Instructions. Chaque Step est décrit par le schéma des paramètres de son Robot. Les réponses indiquent les codes d’erreur que chaque point de terminaison peut renvoyer, par exemple TEMPLATE_LIST_ERROR. À ce jour, la section webhooks de la spécification décrit également l’Assembly Notification que nous envoyons par POST à votre notify_url.

Générer un client typé

Voici la démarche pour TypeScript, avec openapi-typescript⁠ pour les types et son outil complémentaire openapi-fetch pour les appels :

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

Par défaut, openapi-typescript marque comme obligatoire toute propriété ayant une valeur par défaut. Cela vous obligerait à fournir des paramètres de Robot qui sont facultatifs dans la spécification. --default-non-nullable false les conserve facultatifs. Notre tsconfig.json définit skipLibCheck, car le fichier généré contient un type récursif de valeur JSON que TypeScript signale autrement comme une erreur :

{
  "compilerOptions": {
    "module": "nodenext",
    "target": "esnext",
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true
  }
}

Ce script list-templates.ts liste vos Templates. Il utilise Signature Authentication, et la fonction utilitaire signParams de @transloadit/utils se charge de la signature :

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 . vérifie les types du script. Node.js 22.18 et les versions ultérieures peuvent exécuter directement le fichier 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

Les types proviennent de la spécification, donc tsc bloque un chemin mal saisi comme '/templats' ou un champ comme template.nmae avant l’envoi de la requête. Après la vérification if (error), le type de data est identifié comme celui de la réponse de succès.

Comme nous publions une spécification OpenAPI 3.1 standard, vous pouvez utiliser le générateur adapté à votre propre langage. Postman, Insomnia et les outils similaires importent le document à partir de son URL. Pour le vérifier, nous avons soumis la spécification au convertisseur openapi-to-postmanv2 de Postman. Il a produit une collection contenant les 43 requêtes réparties dans 12 dossiers. Dans un client d’API, les jetons porteurs sont le moyen le plus simple de vous connecter : obtenez-en un auprès de POST /token, puis envoyez-le sous la forme Authorization: Bearer ….

Webhooks typés et événements de statut en temps réel

Nous envoyons chaque Assembly Notification à votre notify_url sous forme de deux champs de formulaire. transloadit contient l’Assembly Status au format JSON. signature est une empreinte HMAC-SHA1 de cette chaîne exacte, représentée en hexadécimal avec des lettres minuscules et calculée avec votre Auth Secret. Le schéma de la charge utile figure dans la spécification sous le nom assemblyNotificationPayload et est également publié sous forme de schéma JSON autonome. Après avoir vérifié la signature, vous pouvez valider la charge utile à l’aide de ce schéma et obtenir un résultat typé :

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
}

Nous avons testé cela sur une véritable Assembly qui utilisait 🤖 /http/import et 🤖 /image/resize comme Robots. Son statut final a passé la validation. TypeScript a ensuite affiné son type à partir de ok === 'ASSEMBLY_COMPLETED', ce qui nous a donné accès à results.resized. Une charge utile contenant une valeur inventée pour ok a été rejetée avec must be equal to one of the allowed values.

Pour suivre la progression en temps réel, chaque Assembly Status comprend une valeur update_stream_url. Envoyez une requête GET avec Accept: text/event-stream à cette URL et vous recevrez des Server-Sent Events pendant l’exécution de l’Assembly : assembly_upload_finished, assembly_result_finished, assembly_execution_progress, assembly_error et un message de clôture assembly_finished. La référence du flux documente chaque événement et fournit un lien vers un schéma JSON pour la charge utile de chacun.

Chaque page en Markdown, et llms.txt pour les agents

Les agents de programmation IA écrivent de meilleures intégrations lorsqu’ils lisent du Markdown clair plutôt que d’extraire du contenu HTML. Chaque page publique de transloadit.com possède désormais une version Markdown. Pour l’obtenir, remplacez la barre oblique finale par .md : /docs/api/webhooks/ devient ainsi /docs/api/webhooks.md. Vous pouvez aussi envoyer Accept: text/markdown à l’URL habituelle. Les réponses HTML signalent cette version dans un en-tête Link avec rel="alternate", ce qui permet aux outils qui lisent les en-têtes de réponse de la découvrir.

$ 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
…

Pour découvrir les ressources, /llms.txt constitue un index compact. Il fournit des liens vers nos pages de démarrage, la documentation Markdown de chaque Robot et des index consacrés à la documentation, à l’API, aux Robots, aux SDK et à la FAQ. Il propose également des index thématiques pour la vidéo, les images, l’audio, les documents, le téléversement, le stockage et le dépannage. Il oriente aussi les agents vers la spécification :

$ 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.

Nous publions toujours /llms-full.txt, un fichier unique d’environ 1,5 MB. Les agents obtiennent généralement de meilleurs résultats en partant de llms.txt et en récupérant uniquement les pages dont ils ont besoin. Nous avons détaillé cette approche dans Rendre les API et la documentation plus accessibles aux outils d’IA. Si vous souhaitez que votre agent téléverse et traite lui-même des fichiers plutôt que d’écrire du code, utilisez le Transloadit MCP Server EN (English) ou nos Agent Skills. Notre guide des agents IA vous aide à choisir entre ces options.

Points à retenir

• Avec Signature Authentication, params est une chaîne JSON signée. TypeScript vérifie la requête et la réponse, mais ne vérifie pas ce que vous mettez dans params. L’API valide ce contenu lorsque vous envoyez la requête.
• POST /assemblies accepte multipart/form-data. Nous avons trouvé plus simple d’envoyer un corps FormData avec un simple fetch et d’utiliser les types générés pour la réponse.
• OpenAPI 3.1 ne peut pas typer les événements individuels d’un flux. C’est pourquoi le flux de statut est documenté dans sa page de référence et ses schémas d’événements, plutôt que comme un chemin ordinaire dans openapi.json.
• Pour les téléversements depuis un navigateur ou un appareil mobile, nos SDK restent la voie la plus directe. Ils ajoutent à cette même API la reprise des téléversements, les nouvelles tentatives et le suivi de la progression.

Importez https://api2.transloadit.com/openapi.json dans votre générateur ou votre client d’API, consultez la référence de l’API et créez un compte gratuit pour essayer avec votre propre Auth Key. Si un générateur rencontre une difficulté dans le document, faites-le-nous savoir.