機械可読な API:OpenAPI 3.1、Markdown ドキュメント、llms.txt
Transloadit を SDK なしで組み込む場合、これまではドキュメントを読み、すべての HTTP コール、リクエストボディ、webhook ハンドラーを手書きする必要がありました。今では API 全体を OpenAPI 3.1 ドキュメントとして公開しており、こちらから送信する webhook も含まれます。さらに、Web サイト上のすべてのページも Markdown で利用できます。使用言語向けの型付きクライアントを生成し、API を Postman に取り込み、webhook ペイロードを実際のスキーマで検証し、AI コーディングエージェントに実際に読めるドキュメントを渡せます。
仕様に含まれる内容
ドキュメントは https://api2.transloadit.com/openapi.json にあります。同じファイルは
https://transloadit.com/openapi.json にもミラーされています。これは API のバージョン 2.0.0 向けの
OpenAPI 3.1.2 で、26 個のパスにわたって 43 個の操作を含みます。
- Assembly:作成、ステータス確認、キャンセル、リプレイ。Assembly Notification の一覧取得とリプレイにも対応しています。
- Template、Template 認証情報、Auth Key と、それぞれのスコープ。
- 再開可能な tus アップロード、Assembly 統計、請求、キュー統計。
- OAuth 2.0 の client-credentials bearer token 用の
POST /token。各操作には、templates:readなど必要なスコープが記載されています。
リクエストスキーマには、完全な Assembly
Instructions が含まれます。各 Step は、その
Robot のパラメータスキーマで記述しています。レスポンスには、各エンドポイントが返しうる TEMPLATE_LIST_ERROR などのエラーコードが列挙されています。現時点では、仕様の webhooks
セクションに、notify_url へ POST する Assembly Notification も記載しています。
型付きクライアントの生成
TypeScript での方法は次のとおりです。型には
openapi-typescript を使い、呼び出しにはその補助である
openapi-fetch を使います。
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
openapi-typescript はデフォルトで、デフォルト値を持つすべてのプロパティを必須として扱います。そのままだと、仕様では省略可能な Robot パラメータまで渡す必要が出てしまいます。--default-non-nullable false を使うと、それらを省略可能のままにできます。私たちの tsconfig.json では skipLibCheck を設定しています。生成されるファイルに再帰的な JSON 値型が含まれており、そうしないと TypeScript がエラーとして報告するためです。
{
"compilerOptions": {
"module": "nodenext",
"target": "esnext",
"strict": true,
"noEmit": true,
"skipLibCheck": true,
"allowImportingTsExtensions": true,
"erasableSyntaxOnly": true,
"verbatimModuleSyntax": true
}
}
この list-templates.ts スクリプトは、Template の一覧を取得します。署名認証を使用し、署名処理は @transloadit/utils の
signParams ヘルパーが担当します。
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 . でスクリプトを型チェックできます。Node.js 22.18 以降なら、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
型は仕様から生成されるため、tsc により、'/templats' のような誤ったパスや template.nmae のような誤ったフィールドは、リクエスト送信前に検出されます。if (error) のチェック後は、data が成功レスポンスであると分かります。
標準の OpenAPI 3.1 を公開しているため、代わりに使用言語向けのジェネレーターも利用できます。Postman、Insomnia などのツールは、その URL からドキュメントをインポートできます。確認のため、仕様を Postman の openapi-to-postmanv2 コンバーターにも通しました。その結果、12 個のフォルダーに 43 件すべてのリクエストを含むコレクションが生成されました。API クライアントでは、bearer token がもっとも簡単なサインイン方法です。POST /token から取得し、それを Authorization: Bearer … として送信してください。
型付き webhook とライブステータスイベント
各 Assembly Notification は、notify_url に 2 つのフォームフィールドとして送信します。transloadit には、Assembly Status の JSON が入ります。signature は、その正確な文字列に対して Auth Secret で生成した小文字 16 進の HMAC-SHA1 です。ペイロードスキーマは仕様内では
assemblyNotificationPayload として定義されており、単独の JSON Schema としても公開しています。署名を検証した後、そのスキーマに対してペイロードを検証すれば、型付きの結果を取得できます。
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
}
これは、🤖 /http/import と
🤖 /image/resize の
Robot を使う実際の
Assembly でテストしました。最終ステータスは検証を通過しました。その後 TypeScript は
ok === 'ASSEMBLY_COMPLETED' で型を絞り込み、results.resized にアクセスできました。作り物の ok 値を含むペイロードは、must be equal to one of the allowed values で拒否されました。
ライブ進行状況については、すべての Assembly Status に
update_stream_url が含まれます。その URL に対して
Accept: text/event-stream を付けた GET リクエストを送ると、Assembly の実行中に Server-Sent Events を受け取れます。assembly_upload_finished、assembly_result_finished、assembly_execution_progress、assembly_error、そして最後に assembly_finished メッセージが返ります。ストリームリファレンス では、各イベントを説明し、各イベントペイロード用の JSON Schema へリンクしています。
全ページを Markdown で提供し、エージェント向けに llms.txt も用意
AI コーディングエージェントは、HTML をスクレイピングするより、整った Markdown を読ませたほうがよりよい連携コードを書けます。現在、transloadit.com のすべての公開ページには Markdown 版があります。取得するには、末尾のスラッシュを .md に置き換えます。つまり、/docs/api/webhooks/ は /docs/api/webhooks.md になります。通常の URL に Accept: text/markdown を送る方法もあります。HTML レスポンスには
rel="alternate" を持つ Link ヘッダーで対応する
Markdown 版が示されるため、レスポンスヘッダーを読むツールなら見つけられます。
$ 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
…
検出用として、/llms.txt はコンパクトなインデックスです。開始ページ、各 Robot の Markdown ドキュメント、そして docs、API、Robot、SDK、FAQ 向けのスコープ別インデックスにリンクしています。さらに、動画、画像、音声、ドキュメント、アップロード、ストレージ、トラブルシューティングのトピック別インデックスにもリンクしています。また、仕様への参照先としても使えます。
$ 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.
引き続き /llms-full.txt も公開しています。単一ファイルで、およそ 1.5 MB です。ただし、通常は llms.txt から始め、必要なページだけ取得するほうが、エージェントはうまく動作します。このアプローチについては、AI ツール向けに API とドキュメントを使いやすくする方法で詳しく紹介しています。コードを書くのではなく、エージェント自身にファイルのアップロードと処理をさせたい場合は、Transloadit MCP Server またはエージェントスキル を使ってください。どちらを選ぶべきかは、AI エージェントガイド が役立ちます。
注意点
- 署名認証では、
paramsは署名済みの JSON 文字列です。TypeScript が検査するのはリクエストとレスポンスであり、paramsの中身までは検査しません。API 側では、リクエスト送信時にそこを検証します。 POST /assembliesはmultipart/form-dataを受け取ります。私たちは、プレーンなfetchでFormDataボディを送信し、レスポンスには生成された型を使うほうがシンプルだと感じました。- OpenAPI 3.1 では、ストリーム内の個々のイベントを型付けできません。そのため、ステータスストリームは
openapi.json内の通常のパスとしてではなく、リファレンスページとイベントスキーマで文書化しています。 - ブラウザーとモバイルでのアップロードでは、私たちの SDK が引き続き最短ルートです。同じ API の上に、再開可能なアップロード、リトライ、進行状況レポートを追加できます。
https://api2.transloadit.com/openapi.json をジェネレーターや API クライアントに取り込み、API リファレンス を参照し、無料アカウントを作成して自分の Auth
Key で試してみてください。ジェネレーターがドキュメント内の何かでつまずいたら、お知らせください。
