Transloadit CLI でゼロから始めるファイル処理
API シークレットをコピーせずに、ターミナルからファイルを処理できます。auth login を実行し、ブラウザーでリクエストを承認すると(アカウントがなければ先に登録します)、次のコマンドでファイルを処理できます。
同じ CLI で、文章から Assembly Instructions を生成し、手書きの処理設定を lint で検証・修正して、フォルダー全体に適用できます。以下では、本番 API を使ってそれぞれの手順を紹介します。途中で途切れたアップロードに対処する Node SDK の機能も取り上げます。
ブラウザーからのログイン
以下の例では @transloadit/node 5.1.0 を使用します。CLI コマンドは npx 経由で実行するため、Node.js 20.10 以降があれば始められます。
$ npx -y @transloadit/node auth login
Enter code VKVQ-C5H6 at https://transloadit.com/c/cli-auth?code=VKVQ-C5H6
CLI がページを開きます。--no-browser を指定すると、リンクの表示のみになるため、SSH 接続時に便利です。ログインするか、アカウントがなければ登録し、ページ上のコードがターミナルのコードと一致することを確認して承認します。CLI に Logged in to workspace … と表示されれば準備完了です。コードの有効期限は 15 分です。
承認すると、Auth Key が
Workspace に新規作成されます。マシンのホスト名と日付のラベルが付くので、後から Console の認証情報で見つけられます。CLI はこれを ~/.transloadit/credentials に保存します。このファイルは自分のユーザーだけが読み取れます。このキーで
Assembly の作成、Template の読み取り、Smart CDN URL の署名ができます。auth status でログイン先の Workspace を確認でき、auth logout でファイルを削除してキーを失効させます。既存のキーがある場合は、代わりに auth login --stdin で
dotenv 形式の入力からインポートできます。
ノート PC でのログインは自動化向けではありません。
- CI では、引き続きシークレットマネージャーから
TRANSLOADIT_KEYとTRANSLOADIT_SECRETを渡し、そのジョブにスコープを限定したキーを使用してください。環境変数は保存済みのログイン情報より優先されます。 - アプリケーションサーバーでは別のデプロイ用キーを使用してください。ノート PC でログアウトしても、本番環境に影響しなくなります。
文章からファイル処理まで
curl -fsSLo chameleon.jpg https://demos.transloadit.com/inputs/chameleon.jpg
npx -y @transloadit/node run "resize to 400px wide and convert to WebP" -i chameleon.jpg -o chameleon.webp
$ file chameleon.webp
chameleon.webp: RIFF (little-endian) data, WebP image, XMP metadata, EXIF metadata, ICC profile, 400x266
run は文章を Assembly Instructions にコンパイルし、後述のチェックで結果を lint 検証します。エラーが見つかると最大 3 回試行し、その後、処理設定をファイルに適用します。私たちが試した 9.3 MB の JPEG は、コンパイルを含めて約 20 秒で 62 KB の WebP になりました。
コンパイル自体も 🤖 /ai/chat Robot を使う Assembly なので、ほかの Assembly と同様に使用量に計上されます。同じ処理を再び使う場合は、一度コンパイルして出力を保存します。
npx -y @transloadit/node assembly-instructions compile "resize to 400px wide and convert to WebP" > webp-thumbs.json
生成される処理設定の例です。
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"webp": {
"robot": "/image/resize",
"use": ":original",
"width": 400,
"resize_strategy": "fit",
"zoom": true,
"format": "webp",
"background": "none",
"result": true
}
}
}
これは 🤖 /image/resize
Robot を使う単一の
Step です。モデルを再度呼び出さずに、処理設定をレビューし、コミットして再利用できます。同じ文章でもモデルが異なる処理設定を返すことがあるので、保存する内容は確認してください。固定のフラグで済み、AI が不要な一般的な処理には、image resize などの Intent コマンド のほうが手早く使えます。
再利用するには、保存したファイルをそのまま assemblies create に渡します。
npx -y @transloadit/node assemblies create --steps webp-thumbs.json -i chameleon.jpg -o saved-thumb.webp
本番投入前のミス検出
assemblies lint は、Console エディターや MCP サーバーと共通のリンターを使い、ローカルマシンで処理設定を検証します。認証情報が不要なので、シークレットなしで CI や pre-commit フックから実行できます。次のファイルには、use がない Step、キーの重複、Step 名のタイプミスという 3 つのよくあるミスがあります。
{
"steps": {
":original": { "robot": "/upload/handle" },
"thumb": {
"robot": "/image/resize",
"width": 400,
"height": 300,
"width": 800
},
"optimized": { "robot": "/image/optimize", "use": "thumbs" },
"exported": {
"robot": "/s3/store",
"use": [":original", "thumb", "optimized"],
"credentials": "my-s3-credentials"
}
}
}
$ npx -y @transloadit/node assemblies lint --steps steps.json
[warning] missing-use (3:13) thumb The `use` parameter defines which files a _Robot_ should process. …
[warning] duplicate-key-in-step (7:6) thumb Duplicate key 'width' found
[error] undefined-step (9:54) optimized The _Step_ `optimized` attempts to use the output files from _Step_ `thumbs`, but _Step_ `thumbs` does not exist …
--fix を付けると、リンターが安全に修正できる箇所を修正し、ファイルを直接書き換えます。
$ npx -y @transloadit/node assemblies lint --steps steps.json --fix
[error] undefined-step (13:13) optimized The _Step_ `optimized` attempts to use the output files from _Step_ `thumbs`, but _Step_ `thumbs` does not exist …
thumb Step は次のようになります。
{
"steps": {
// …
"thumb": {
"robot": "/image/resize",
"width": 800,
"height": 300,
"use": ":original"
},
// …
},
}
--fix は、JSON パーサーが保持する最後の
width を残し、Step の参照先を
:original に設定して、ファイルを整形しました。意図した Step をリンターが判断することはできないため、タイプミスは残ります。thumbs を thumb に変更すると、警告を失敗として扱っても検証に通ります。
$ npx -y @transloadit/node assemblies lint --steps steps.json --fatal warning
No issues found
lint はエラー時にゼロ以外のコードで終了します。--fatal warning を指定すると警告時も同様なので、CI ジョブで同じコマンドを実行すれば、不正な処理設定のリリースを防げます。--steps - は標準入力から読み取り、--json は機械可読形式で問題を出力します。--template は、API と同じ方法で Step と保存済みの Template をマージして lint 検証します。この最後のオプションには認証情報が必要です。
フォルダー全体の処理
assemblies create は、ファイルやディレクトリに処理設定を適用し、結果をダウンロードします。--steps は、以下の Step のみのファイルと、先ほどの { "steps": … } 形式の両方を受け付けます。photos/ に JPEG をいくつか置くと、次の例で幅 400 ピクセルのサムネイルを作成できます。
{
":original": { "robot": "/upload/handle" },
"thumb": { "robot": "/image/resize", "use": ":original", "width": 400 }
}
mkdir -p thumbs
npx -y @transloadit/node assemblies create --steps thumbs.json --input photos/ --output thumbs/
写真ごとに個別の Assembly が作成され、デフォルトでは 5 つずつ同時に処理します(--concurrency で変更できます)。各結果は、写真のファイル名で thumbs/ に保存されます。コマンドを再実行すると、サムネイルが元の写真より新しいものはすべてスキップするため、Assembly の使用量が発生するのは新規または変更されたファイルだけです。--reprocess-stale はすべてを再処理します。サブフォルダーも対象にするには --recursive を、コマンドを実行したままファイルの変更に応じて処理するには
--watch を付けます。
クラッシュ後のアップロード再開
独自の Node.js スクリプトから大容量ファイルをアップロードする場合、SDK の resumeAssemblyUploads() を使うと、中断したアップロードを最初からやり直さずに再開できます。プロジェクトに @transloadit/node@5.1.0 をインストールし、SDK のデフォルトである SHA-384 用に設定したアプリケーションの Auth Key に合わせて
TRANSLOADIT_KEY と TRANSLOADIT_SECRET を設定してください。これらのスクリプトは環境変数から認証情報を読み取ります。サンプル写真をダウンロードします。
curl -fsSLo prinsengracht.jpg https://demos.transloadit.com/inputs/prinsengracht.jpg
アップロードが始まったらすぐに Assembly URL を保存します。
import { writeFile } from 'node:fs/promises'
import { Transloadit } from '@transloadit/node'
const client = new Transloadit({
authKey: process.env.TRANSLOADIT_KEY,
authSecret: process.env.TRANSLOADIT_SECRET,
})
const upload = client.createAssembly({
params: { steps: { thumb: { robot: '/image/resize', use: ':original', width: 400 } } },
files: { photo: './prinsengracht.jpg' },
chunkSize: 1024 * 1024,
})
// The Assembly ID exists before the first byte is sent, so save it right away.
await writeFile('assembly.txt', `https://api2.transloadit.com/assemblies/${upload.assemblyId}`)
await upload
そのプロセスが終了してしまった場合は、別のスクリプトで未送信のバイトを同じ Assembly に送信します。
import { readFile } from 'node:fs/promises'
import { Transloadit } from '@transloadit/node'
const client = new Transloadit({
authKey: process.env.TRANSLOADIT_KEY,
authSecret: process.env.TRANSLOADIT_SECRET,
})
const status = await client.resumeAssemblyUploads({
assemblyUrl: await readFile('assembly.txt', 'utf8'),
files: { photo: './prinsengracht.jpg' },
chunkSize: 1024 * 1024,
waitForCompletion: true,
onUploadProgress: ({ uploadedBytes }) => console.log(`${uploadedBytes} bytes uploaded`),
})
console.log(status.ok)
私たちは、Ctrl+C が送るシグナルで 14 MB の写真のアップロードを中断し、Assembly のステータスで部分アップロードを確認してから再開しました。
$ node upload.mjs
^C
$ node resume.mjs
1048576 bytes uploaded
1114112 bytes uploaded
…
14160569 bytes uploaded
ASSEMBLY_COMPLETED
アップロードはゼロからではなく、1,048,576 バイトの位置から続行されました。SDK はフィールド名、ファイル名、サイズでアップロードを照合するため、前回と同じパスを渡してください。再開できるのはファイルパスによる入力のみで、ストリームやバッファーは対象外です。API は部分アップロードのステータスを非同期で更新します。Assembly のステータスに部分アップロードが表示される前に再開すると、SDK は同じ Assembly にそのファイルを最初からアップロードし直します。
制限事項
- ブラウザーログインで作成したキーは Assembly の実行と Template の読み取りに使えますが、Template の作成や変更はできません。書き込みを行う
templatesコマンドには、その権限を持つ別のキーが必要です。 runとcompileは AI モデルを使うため、同じ文章を 2 回処理しても、異なる処理設定が生成されることがあります。- 無料の Community プランでは、画像の結果にはウォーターマークが入り、音声と動画の結果は短く切り詰められます。理由は FAQ で説明しています。
実際に試す
npx -y @transloadit/node auth login
アカウントがまだない場合は、開いたページで登録するか、先にアカウントを作成してください。CLI の概要ではツールを紹介し、SDK READMEではコマンドとアップロード再開 API を説明しています。エージェントから Transloadit を操作したい場合は、MCP サーバーとエージェントスキルをご覧ください。不足している機能があれば、node-sdk の課題トラッカーでお知らせください。
