一度アップロードして、いつでも変換
多くの画像パイプラインでは、アップロード時に必要な出力を見込んで、サムネイル、中サイズ、大サイズ、WebP 版を生成し、元画像とともに保存します。デザインに正方形のカードが追加されたり、AVIF が必要になったりすると、ライブラリ全体に対して再びバッチ処理を実行することになります。
Transloadit Storage と Smart CDN では、元画像を保存し、派生画像の指定を URL に含めます。最初のリクエストで画像を生成し、以降のリクエストではキャッシュ済みの結果を利用できます。新しいサイズや切り抜きのために、再アップロードやライブラリ全体の移行は不要です。
写真を 1 つ保存し、WebP のカード、正方形の AVIF 画像、横長に切り抜いた JPEG として表示してみましょう。カスタム Template、AWS CLI、フロントエンドフレームワークは不要です。
Transloadit Storage はプライベートプレビュー中です。Workspace での有効化はお問い合わせください。このサンプルには Node.js 24.15+ または 26+ も必要です。
試す
npx @transloadit/node@latest init upload-once my-gallery
cd my-gallery
npm run demo
初期化ツールは、互換性のある依存関係、サンプル写真、小さな
demo.ts を含む新しいディレクトリを作成します。ファイルのアップロードや既存プロジェクトの変更は行いません。デモは必要に応じてブラウザーのログイン画面を開き、Storage へのアクセスを確認して写真をアップロードします。gallery.html を開くと、3 つの派生画像を確認できます。
承認ページで目的の Workspace を選択してください。別のアカウントを使う場合は、プライベートブラウザーウィンドウでログインリンクを開くと、現在の Console セッションを維持できます。

pad によって画像全体を収めるための余白です。fillcrop は横長の枠を埋めるように切り抜きます。完全なサンプルと README は SDK のリリースに含まれています。生成されるプロジェクトはそのバージョンに固定され、ソースを編集できます。
元画像をそのままに、出力を変更
demo.ts の先頭にある variants で、各出力の幅、高さ、形式、リサイズ方法を定義しています。幅や切り抜きを変更し、npm run demo を再実行してください。CLI は、対応する元画像の保存済みレシートを再利用して再アップロードを省略し、派生画像の新しい URL を生成します。写真をアップロードしたか、再利用したかはターミナルに表示されます。
自分の写真で試すには、次を実行してください。
npm run demo -- ./your-photo.jpg
storage store --hashed はコンテンツアドレス方式のファイル名を使用し、アセットとバージョンのレシートを transloadit.images.json に保存します。このカタログは保持してください。CLI が重複アップロードを省略するために使います。アップロードが正常に完了しなかった場合の上書きや復旧の動作は、README に記載されています。
auth smart-cdn は、公開済みの builtin/storage-preview@0.0.3
パイプライン用の URL に署名します。この URL では、w と
h が出力枠を設定し、f が形式を選択し、q が画質を設定します。pad は画像全体を枠内に収め、fillcrop は切り抜いて枠を埋めます。このサンプルでは幅と高さの両方を指定します。
生成されるページには、Smart CDN を直接参照する通常の画像要素が含まれます。アプリケーションが画像データをプロキシすることはなく、別の派生画像をリクエストしても元画像は変更されません。
サンプルからアプリケーションへの組み込み
デモはローカルの CLI 認証情報を使用し、一時的な署名付きアクセス URL を作成します。ディレクトリを公開することはありませんが、すでに公開されているディレクトリにアップロードしても、そのディレクトリが非公開になるわけではありません。gallery.html は非公開にしてください。そこに含まれる URL を持つ人は、有効期限が切れるまで派生画像にアクセスできます。このサンプルでは、有効期限を正時にそろえることで、1 時間から 2 時間のアクセス期間を確保し、URL を再利用しやすくしています。URL の有効期限が切れたら、ページを再生成してください。実際のキャッシュ有効期間はレスポンスの Cache-Control ヘッダーで決まります。有効期限が切れても、すでにダウンロードされたデータは回収できません。
デプロイするアプリケーションでは、アップロード用の認証情報を分離し、smart_cdn:sign を使用するサーバー専用の配信キーを使ってください。ブラウザーで CLI からログアウトするとログインキーが失効するため、そのキーをアプリケーションキーとしてデプロイしないでください。署名前にユーザーを認証し、保存済みアセットレコードへのアクセス権を確認してください。ブラウザーから渡された任意のアセット ID や変換パラメーターに署名するエンドポイントは、決して公開しないでください。
アプリケーションに合った連携方法を選んでください。
- サーバー側のアップロード: Node SDK の
storeAsset()ヘルパーを使用し、返されたレシートを所有者と関連付けて保存してください。既存の S3 や Assembly によるアップロードでも、正規の Storage レコードを取得できます。ファイル名から独自にアセット ID を作らないでください。 - React または Next.js:Next.js 向け Viewer ガイドまたは
React の連携機能を使用すると、レスポンシブな表示、読み込み状態、ギャラリーを扱えます。Viewer は公開アルファ版です。テストしたバージョンに固定してください。既存の Next.js プロジェクトでは、別のアプリを作成せずに
image initを使えます。 - ユーザー投稿型ギャラリー:Convex のウェディングデモは、Uppy によるアップロード、リアクティブなレシートクエリ、認可付きの写真・動画配信を組み合わせています。同じ Storage の識別情報と配信ヘルパーを基盤とし、ゲストのアクセスルールはアプリケーション側で管理します。
ファイルを置き換えるとどうなる?
アセットとバージョンの組み合わせは、「現在このパスにあるもの」ではなく、保持されている特定のデータを厳密に指定します。Storage 内で移動しても、この識別情報は維持されます。上書きすると新しいバージョンが作成されます。置き換え後のファイルを表示するには、新しいレシートを保存してください。旧バージョンに固定された URL は、そのバージョンが保持され、アクセス可能な間は引き続き旧バージョンを参照します。ここでの v は実際の Storage バージョン ID であり、v=2 によるキャッシュ回避用の値ではありません。
同じ組み込み機能で、保存済みの PDF や動画も、そのファイル自体のアセットとバージョンのレコードを使ってプレビューできます。Node SDK/CLI 6.9.0 以降では、storage store は動画、音声、ドキュメント、その他の元ファイルも受け付けます。上記のギャラリーサンプルは引き続き画像を対象としています。ほかのファイル、プレビュー、元ファイルのダウンロードについては、複数メディアを扱うレシピを参照してください。特殊な処理には、署名を必須とするカスタム
Template と URL Transform を使用し、各 Robot の Smart CDN 対応状況を確認してください。負荷の高い動画処理は Assembly で行い、結果を保存して配信します。
実行可能なサンプルから始めて、元画像はそのままに、派生画像を 1 つ変更してみてください。
