バケットを設定せずにアップロードと処理結果を保存
処理済みファイルを保存するには、多くの場合、ストレージを別途設定する必要があります。S3 バケットを作成し、IAM ポリシーを記述し、Templateに認証情報を追加します。本来解決したい課題に取りかかる前に、こうした作業が発生します。
Transloadit Storage は、利用を許可された Workspace に別の選択肢を提供します。/transloadit/store Robotで Workspace のストレージにファイルを保存し、署名付き Smart CDN URL でオリジナルやオンデマンドで生成した派生ファイルを配信します。Workspace でファイルライブラリーが有効になっていれば、Console のファイルライブラリーと
S3 互換エンドポイントで、それらのファイルを管理できます。
Transloadit Storage はプライベートプレビュー中です。一般提供前の試用をご希望の場合は、Workspace のアクセスについてお問い合わせください。このチュートリアルには、当社チームが別途有効にするファイルライブラリーへのアクセスも必要です。Storage を有効にするだけでは、このアクセス権は付与されません。
このチュートリアルでは、Node.js と公式 SDK を使い、ディスク上のファイルを Transloadit Storage に保存して Smart CDN 経由で取り出すまでを、4 つの短い手順で説明します。バケットを作成する必要は一切ありません。
必要なもの
- Node.js 22 以降
- Storage プレビューの利用が許可され、ファイルライブラリーへのアクセスが有効な Workspace
- Consoleの「認証情報」にある 2 つの Auth Key。以下の例で使う
assemblies:write、dam:read、templates:read、templates:writeを持つ API キーと、それとは別の Smart CDN 署名用キーが必要です。後者を作成するには「新しい Auth Key」と「非公開画像の配信(Smart CDN の署名)」を選択します。これにより Smart CDN が有効になり、smart_cdn:signのみが選択されます。S3 経由で直接アップロードする場合はdam:writeも必要です。 - 手順 2 の任意の S3 コマンドを実行するための AWS CLI
- Workspace のスラッグ。Console URL の
/c/より後の部分で、たとえばmytransloadit-toystory-appです。
assemblies:write で認可されたAssemblyは、Storage Robot 経由でファイルを保存、インポートできます。dam:read と dam:write のスコープが制御するのは S3 への直接アクセスであり、これらの Assembly 操作ではありません。
キーで Smart CDN を有効にしても、ほかの機能は制限されません。制限するのはキーの権限です。smart_cdn:sign のみを持つキーでは、単独の Assembly の作成や Storage の管理はできません。ただし、その Auth Secret を持つ人は誰でも、アカウント上で変換を実行し、保存済みファイルを配信する URL に署名できます。ほかの Auth Secret と同様に、サーバー上で保管してください。漏えいした場合は、キーを削除して新しいキーを作成してください。
プロジェクトと .env ファイルを作成します。
mkdir zero-config-storage && cd zero-config-storage
npm init -y && npm pkg set type=module
npm install @transloadit/node @transloadit/utils
curl --fail --location --output photo.jpg https://demos.transloadit.com/inputs/chameleon.jpg
TRANSLOADIT_KEY=your-api-auth-key
TRANSLOADIT_SECRET=your-api-auth-secret
TRANSLOADIT_CDN_KEY=your-smart-cdn-auth-key
TRANSLOADIT_CDN_SECRET=your-smart-cdn-auth-secret
TRANSLOADIT_WORKSPACE=your-workspace-slug
Node は --env-file でこのファイルを読み込むため、dotenv への依存はありません。手順 2 のシェルコマンドでは、set -a; . ./.env; set +a で読み込み、同じターミナルを使用してください。プレビュー中に、当社からエンドポイントの上書き設定(TRANSLOADIT_ENDPOINT、TRANSLOADIT_STORAGE_S3_ENDPOINT、TRANSLOADIT_SMART_CDN_BASE_URL、TRANSLOADIT_SMART_CDN_EXTRA_PARAMS)をお渡ししている場合もあります。以下のスクリプトは、設定があればそれを使い、なければ本番環境のデフォルト値を使用します。シェルコマンドでも安全に読み込めるよう、.env 内では、スペースや & などのシェル文字を含む値を引用符で囲んでください。
手順 1:/transloadit/store でファイルを保存
/transloadit/store は /s3/store と同様に保存用のRobotですが、認証情報もバケットも不要です。Workspace のストレージに書き込みます。path がファイルの保存先です。フォルダーは必要に応じて作成され、${file.name} はファイルごとに置換されます。
import { Transloadit } from '@transloadit/node'
const client = new Transloadit({
authKey: process.env.TRANSLOADIT_KEY,
authSecret: process.env.TRANSLOADIT_SECRET,
endpoint: process.env.TRANSLOADIT_ENDPOINT,
})
const assembly = await client.createAssembly({
files: { photo: './photo.jpg' },
params: {
steps: {
stored: {
robot: '/transloadit/store',
use: ':original',
path: 'uploads/${file.name}',
// Uploading the same name again creates a new version instead of failing.
conflict_strategy: 'overwrite',
},
},
},
waitForCompletion: true,
})
// Storing Robots do not add a result key of their own: they annotate the file they stored,
// which is still listed under the step that produced it — here the upload, `:original`.
const [stored] = assembly.results[':original']
console.log(`Stored ${stored.path} (${stored.size} bytes, asset ${stored.asset_id})`)
node --env-file=.env store.js
# Stored uploads/photo.jpg (9309370 bytes, asset 8kLg…)
このチュートリアルで「ストレージの設定」にあたる作業は、これだけです。ファイルは Workspace 内の uploads/photo.jpg に保存されました。同じパスに再度保存すると、新しいバージョン(conflict_strategy: 'overwrite')が作成されます。以前のバージョンは、保持されている間は取得できます。バージョニングは永続的な保持を約束するものではなく、バックアップポリシーの代わりにもなりません。
手順 2:Console または使い慣れた S3 ツールで確認
Workspace のファイルライブラリーは、当社チームが有効にする必要があります。有効になると、Workspace のオーナー、管理者、通常のメンバーが開けますが、請求管理者は開けません。Storage を有効にするだけでは、このページやその S3 エンドポイントは利用できません。
アクセスが有効になったら、Consoleを開き、Workspace を選択して、「ファイルライブラリー」(https://transloadit.com/c/<workspace-slug>/file-library/)に移動します。uploads フォルダー内に photo.jpg があります。ここで保存済みファイルを閲覧、管理できます。

ターミナルを使いたい場合も対応できます。Transloadit Storage は S3 互換で、Auth Key と Secret が認証情報になります。Workspace のスラッグがバケットに相当します。
set -a; . ./.env; set +a
export AWS_ACCESS_KEY_ID="$TRANSLOADIT_KEY" AWS_SECRET_ACCESS_KEY="$TRANSLOADIT_SECRET"
export AWS_DEFAULT_REGION=us-east-1
aws --endpoint-url "${TRANSLOADIT_STORAGE_S3_ENDPOINT:-https://api2.transloadit.com/storage}" \
s3 ls "s3://$TRANSLOADIT_WORKSPACE/uploads/"
# 2026-08-31 10:12:04 9309370 photo.jpg
以下の例では、S3 の一覧取得とバージョンを指定したダウンロードを使用します。AWS S3 の全機能が使えるとは想定せず、クライアントに必要な操作と権限を確認してください。store.js を 2 回実行すると、S3 API で両方のバージョンを一覧表示できます。
aws --endpoint-url "${TRANSLOADIT_STORAGE_S3_ENDPOINT:-https://api2.transloadit.com/storage}" \
s3api list-object-versions --bucket "$TRANSLOADIT_WORKSPACE" --prefix uploads/photo.jpg \
--query 'Versions[?Key==`uploads/photo.jpg`].[VersionId,IsLatest,LastModified]' --output text
# 9G2… True 2026-08-31T10:12:04+00:00
# 7Kq… False 2026-08-31T10:05:41+00:00
同じパスに 2 回アップロードした後、バージョン ID を指定して以前のバージョンを取得します。キーの完全一致フィルターにより、名前が uploads/photo.jpg で始まる別のファイルを選択せずに済みます。
if PREVIOUS=$(aws --endpoint-url "${TRANSLOADIT_STORAGE_S3_ENDPOINT:-https://api2.transloadit.com/storage}" \
s3api list-object-versions --bucket "$TRANSLOADIT_WORKSPACE" --prefix uploads/photo.jpg \
--query 'Versions[?Key==`uploads/photo.jpg` && IsLatest==`false`] | [0].VersionId' --output text); then
if [ -n "$PREVIOUS" ] && [ "$PREVIOUS" != None ]; then
aws --endpoint-url "${TRANSLOADIT_STORAGE_S3_ENDPOINT:-https://api2.transloadit.com/storage}" \
s3api get-object --bucket "$TRANSLOADIT_WORKSPACE" --key uploads/photo.jpg \
--version-id "$PREVIOUS" photo-previous.jpg
else
printf '%s\n' 'No previous version exists. Upload the same path again first.'
fi
else
printf '%s\n' 'Could not list object versions; no download was attempted.' >&2
fi
手順 3:Smart CDN 経由で配信
このチュートリアルの uploads/ ディレクトリーは非公開のままにしてください。ブラウザーにファイルを渡すには、組み込みの builtin/storage-serve@0.0.1 Template用に
Smart CDN URL に署名します。この Template はストレージからファイルを読み込み、配信します。署名には有効期限があり、Transloadit がその署名を受け付ける期間を制限します。有効期限が切れても、受信者がすでにダウンロードまたはキャッシュしたバイト列は回収できません。
import { getSignedSmartCdnUrl } from '@transloadit/utils/node'
const url = getSignedSmartCdnUrl({
workspace: process.env.TRANSLOADIT_WORKSPACE,
template: 'builtin/storage-serve@0.0.1',
input: 'uploads/photo.jpg',
authKey: process.env.TRANSLOADIT_CDN_KEY,
authSecret: process.env.TRANSLOADIT_CDN_SECRET,
expiresAt: Date.now() + 60 * 60 * 1000, // valid for one hour
// Preview environments only; omit in production.
baseUrl: process.env.TRANSLOADIT_SMART_CDN_BASE_URL,
urlParams: Object.fromEntries(
new URLSearchParams(process.env.TRANSLOADIT_SMART_CDN_EXTRA_PARAMS ?? ''),
),
})
console.log(url)
curl --fail --silent --show-error --output photo-served.jpg "$(node --env-file=.env serve.js)"
URL は次のようになります。https://your-workspace-slug.tlcdn.com/builtin%2Fstorage-serve%400.0.1/uploads%2Fphoto.jpg?auth_key=…&exp=…&sig=sha256%3A…。この URL を持つ人は誰でも、その認可を利用できます。認証情報と同様に扱い、ログに記録せず、curl にパイプで渡すか、ブラウザーに渡してください。同じ URL でも、auth_key、exp、sig のパラメーターがなければ、Workspace の Signature Authentication 設定にかかわらず、この非公開ディレクトリーへのアクセスは拒否されます。Storage は、明示的に公開したプレフィックスと、公開配信用の別の組み込み Template にも対応しています。このチュートリアルではプレフィックスを公開しません。URL への署名を省くためだけに、非公開ファイルを公開しないでください。
この方法では、スマートフォンにもオリジナルの 9.3 MB すべてを配信します。手順 4 では、代わりにリサイズ版を配信する方法を説明します。実際のページでは、サムネイルより大きい画像にはリサイズ版を使用します。
手順 4(任意):派生ファイルのオンデマンド生成
builtin/storage-serve はオリジナルを配信します。サムネイル、透かし、形式変換には、/transloadit/import、処理用のRobot、/file/serve を使って、独自のTemplateを作成します。この例では /image/resize を使い、URL で渡された幅にリサイズします。
import { Transloadit } from '@transloadit/node'
const client = new Transloadit({
authKey: process.env.TRANSLOADIT_KEY,
authSecret: process.env.TRANSLOADIT_SECRET,
endpoint: process.env.TRANSLOADIT_ENDPOINT,
})
const name = 'storage-thumb'
const template = {
steps: {
imported: { robot: '/transloadit/import', path: '${fields.input}' },
resized: { robot: '/image/resize', use: 'imported', width: '${fields.w}', imagemagick_stack: 'v3.0.0' },
served: { robot: '/file/serve', use: 'resized' },
},
}
// Search every page so rerunning the script also works in Workspaces with many Templates.
let existing
for await (const item of client.streamTemplates()) {
if (item.name === name) {
existing = item
break
}
}
if (existing) {
await client.editTemplate(existing.id, { name, template })
console.log(`Template ${name} updated`)
} else {
await client.createTemplate({ name, template })
console.log(`Template ${name} created`)
}
URL への署名には同じ呼び出しを使い、独自のTemplate名と、URL パラメーターとして幅を指定します。
import { getSignedSmartCdnUrl } from '@transloadit/utils/node'
const url = getSignedSmartCdnUrl({
workspace: process.env.TRANSLOADIT_WORKSPACE,
template: 'storage-thumb',
input: 'uploads/photo.jpg',
authKey: process.env.TRANSLOADIT_CDN_KEY,
authSecret: process.env.TRANSLOADIT_CDN_SECRET,
expiresAt: Date.now() + 60 * 60 * 1000,
baseUrl: process.env.TRANSLOADIT_SMART_CDN_BASE_URL, // preview environments only
urlParams: {
w: 300,
...Object.fromEntries(new URLSearchParams(process.env.TRANSLOADIT_SMART_CDN_EXTRA_PARAMS ?? '')),
},
})
console.log(url)
node --env-file=.env create-template.js && \
curl --fail --silent --show-error --output photo-thumb.jpg "$(node --env-file=.env serve-thumb.js)"
# Template storage-thumb created
Smart CDN は、uploads/photo.jpg の幅 300 ピクセル版を返します。

独自のTemplateの /transloadit/import Stepも、認証済みアクセスを必要とします。Workspace の Signature Authentication を無効にしても、この非公開インポートが公開されることはありません。ほかの Template では、署名なしの利用を許可する前に認証ドキュメントを確認してください。
リファレンス:2 つの Robot
/transloadit/storeは任意のpathを受け付け、デフォルトは${file.url_name}です。overwriteまたはrenameを選択しない限り、保存先が既存の場合は失敗します。出力元のStepの結果から、返されたworkspace、asset_id、version_id、最終的なpathを保存してください。すべてのオプションはストレージ Robot リファレンスを参照してください。/transloadit/importは、ファイルまたはフォルダーのpath、あるいはasset_idを受け付けます。任意のversion_idで保持されているバイト列を選択できます。フォルダーのインポートでは、recursive: trueを設定しない限り、直下の子要素のみが含まれます。出力は、別のRobotがuseできる通常のファイルです。認証とセレクターについては、インポート Robot リファレンスを参照してください。
ここまでのまとめ
/transloadit/storeという 1 つのRobotで、Workspace のストレージにファイルを保存しました。バケットも IAM も不要で、Templateに認証情報を設定する必要もありません。- 有効化された Console のファイルライブラリーと、サポート対象の S3 操作で、同じ保存済みファイルにアクセスできます。
- 署名付き Smart CDN URL でオリジナルを配信し、独自の小さなTemplateで派生ファイルを配信します。
次のステップ
- ブラウザー向けのアップロード UI には、Uppyをご覧ください。Auth Secret とこの記事の署名処理の例は、ブラウザーのコードではなくサーバー上に置いてください。
- キャンペーン全体の新しいサムネイルを作るなど、コレクションを再処理する場合は、
/transloadit/importにフォルダーパスとrecursive: trueを指定して、サブフォルダーも含めてください。
