Maschinenlesbare API: OpenAPI 3.1, Markdown-Doku und llms.txt

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande ·

Wenn Sie Transloadit ohne eines unserer SDKs integrieren, mussten Sie bisher die Dokumentation lesen und jeden HTTP-Aufruf, Anfragekörper und Webhook-Handler von Hand schreiben. Jetzt ist die gesamte API als OpenAPI-3.1-Dokument veröffentlicht, einschließlich des Webhooks, den wir Ihnen senden. Außerdem ist jede Seite unserer Website als Markdown verfügbar. Generieren Sie einen typisierten Client in Ihrer Sprache, importieren Sie die API in Postman, prüfen Sie Webhook-Payloads anhand echter Schemas und verweisen Sie Ihren KI-Coding-Agenten auf Dokumentation, die er tatsächlich lesen kann.

Was die Spezifikation abdeckt

Das Dokument liegt unter https://api2.transloadit.com/openapi.json. Dieselbe Datei wird unter https://transloadit.com/openapi.json gespiegelt. Sie verwendet OpenAPI 3.1.2 für Version 2.0.0 unserer API und umfasst 43 Operationen auf 26 Pfaden:

Assemblies: erstellen, Status abrufen, abbrechen und erneut ausführen. Assembly Notifications lassen sich ebenfalls auflisten und erneut senden.
Templates, Template-Zugangsdaten und Auth Keys mit ihren Scopes.
Fortsetzbare tus-Uploads, Assembly-Statistiken, Abrechnung und Queue-Statistiken.
POST /token für Bearer-Tokens mit dem Client-Credentials-Verfahren von OAuth 2.0. Jede Operation nennt den benötigten Scope, etwa templates:read.

Die Anfrageschemas enthalten die vollständigen Assembly Instructions. Jeder Step wird durch das Parameterschema für den zugehörigen Robot beschrieben. Die Antworten führen die Fehlercodes auf, die jeder Endpunkt zurückgeben kann, etwa TEMPLATE_LIST_ERROR. Stand heute beschreibt auch der Abschnitt webhooks der Spezifikation die Assembly Notification, die wir per POST an Ihre notify_url senden.

Einen typisierten Client generieren

Hier ist der Weg für TypeScript, mit openapi-typescript für die Typen und dem zugehörigen openapi-fetch für die Aufrufe:

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

Standardmäßig markiert openapi-typescript jede Eigenschaft mit einem Standardwert als erforderlich. Dadurch müssten Sie Robot-Parameter übergeben, die laut Spezifikation optional sind. --default-non-nullable false sorgt dafür, dass sie optional bleiben. In unserer Datei tsconfig.json wird skipLibCheck gesetzt, weil die generierte Datei einen rekursiven Typ für JSON-Werte enthält, den TypeScript sonst als Fehler meldet:

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

Das Skript list-templates.ts listet Ihre Templates auf. Es verwendet Signature Authentication, und die Hilfsfunktion signParams aus @transloadit/utils übernimmt das Signieren:

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 . prüft die Typen im Skript. Node.js 22.18 und spätere Versionen können die TypeScript-Datei direkt ausführen:

$ 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

Die Typen stammen aus der Spezifikation. Deshalb fängt tsc einen falsch geschriebenen Pfad wie '/templats' oder ein Feld wie template.nmae ab, bevor die Anfrage gesendet wird. Nach der Prüfung von if (error) steht fest, dass data die Erfolgsantwort ist.

Da wir standardkonformes OpenAPI 3.1 veröffentlichen, können Sie stattdessen den Generator für Ihre eigene Sprache verwenden. Postman, Insomnia und ähnliche Tools importieren das Dokument über seine URL. Zur Kontrolle haben wir die Spezifikation mit dem Konverter openapi-to-postmanv2 von Postman verarbeitet. Er erzeugte eine Collection mit allen 43 Anfragen in 12 Ordnern. In einem API-Client sind Bearer-Tokens der einfachste Weg zur Anmeldung: Rufen Sie ein Token von POST /token ab und senden Sie es anschließend als Authorization: Bearer ….

Typisierte Webhooks und Statusereignisse in Echtzeit

Wir senden jede Assembly Notification als zwei Formularfelder an Ihre notify_url. transloadit enthält den Assembly Status als JSON. signature ist ein hexadezimaler HMAC-SHA1-Wert in Kleinbuchstaben für genau diese Zeichenfolge, der mit Ihrem Auth Secret erzeugt wird. Das Payload-Schema ist in der Spezifikation als assemblyNotificationPayload enthalten und wird auch als eigenständiges JSON Schema veröffentlicht. Nachdem Sie die Signatur überprüft haben, können Sie die Payload anhand dieses Schemas prüfen und ein typisiertes Ergebnis erhalten:

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
}

Wir haben dies mit einer echten Assembly getestet, die die Robots 🤖 /http/import und 🤖 /image/resize verwendete. Ihr abschließender Status bestand die Validierung. TypeScript grenzte den Typ anschließend anhand von ok === 'ASSEMBLY_COMPLETED' ein, wodurch wir auf results.resized zugreifen konnten. Eine Payload mit einem erfundenen Wert für ok wurde mit must be equal to one of the allowed values abgelehnt.

Für Fortschrittsmeldungen in Echtzeit enthält jeder Assembly Status eine update_stream_url. Senden Sie eine Anfrage mit GET und Accept: text/event-stream an diese URL. Dann erhalten Sie während der Ausführung der Assembly Server-Sent Events: assembly_upload_finished, assembly_result_finished, assembly_execution_progress, assembly_error und eine abschließende Nachricht assembly_finished. Die Stream-Referenz dokumentiert jedes Ereignis und verlinkt für jede Ereignis-Payload ein JSON Schema.

Jede Seite als Markdown und llms.txt für Agenten

KI-Coding-Agenten schreiben bessere Integrationen, wenn sie sauberes Markdown lesen, statt HTML auszulesen. Jede öffentliche Seite auf transloadit.com hat jetzt eine Markdown-Version. Um sie abzurufen, ersetzen Sie den abschließenden Schrägstrich durch .md. So wird /docs/api/webhooks/ zu /docs/api/webhooks.md. Sie können auch Accept: text/markdown an die reguläre URL senden. HTML-Antworten weisen in einem Header Link mit rel="alternate" auf die Markdown-Version hin. So können Tools, die Antwort-Header lesen, sie entdecken.

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

Als kompakter Index hilft /llms.txt beim Finden der Inhalte. Er verlinkt unsere Einstiegsseiten, die Markdown-Dokumentation für jeden Robot und separate Indizes für Dokumentation, API, Robots, SDKs und FAQ. Außerdem verlinkt er Themenindizes für Video, Bilder, Audio, Dokumente, Uploads, Speicherung und Fehlerbehebung. Und er verweist Agenten auf die Spezifikation:

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

Wir veröffentlichen weiterhin /llms-full.txt, eine einzelne Datei mit etwa 1,5 MB. Agenten erzielen meist bessere Ergebnisse, wenn sie bei llms.txt beginnen und nur die benötigten Seiten abrufen. Mehr zu diesem Ansatz finden Sie in unserem Artikel APIs und Dokumentation für KI-Tools leichter zugänglich machen. Wenn Ihr Agent selbst Dateien hochladen und verarbeiten soll, statt Code zu schreiben, nutzen Sie den Transloadit MCP Server oder unsere Agenten-Skills. Unser Leitfaden zu KI-Agenten hilft Ihnen bei der Auswahl.

Was Sie beachten sollten

Bei Signature Authentication ist params eine signierte JSON-Zeichenfolge. TypeScript prüft die Anfrage und die Antwort, aber nicht den Inhalt, den Sie in params einsetzen. Die API validiert ihn, wenn Sie die Anfrage senden.
POST /assemblies nimmt multipart/form-data entgegen. Für uns war es einfacher, für den Anfragekörper FormData zu verwenden, ihn mit einfachem fetch zu senden und die generierten Typen für die Antwort zu nutzen.
OpenAPI 3.1 kann die einzelnen Ereignisse eines Streams nicht typisieren. Deshalb ist der Statusstream auf seiner Referenzseite und in Ereignisschemas dokumentiert, statt als regulärer Pfad in openapi.json.
Für Uploads aus Browsern und mobilen Anwendungen bleiben unsere SDKs der kürzeste Weg. Sie ergänzen dieselbe API um fortsetzbare Uploads, Retries und Fortschrittsmeldungen.

Importieren Sie https://api2.transloadit.com/openapi.json in Ihren Generator oder API-Client, lesen Sie die API-Referenz und erstellen Sie ein kostenloses Konto, um die API mit Ihrem eigenen Auth Key auszuprobieren. Wenn ein Generator bei etwas im Dokument scheitert, geben Sie uns Bescheid.