Node SDK Intents:一般的なタスク向け CLI コマンド
Node SDK で、一般的な Transloadit のタスク向けに高水準の CLI コマンドである Intent コマンドを利用できるようになりました。これらのコマンドを使うと、都度の処理のために Assembly Instructions JSON を手書きしなくても、Transloadit をずっと手軽に使えます。
以下の例では、現在の @transloadit/node パッケージ名を使用しています。CLI バイナリー名は引き続き transloadit です。古い transloadit npm パッケージも、互換性のためのエイリアスとして引き続き利用できます。インストールと認証については、Node SDK ドキュメントを参照してください。
Node SDK にコマンドラインの利便性を加えようと考えたきっかけは、私たち自身が直面した実際の問題でした。長く使う統合を構築する場合、JSON の処理設定や再利用可能な Templateは、まさに適した高水準の仕組みです。表現力があり、安定していて、カスタムの複数 Step からなるワークフローにも向いています。一方で、ちょっとしたコマンドライン処理には、どうしても準備の負担に感じられます。
共同創業者として日々仕事をする中で、Markdown ファイルをすばやく PDF に変換したい場面でも、そのために非常に優れたサービスがあるにもかかわらず、Transloadit を使っていないことに気づきました。
そこで、自分が実際に使いたくなるには、統合がどのようなことをできるべきかを考え始めました。使いたいコマンドを書き出し、そこから実装へと逆算していきました。それが Intents です。
Intents は、Node SDKの CLI にある追加の高水準レイヤーで、Robot、Assembly、Builtin Templateといった基本要素の上に成り立っています。
これまでの CLI では、こうした基本要素にそのままアクセスしていました。新しい Intents レイヤーは、内部実装ではなく都度のユースケースを軸に構成されており、markdown pdf、markdown docx、image remove-background、image generate、image describe のように、推測しやすいコマンドを用意しています。
CLI から都度の処理を実行
TRANSLOADIT_KEY と TRANSLOADIT_SECRET の認証情報をシェル、ローカルの .env、または ~/.transloadit/credentials で利用できる場合は、次のように実行できます。
npx -y @transloadit/node markdown pdf --input ./README.md --print-urls
すると、最後の列に実際の一時結果 URL が入った、次のような表が表示されます。
STEP NAME URL
convert README.pdf https://example.com/README.pdf
つまり、Transloadit を埋め込み型のバックエンド統合としてだけでなく、ちょっとした処理に使える実用的な CLI ツールとしても活用できます。
一般的なタスクでは JSON の代わりに高水準コマンドを使用
Intents は、一般的なワークフローを短く予測しやすいコマンド名で提供します。いくつか例を挙げます。
npx -y @transloadit/node image remove-background --input ./photo.jpg --print-urls
npx -y @transloadit/node image generate --prompt "A red bicycle in a studio" --output bicycle.png
npx -y @transloadit/node image describe --input ./hero.jpg --for wordpress --output fields.json
npx -y @transloadit/node markdown docx --input ./plan.md --output plan.docx
入力に基づく画像生成も可能です。
npx -y @transloadit/node image generate \
--input ./person1.jpg \
--input ./person2.jpg \
--input ./background.jpg \
--prompt "Place person1.jpg feeding person2.jpg in front of background.jpg" \
--output scene.png
完全なリファレンスについては、GitHub の Intent Commands リファレンスまたは Node SDK ドキュメントを参照してください。
最重要の設計原則は利便性
Intents では、役立つデフォルト値を選ぶことを重視しています。今回の更新時点では、image generate のデフォルトは google/nano-banana-2 です。サポートされている別の選択肢を明示する場合は、--model を使用してください。この記事を恒久的なモデルカタログとして扱うのではなく、npx -y @transloadit/node image generate --help を実行して、インストール済みコマンドのオプションを確認してください。
モデルのデフォルトは、リリースごとに変わる可能性があります。再現性が必要な統合では、プロジェクトの依存関係で SDK のバージョンを固定し、モデルを意図的に選択したうえで、ユースケースに対して出力を検証してください。
出力先を予測しやすくしたい場合は、--output を指定してください。省略すると、CLI はコマンドと入力からパスを推定します。詳細は Intent Commands リファレンスに記載しています。ファイルをローカルにダウンロードせず、一時結果 URL だけが必要な場合は、--print-urls のみを使用してください。
読みやすさを優先して、この投稿では長い形式の --output を使っていますが、もちろん -o のような短いエイリアスもあります。
ちょっとした処理には Intents、カスタムワークフローには JSON を使用
Intents は、Transloadit の低水準モデルを置き換えるものではありません。JSON の処理設定は、統合されたメディアパイプラインのための長期的な高水準の仕組みとして、引き続き適しています。ユースケースに合わせたフローを構築でき、Templateとして保存して、本番環境で SDKを通じて何度でも再利用することを想定しています。
ただし、コマンドラインで素早くメディアを処理したい場合には、(あるいはその役割をエージェントが担う場合にも)これはちょうどよい選択肢かもしれません。
また、CLI で必要なことが Intents では足りなくなっても、CLI は引き続き
npx -y @transloadit/node assemblies create をサポートしています。そのため、必要になった時点でいつでも独自のメディアパイプライン構築へ移行できます。
試してみる
対話的に使う場合は、npx -y @transloadit/node auth login から始めて、Node SDK のセットアップに従ってください。自動化する場合は、SDK のデプロイガイダンスに従い、適切なスコープを持つ別の
Auth Key と Auth Secret を用意し、シークレットマネージャー経由で
TRANSLOADIT_KEY と TRANSLOADIT_SECRET として渡してください。これらの API 認証情報は Transloadit へのリクエストを認証するものであり、ストレージプロバイダーへのアクセスに使う Template の認証情報ではありません。Auth Secret はブラウザーコードやソース管理に含めないでください。そのうえで、利用可能なコマンドを確認します。
npx -y @transloadit/node --help
必要に応じて、エージェント(Cursor、Codex、Claude Code など)がこれらの Intents を見つけて、メディア処理の能力を使えるようにしたい場合は、次のコマンドで私たちの Skills をグローバルにインストールできます。
npx -y skills add https://github.com/transloadit/skills -g --all --copy
これによって、メディアファイルの作成と管理がずっと簡単になることを願っています。機能が足りない場合や、さらに便利にできそうな点があれば、GitHub の issue tracker でお知らせください。
