Node.js SDK
Node.js アプリから Transloadit REST API を簡単に呼び出せる、充実した機能を備えた Node.js 向けソフトウェア開発キットを提供しています。
インストール
現在の SDK は ESM 専用で、Node.js 20.10.0 以降をサポートしています。以下の Storage の例では SDK/CLI 6.9.0 以降を使用します。旧バージョンのドキュメントは v3 または v2 を参照してください。アップグレードの詳細は、移行ガイドを参照してください。
パッケージ名には @transloadit/node を使用してください。従来の npm パッケージ名 transloadit は、後方互換性のためにエイリアスとして維持されています。
プロジェクト内で、npm を使用して SDK をインストールしてください。
npm install @transloadit/node
プロジェクトですでに Yarn または pnpm を使用している場合は、既存のパッケージマネージャーとロックファイルをそのまま使用してください。
yarn add @transloadit/node
pnpm の場合は、pnpm add @transloadit/node を使用してください。
CLI
このパッケージには、充実した機能を備えた CLI が付属しています。
npx @transloadit/node --help
npx @transloadit/node auth login
ログインするとブラウザーが開き、Workspace を選択して CLI を承認できます。API シークレットをシェルにコピーする必要はありません。自動化やアプリケーションサーバーには、別途設定した Auth Key を使用してください。利用できるオプションは認証情報リファレンスを参照してください。CLI ログイン用の使い捨てキーをアプリケーション用のキーとしてデプロイしないでください。
npx @transloadit/node はインストール済みの SDK の CLI を使用します。パッケージがない場合は、取得するかどうかを確認します。例ではパッケージ名を明示しており、グローバルインストールは不要です。単体で動作する Storage のデモには、メンテナンスされている upload-once 初期化ツールを使用してください。
Intent コマンド
単発の処理をすばやく実行するための高水準の Intent コマンドも CLI に付属しています。よく使う Transloadit ワークフローを、用途がわかりやすいサブコマンドで実行できるため、タスクのたびに JSON の Assembly Instructions を作成する必要はありません。
ブラウザーログインの代わりに Auth Key をエクスポートする場合は、その Signature アルゴリズムに合わせてください。以下のキーを手動設定する CLI の例と JavaScript の例では、Smart CDN 署名が有効な Auth Key で受け付けられる SHA-256 を使って署名します。Smart CDN 署名が無効なキーでの SHA-384 など、Auth Key が別の Signature アルゴリズムを使う場合は、TRANSLOADIT_SIGNATURE_ALGORITHM と signatureAlgorithm の値をそのアルゴリズムに合わせてください。
使用例:
export TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY"
export TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET"
export TRANSLOADIT_SIGNATURE_ALGORITHM="sha256"
npx @transloadit/node markdown pdf --input ./README.md --print-urls
ほかにも次のような例があります。
npx @transloadit/node image remove-background --input ./photo.jpg --print-urlsnpx @transloadit/node image generate --prompt "A red bicycle in a studio" --output bicycle.pngnpx @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.pngnpx @transloadit/node image describe --input ./hero.jpg --for wordpress --output fields.json
image generate のデフォルトは、入力に基づく実行も含め、現在は google/nano-banana-2 です。
--output を省略すると、入力が単一のローカルファイルの場合、CLI は可能な限りそのファイルと同じディレクトリに書き込みます。それ以外の場合は、現在の作業ディレクトリに書き込みます。ローカルにダウンロードせずに一時的な結果 URL を取得するには、--print-urls を単独で使用してください。
公開している Transloadit skills リポジトリも更新し、同じ Intent ベースの画像生成フローを使用するようにしました。
コマンドリファレンス全体については、Intent コマンドリファレンスとパッケージの README を参照してください。
Storage と画像配信
upload-once の例で Storage と Smart CDN を試せます。既存のアプリでレスポンシブ画像を表示するには、Viewer for Next.js ガイドに従ってください。
CLI では画像だけでなく、さまざまなメディアのオリジナルファイルを保存できます。
npx @transloadit/node storage store ./photo.jpg ./clip.mp4 ./guide.pdf website/media/
この操作でディレクトリが公開されることはありません。アプリケーションサーバーからのアップロードには storeAsset() を使用し、返されたアセットとバージョンの受領情報を、その所有者と紐付けて保持してください。バイト単位の検証、明示的な上書き、カタログの復旧、オリジナルファイルのダウンロードについては、各種メディアのオリジナルファイルを参照してください。既存の HTTP/S3 ソースも、Storage に移行せずに Viewer で使用できます。
CommonJS プロジェクト
この SDK は ESM 専用です。CommonJS を使用している場合は、動的インポートを使用してください。
async function getClient() {
const { Transloadit } = await import('@transloadit/node')
return new Transloadit({
authKey: process.env.TRANSLOADIT_KEY,
authSecret: process.env.TRANSLOADIT_SECRET,
// Match another Signature algorithm if your Auth Key requires one.
signatureAlgorithm: 'sha256',
})
}
使い方
次のコードは、画像をアップロードし、サムネイルサイズにリサイズします。
import { ApiError, Transloadit } from '@transloadit/node'
const transloadit = new Transloadit({
authKey: 'YOUR_TRANSLOADIT_KEY',
authSecret: process.env.TRANSLOADIT_SECRET,
// Match another Signature algorithm if your Auth Key requires one.
signatureAlgorithm: 'sha256',
})
try {
const options = {
files: {
file1: '/PATH/TO/FILE.jpg',
},
params: {
steps: {
// You can have many Steps. In this case we will just resize any inputs (:original)
resize: {
use: ':original',
robot: '/image/resize',
result: true,
width: 75,
height: 75,
},
},
// OR if you already created a template, you can use it instead of "steps":
// template_id: 'YOUR_TEMPLATE_ID',
},
waitForCompletion: true, // Wait for the Assembly (job) to finish executing before returning
}
const status = await transloadit.createAssembly(options)
if (status.results.resize) {
console.log('✅ Success - Your resized image:', status.results.resize[0].ssl_url)
} else {
console.log("❌ The Assembly didn't produce any output. Make sure you used a valid image file")
process.exitCode = 1
}
} catch (err) {
console.error('❌ Unable to process Assembly:', err instanceof ApiError ? (err.code ?? 'API request failed.') : 'Check your connection and input files.')
process.exitCode = 1
if (err instanceof ApiError && err.assemblyId) {
console.error(`💡 More info: https://api2.transloadit.com/assemblies/${err.assemblyId}`)
}
}
実行済みの Assembly の詳細はこちらで確認できます。
使用例
- 画像のアップロードとリサイズ
- 画像のアップロードと WebP への変換
- SVG から PNG へのラスタライズ
- 画像から顔を切り抜いて結果をダウンロード
- リトライの例
- 合計コストの計算(GB 使用量)
- Template の CRUD
- Template の認証情報の CRUD
そのまま動作するサンプルをさらに確認するには、examples/ を参照してください。