Cloudinary の Upload Presets でアップロード設定を一元管理する

ベルリンから伊藤です。

Cloudinary を使っていると、

「アップロードのたびにフォルダやタグ、メタデータを指定するのが面倒」
「配信速度を上げるため変換を事前生成しておきたい」
「ユーザ生成コンテンツを圧縮してアップロードさせたい」

といった場面が出てきます。

これらを一気に解決してくれるのが Upload Presets という機能です。本記事ではプリセットの概念から、実用的なユースケース、Signed/Unsigned の使い分けまでを整理してご紹介します。

この記事でわかること

• アップロードプリセットとは何か
• 代表的なユースケース
• Signed と Unsigned の違い
• 作成方法と設定のポイント
• 実装時の注意点

アップロードプリセットとは

アップロード時に適用する設定をまとめて事前定義しておく機能です。一度プリセットを作っておけば、アップロード時にはプリセット名を指定するだけで、定義した設定がすべて適用されます。

プリセットに含められる主な設定には次のものがあります。

• 保存場所：フォルダ、public ID の命名規則、上書きポリシー
• タグ・メタデータ：タグ、コンテキストメタデータ、構造化メタデータ
• Incoming Transformations：フォーマットやサイズなど、保存前にオリジナルへ適用する変換
• Eager Transformations：アップロード時に変換アセットを事前生成
• アセットの制御：アクセス管理、許容フォーマットなど
• 通知：アップロード完了時の Webhook 通知

アップロードプリセットの呼び出し

作成したプリセットは、Cloudinary のあらゆるアップロード経路から呼び出せます。

コンソールの Media Library からアップロード時：

デフォルト設定：

API とコンソールのそれぞれのアップロードに対して、画像・動画・それ以外でデフォルトプリセットを指定しておくことができます。

一度作ったプリセットを指定すれば、サーバーサイド/クライアントサイドアップロード・GUI 手動アップロード・既存システムからの自動取り込みまで、すべて同じ設定での統一が可能です。

プリセットのユースケース

1. アセット名と保存場所の規則化

複数の開発者や複数のアプリケーションから Cloudinary にアップロードする場合、どの経路でも同じフォルダ構成・命名規則・タグ付けにしたいシーンは多いはず。例えば次のようなプリセットを作成し、デフォルトプリセットとしてコンソール・API 両方に設定しておけば、upload_preset を明示しないアップロードにも自動適用されます。

• フォルダを products/2026/ に固定
• 元のファイル名を public ID に使う
• すべてのアセットに production タグを付与

2. 移行時のフォーマット・サイズ調整

Cloudinary に既存アセットを大量に移行する際、ブラウザで直接表示できないフォーマット（TIFF、BMP、HEIC、RAW など）が混ざっていたり、過去のカメラで撮影した数十 MB の高解像度画像が混ざっていたりするケースがあります。
プリセットで Incoming Transformation を指定すれば、保存前に強制的に変換できます。

例えば f_jpg,c_limit,w_3000,h_3000,q_auto:best と設定すると、

• f_jpg: ブラウザフレンドリーな JPEG に統一
• c_limit,w_3000,h_3000 : 最大 3000px に抑える
• q_auto:best: 視覚的な品質を保ちつつビットレートを下げる

のようにオリジナルが軽量化された状態で保存されるので、ストレージ消費量そのものを削減できる効果があります。

UGC のアプリにおいても、ユーザがアップロードする画像・動画は巨大すぎるファイルや想定外のフォーマットが混ざるため、このような設定を入れることで保存前にサーバーサイドで強制的に正規化できます。

動画なら du_60（最大 60 秒にトリム）なども便利です。

3. Add-on で AI 自動ロジックを適用

固定のタグを指定するのではなく、AI による自動判定でのタグ付けなど、Add-on を使った自動処理を走らせることもできます。

• 自動タグ付け：Google や Amazon Rekognition で被写体を自動的にタグ付け
• モデレーション：Cloudinary Moderation や Amazon Rekognition AI Moderation で不適切コンテンツを自動審査
• 背景除去：Cloudinary AI Background Removal で背景を自動で透過化
• 顔検出：Advanced Facial Attributes Detection で顔の位置・属性を取得しスマートクロップなどに活用
• OCR：画像内のテキストを抽出してメタデータ化
• Auto-captioning：AI で画像説明文を生成

利用可能な Add-on の全リストは Cloudinary Add-ons でご確認ください。コード側にロジックを書かずに、アップロード経路すべてに同じ処理を適用できるのが利点です。

4. eval パラメータでアップロード時に動的に判定

プリセットの動作を完全に固定するのではなく、アップロードされたアセットの内容に応じて動的に振る舞いを変えたいケースもあります。例えば…

• 横幅が 4000px を超える画像だけリサイズ＆large-source タグを付与
• 顔検出で人物が写っている画像だけ顔中心にスマートクロップ
• 暗すぎる画像にだけ自動で明度補正を適用
• 特定のフォーマットの場合は Incoming transformation を適用しない

これを実現するのが eval パラメータ です。アップロード時の解析結果（width, height, faces など）を JavaScript 式で参照し、その場でアップロード設定を調整できます。

// ファイル名から値を抽出してメタデータに指定
var parts = (resource_info.filename || "").split("_"); 
if (parts.length > 1) {
  upload_options.metadata = "year=" + parts[1].split(".")[0];
}

5. Eager Transformations で配信パフォーマンスを向上

動画など重い変換は、URL パラメータでの動的変換をすると初回リクエスト時にレイテンシーが発生するため、変換を事前生成する Eager Transformations が推奨されています。プリセットに仕込むことで、アップロード時に変換を事前生成することが可能です。

6. プロジェクト・環境ごとの設定分離

複数のプロジェクトや環境（dev / staging / production）で別々の動作をさせたい場合、プリセットを複数作って使い分けます。例えば…

• ugc-images：UGC 用、Incoming Transformation で 2000px 制限、自動モデレーション
• cms-articles：CMS 入稿用、articles/ フォルダ固定、Eager で WebP 生成
• dev-testing：開発用、dev/ フォルダ、自動削除タグ付き

Signed と Unsigned 設定

アップロードプリセットの作成時、 Signed か Unsigned のいずれかを選択します。

• Signed：認証ありでバックエンドからのアップロードや、Admin API・Media Library 経由のアップロードで使います。アップロードのデフォルト設定として使用するのもこちらです。
• Unsigned：認証なしでブラウザやモバイルのクライアントサイドアプリから直接アップロードさせたい場合やアップロードウィジェットを使いたい場合、または Auto Upload の設定に使います。

Unsigned では、プリセット名を指定すれば認証なしで誰でもアップロードができてしまうため、セキュリティ面からアップロードメソッドで使えるパラメータが制限されており、プリセット側での適切な事前設定が必要になります。

なお、プリセット名が知られたとしても、既存アセットの編集・削除・破壊行為はできません。

実際に作ってみた

コンソールから

設定 → Upload → Upload Presets → Add upload preset から手軽に作成できます。

API から

Admin API のupload_presets メソッドで作成できます。複数環境で同じプリセット設定を再現したい場合に便利です。

// Node.js SDK の例
cloudinary.v2.api
.create_upload_preset({
  name: 'ugc-images',
  unsigned: true,
  asset_folder: 'ugc/uploads',
  disallow_public_id: true,
  use_filename: true,
  use_filename_as_display_name: true,
  transformation: [
    { width: 2000, height: 2000, crop: 'limit' },
    { quality: 'auto:best'}
  ],
  categorization: "aws_rek_tagging",
  auto_tagging: 0.75,
  allowed_formats: "jpg,png,webp"})
.then(result=>console.log(result));

プリセットを使ったアップロードの実行例

上記で作成したプリセットを使ってアップロードを試してみました。アップロードに使ったのは、次のような画像です。

unsigned_upload メソッドを使い、プリセットを指定します。
今回はオプションでパブリック ID も指定してみています。

cloudinary.v2.uploader
.unsigned_upload("image.png", "ugc-images", {public_id: "test"})
.then(callback);

アップロードされた画像は次のような結果となりました。

• プリセット指定通りのフォルダやパブリック ID となり、タグが付与されている
• プリセットの disallow_public_id が有効なため、リクエストで指定したパブリック ID は無視されている
• 変換が適用されてサイズと容量が変化
  • サイズ：3024 × 3024 px → 2000 x 2000 px
  • 容量：17.9 MB → 8.09 MB

{'resources': [{'access_mode': 'public',
                'asset_folder': 'ugc/uploads',
                'asset_id': '71d5e8d406a40594a9bde0fac750b5e7',
                'backup': True,
                'bytes': 8095771,
                'created_at': '2026-06-04T07:29:58Z',
                'display_name': 'image',
                'format': 'png',
                'height': 2000,
                'public_id': 'image_cv3nuj',
                'resource_type': 'image',
                'secure_url': 'https://res.cloudinary.com/<cloud-name>/image/upload/v1780558198/image_cv3nuj.png',
                'tags': ['arch',
                         'bus',
                         'cable car',
                         'person',
                         'shoe',
                         'vehicle'],
                'type': 'upload',
                'url': 'http://res.cloudinary.com/<cloud-name>/image/upload/v1780558198/image_cv3nuj.png',
                'version': 1780558198,
                'width': 2000}]}

実装時の注意点

Eager Transformation での f_auto

f_auto （フォーマット最適化の変換パラメータ）は配信時にリクエスト元のブラウザを判定して最適フォーマットを動的に選択する機能ですので、Eager/Incoming では指定することはできません。

f_auto を含む変換の事前生成を行いたい場合には、各フォーマットを明示的に Eager で指定する必要があります。

詳細は Using automatic format (f_auto) in eager transformations をご確認ください。

変換適用するなら画像用と動画用は分ける

プリセット内に Incoming/Eager Transformation を入れる場合、画像と動画の両方で意味の通るパラメータだけにするか、リソースタイプごとに別プリセットを作りましょう。例えば動画専用の sp_auto を含むプリセットを画像アップロードに適用するとエラーになります。

Unsigned プリセットのセキュリティ

Unsigned のプリセット名がクライアントサイドで露出し、第三者がアップロードできる状況であることを踏まえて、overwrite オプションは常に false として扱われます（リクエストやプリセットで true 指定しても無視される）。これは意図しない上書きを防ぐためのセキュリティ仕様です。

これに加えて、以下のような制御を検討できます：

• allowed_formats：アップロードを許可するファイル形式を限定（例：jpg のみ）
• max_file_size：ファイルのサイズ上限
• Incoming Transformation を適用して、保存前に強制的に変換
• disallow_public_id：Unsigned アップロード時の public_id の指定を無効とし、上書き防止
• access_mode：アップロード後のアセット配信を public（誰でも URL でアクセス可能）から authenticated（認証必須）へ

これらを組み合わせることで、Unsigned プリセットでも安全に運用可能です。

パラメータの優先順位

アップロードプリセットの設定項目は、アップロードリクエスト時のオプションでも指定することができます。そのため両方に値がある場合には、Signed / Unsigned モードと指定パラメータによって、どう適用されるかが異なります。

フォルダモードによる挙動の違い

Cloudinary にはアカウント環境によって以下２つのフォルダモードがあります。

• Fixed (固定)：フォルダ&アセットパス＝パブリック ID（配信 URL に使われるアセットパス）
• Dynamic (動的)：2024年以降のデフォルト。アセット保存場所とパブリック ID が分離

このモードによって、利用できるパラメータが一部異なるため、注意が必要です。

まとめ

アップロードプリセットは、Cloudinary を実運用する上で大変便利な機能です！

• アップロード設定を一元管理できるので、コード変更なしに動作を変えられる
• Signed / Unsigned を使い分けることで、サーバー経由・クライアント直接の両方に対応
• Incoming / Eager Transformation で正規化・パフォーマンス改善
• Add-on の自動実行で AI 機能を活用しやすい
• 複数プリセットで環境・ユースケースごとに動作を分離

まずはコンソールから小さく作って試してみるのがおすすめです。

クラスメソッドでは Cloudinary の導入支援を行っています。アップロードプリセットを含む設計や移行のご相談は、ぜひお気軽にお問い合わせください。

以上、ご参考になれば幸いです！