Cloudinaryは画像と動画をアップロードして保管し、URLのパラメータで変換してCDNから配信するSaaSです。使い始めは管理画面へのドラッグ&ドロップで完結しますが、業務システムへ組み込む段階になると、SDKからのアップロード、署名の生成、変換URLの設計、そしてクレジット消費の見積もりが順番に問題になります。この記事では、公式ドキュメントの定義に沿って三層構造を分解したうえで、Node.js SDKでの動作コード、f_autoとq_autoの指定基準、1クレジットの換算から逆算した月額の試算、フロントから直接アップロードするときの設計、そしてS3とCloudFrontで自前構築する場合との分岐点までを示します。受託開発の現場で使っている採用条件と見送り条件も最後にまとめました。
まとめ：無料枠25クレジットで足りる規模と有料プランへ移る分岐点
Cloudinaryの判断はクレジットの消費速度でほぼ決まります。無料のFreeプランは月25クレジットで、1クレジットが変換1,000回・管理ストレージ1GB・画像帯域1GBのいずれかに相互換算される仕組みです。つまり無料枠の実体は「保管量＋転送量＋変換回数の合計が25単位まで」であり、画像を数百枚置いて月数万PV程度の企業サイトなら収まります。月間10万PVを超えるメディアや、ユーザー投稿で画像が積み上がるサービスは、帯域側から先に枠を食い潰します。
導入の判断はシンプルです。画像変換のコードを自前で持ちたくない、かつ配信量が月数十GB以下なら、Cloudinaryに寄せたほうが実装工数も運用負荷も下がります。逆に、すでにS3とCloudFrontが動いていて配信量が数百GB規模、あるいは画像の保管先を自社の管理下に置く要件があるなら、月額の逆転が起きる条件に該当するわけです。その分岐点の計算方法を後半の章で数字付きで示します。
保管・変換・CDN配信を1本のURLで完結させるCloudinaryの構造
Cloudinaryを「画像置き場」と捉えると設計を誤ります。実体は3つの機能が縦に積まれたサービスで、どの層が課金対象かを分けて理解しないと、クレジットの読みが外れます。
メディアライブラリ・変換エンジン・CDNが分担する3つの役割
第1層のメディアライブラリは、アップロードしたアセットの保管場所です。ここで消費するのは管理ストレージで、元ファイルと生成された派生ファイルの両方が容量に乗ります。第2層の変換エンジンは、リクエストされたURLのパラメータを解釈して画像を加工する部分です。同じ加工結果は再利用されるため、初回の生成だけが変換回数として数えられます。第3層のCDNが、生成済みのファイルを配信します。ここで消費するのが帯域です。
3層のうち、想定外にクレジットが減るのは変換エンジンの層です。幅の値を外部からそのまま受け取るような実装にすると、w_301からw_999まで別々の派生が作られ、変換回数もストレージも同時に膨らみます。配信そのものの仕組みを押さえておきたい場合は、CDNの仕組みとキャッシュ制御を整理した記事を先に読むと、この3層の役割分担が掴みやすくなります。
cloud nameとpublic_idで組み立てる配信URLの構成規則
配信URLは固定の並びで組み立てられます。ホストの後にアカウント固有のcloud name、アセット種別、配信タイプ、変換パラメータ、そしてアップロード時に決まるpublic_idが続く形です。パラメータはカンマ区切りで1つの区画にまとめ、区画の後ろにpublic_idを置きます。
# 配信URLの並び（cloud nameが demo、public_idが sample.jpg の場合）
https://res.cloudinary.com/demo/image/upload/f_auto,q_auto,w_800,c_fill/sample.jpg
# 変換なしの原本URL
https://res.cloudinary.com/demo/image/upload/sample.jpgパラメータの意味は公式の変換リファレンスに一覧で定義されています。w_は幅、c_は切り抜き方法、f_は配信形式の指定です。この並びを見れば、アプリケーション側は文字列を組み立てるだけで加工結果を受け取れると分かります。画像加工のライブラリをサーバーに入れる必要がありません。
Node.js SDKでのアップロードと変換URL生成までの動作コード
管理画面からのアップロードは手作業の範囲です。業務システムに組み込むなら、SDK経由でアップロードし、返ってきたpublic_idを自社のデータベースに保存する形になります。
cloudinary_npm 2系の導入とCLOUDINARY_URLでの認証設定
Node.js向けのSDKはcloudinary/cloudinary_npmで公開されています。READMEの互換性表では2系がNode.js 9以降に対応し、1系はメンテナンス終了の扱いです（2026年9月時点）。新規実装で1系を選ぶ理由はありません。認証情報は環境変数CLOUDINARY_URLに1行で書く方式が公式の手順で、cloud name・API key・API secretがこの1本に含まれます。
# インストール
npm install cloudinary
# 認証情報を環境変数で渡す（値はConsoleのProduct Environment Credentialsから取得）
export CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>この文字列にはAPI secretが含まれるため、リポジトリへのコミットは避け、シークレットマネージャーや実行環境の環境変数として渡してください。フロントエンドのビルド成果物に混ざると、第三者が任意のファイルをアップロードできる状態になります。
uploaderで画像を登録し変換URLを受け取るまでの実行コード
アップロードと変換URLの生成は、Node.js統合ドキュメントの手順どおりに書けば数行で動きます。次のコードはローカルファイルを登録し、幅400・高さ400で切り抜いたうえで形式と品質を自動解決するURLを返します。
const cloudinary = require('cloudinary').v2;
async function main() {
// ローカルの画像を登録する。public_idを指定すると再アップロード時に上書きできる
const result = await cloudinary.uploader.upload('./assets/hero.jpg', {
public_id: 'articles/hero',
overwrite: true,
});
console.log(result.public_id, result.bytes, result.format);
// 保存したpublic_idから配信URLを組み立てる
const url = cloudinary.url(result.public_id, {
width: 400,
height: 400,
crop: 'fill',
gravity: 'auto',
fetch_format: 'auto',
quality: 'auto',
secure: true,
});
console.log(url);
}
main().catch((e) => {
console.error(e.message);
process.exitCode = 1;
});戻り値にはpublic_idのほかにbytes（ファイルサイズ）、width、height、versionが含まれます。自社DBに保存するのはpublic_idだけで足り、URLそのものを保存するとパラメータを変えたくなったときに全件更新が必要になる設計です。REST APIを直接叩く場合のエンドポイントはapi.cloudinary.com/v1_1/<cloud name>/<resource_type>/uploadで、resource_typeにはimage・raw・video・autoを指定します。100MBを超えるファイルはチャンク分割でのアップロードが必須とアップロードのドキュメントに明記されています。
f_autoとq_autoが返す配信形式と品質レベルの指定基準
Cloudinaryを入れて体感が変わるのは、この2つのパラメータを付けたときです。どちらもリクエスト元のブラウザを見て解決するため、配信時に評価される点が設計上の制約になります。
f_autoが返すAVIF・WebP・JPEG XLの選択規則と容量の実測差
f_autoは、リクエストしてきたブラウザが解釈できる形式のうち軽いものを選んで返します。公式ドキュメントが挙げる候補はAVIF、JPEG XL、WebP、animated AVIF、animated WebP、そしてどれも使えない場合の元形式です。同ドキュメントの500px幅の比較例では、AVIFが14.6KB、WebPが16.1KB、JPEG XLが21.4KB、元のJPEGが33.5KBと示されています。元JPEGに対してAVIFはおよそ44%の容量です。
| 形式 | 公式例の容量（500px幅） | 元JPEG比 |
|---|---|---|
| AVIF | 14.6KB | 約44% |
| WebP | 16.1KB | 約48% |
| JPEG XL | 21.4KB | 約64% |
| 元JPEG | 33.5KB | 100% |
注意点が1つあります。公式ドキュメントはf_autoをincoming transformation（アップロード時の変換）と名前付き変換で使わないよう明記しています。ブラウザごとに配信時点で解決する必要があるためです。アップロード時に形式を固定してしまうと、この仕組みは働きません。
q_autoのbest・good・eco・lowの違いと既定値が切り替わる条件
q_autoは画像の内容を解析して圧縮率を決めます。水準は4段階あり、コロンで明示する指定方法です。q_auto単体はgood相当ですが、Save-Dataヘッダーを送るブラウザに対しては自動的にecoへ切り替わる、と公式ドキュメントに書かれています。通信量を抑えたい端末には勝手に軽い方を返す設計です。
| 指定 | 圧縮の強さ | 想定する使いどころ |
|---|---|---|
| q_auto:best | 弱い | 商品の質感を見せる写真・作品ポートフォリオ |
| q_auto:good | 中（既定相当） | 記事のアイキャッチ・一般的なコンテンツ画像 |
| q_auto:eco | 強い | 一覧ページのサムネイル・低速回線向け |
| q_auto:low | 最も強い | プレースホルダー・遅延読み込み前の低解像度 |
実務では既定のq_autoをサイト全体に当て、質感が問われる箇所だけq_auto:bestに上げる運用が扱いやすい形です。goodとbestの中間が必要ならq_auto:good:sensitiveが用意されています。最初から全画像をbestで配信すると、後述する帯域クレジットの消費が跳ね上がります。
クレジット換算から逆算する画像配信の月間PV別の実額と有料化の目安
ここが上位の解説記事でほぼ触れられていない部分です。「無料枠25クレジット」という数字だけでは、自分のサイトが収まるのか判断できません。換算の定義に自分の数字を当てて計算します。
1クレジットが変換1,000回・ストレージ1GB・帯域1GBに対応する換算
公式の料金ページによれば、1クレジットは変換1,000回、管理ストレージ1GB、画像帯域1GB、動画帯域2GB（有料プランの2対1ブースト）のいずれかに相互換算されます。プランごとの月額とクレジット数は次のとおりです（2026年9月時点・米ドル）。
| プラン | 月額（月払い／年払い） | 月間クレジット | ユーザー数 |
|---|---|---|---|
| Free | $0 | 25 | 3 |
| Plus | $99／$89 | 225 | 3 |
| Advanced | $249／$224 | 600 | 5 |
| Enterprise | カスタム | カスタム | カスタム |
相互換算という点が計算を単純にします。ストレージも帯域も変換も同じ通貨で数えられるため、「保管GB＋転送GB＋変換回数÷1,000」を足した合計が枠に収まるかを見れば済みます。
月間10万PVの記事メディアで無料枠25クレジットを使い切る計算
具体的な数字を当てます。記事1ページあたり画像5枚、f_autoとq_autoを効かせて1枚平均40KBとすると、1ページビューあたりの転送は約200KBです。月間10万PVなら転送量は約20GB、つまり帯域だけで20クレジットを消費します。保管している画像が原本2,000枚で計3GB、派生を含めて4GB程度なら、ストレージで4クレジット。合計24クレジットで、無料枠25の内側にかろうじて収まる計算です。
ここに変換回数が乗ります。デバイス幅ごとに3サイズ、形式で2種類（AVIFとWebP）を生成すると、画像1枚あたり6派生。2,000枚なら12,000回で12クレジットです。合計36クレジットとなり、無料枠は初月で超えます。Plusプラン225クレジットなら、同じ条件のまま月間PVが5倍から6倍になるまで耐えられる計算です。
この試算で分かるのは、最初に枠を食うのは帯域だという点です。キャッシュが効いたあとは変換回数が落ち着くため、運用が定常化すると帯域とストレージの2項目だけを見ていれば足ります。逆に、キャンペーンで画像を大量差し替えする月は変換側が跳ねます。
署名付きアップロードとunsigned uploadの使い分けと漏えい対策
アップロードをどこから実行するかで、設計が2つに分かれます。ここを間違えるとAPI secretが公開される事故になるため、業務システムでは必ず先に決めます。
api_secretを配布せずに署名を生成するサーバー側の手順
signed uploadは、fileに加えてapi_key、timestamp、signatureを送る方式です。公式ドキュメントによれば署名はtimestampを含む全リクエストパラメータから生成し、有効期間は1時間と定められています。署名の作り方は認証署名のドキュメントに定義があり、パラメータ名をアルファベット順に並べて&で連結し、末尾にAPI secretを付けてハッシュ化する手順です。
// サーバー側で署名だけを発行し、ブラウザへ返す
const cloudinary = require('cloudinary').v2;
app.post('/api/upload-signature', (req, res) => {
const timestamp = Math.round(Date.now() / 1000);
const params = { timestamp, folder: 'user-uploads' };
// api_secretはサーバー側にのみ存在する
const signature = cloudinary.utils.api_sign_request(
params,
process.env.CLOUDINARY_API_SECRET
);
res.json({ timestamp, signature, folder: params.folder });
});ブラウザはこのレスポンスとファイルをCloudinaryへ直接送ります。API secretがクライアントへ渡らないため、第三者が任意のパラメータでアップロードを実行できません。署名対象にfolderを含めておけば、保存先ディレクトリの改ざんも防げます。
upload_presetで縛るunsigned uploadの制限と悪用の防ぎ方
もう一方のunsigned uploadは、アップロードプリセットに事前定義した設定名だけでアップロードする方式です。署名を作るサーバーが不要なので、静的サイトやプロトタイプでは手数が減ります。ただし指定できるパラメータが制限されるうえ、プリセット名が分かれば誰でもアップロードできます。プリセット名はブラウザのネットワークタブに丸見えです。
採用するなら、プリセット側で保存先フォルダを固定し、変換で幅の上限を掛け、モデレーションを有効にする、という縛りを必ず入れてください。それでも、外部からの投稿を受ける本番サービスでunsigned uploadを選ぶ判断は勧めません。ストレージクレジットを他人に消費される経路を、防ぐ手段なしに開けることになります。認証済みユーザーの投稿であれば、署名発行のエンドポイントを1本足すだけで塞げます。
S3とCloudFrontで自前構築する場合の工数と切り替えの分岐点
Cloudinaryが提供する機能は、AWSの部品を組み合わせても作れます。どちらを選ぶかは好みではなく、配信量と要件で決まります。
S3・CloudFront・sharpで同等機能を作る場合の実装範囲と運用負荷
自前構成の最小形は、S3に原本を置き、CloudFrontで配信し、Lambda@EdgeまたはCloudFront Functionsでリクエストを受けてsharpで変換し、変換済みをS3へ書き戻してキャッシュする、という組み合わせです。実装しなければならないのは、変換パラメータのパース、許可する幅と形式のホワイトリスト、変換済みの命名規則、キャッシュキーの設計、Acceptヘッダーを見た形式振り分け、そして変換失敗時のフォールバックです。
料金側は安くなります。S3のストレージ単価とCloudFrontの転送単価は、Cloudinaryのクレジット換算より桁で安い水準です。実額の内訳はS3の料金を東京リージョンの単価で計算した記事に整理しており、ストレージそのものの仕組みはAmazon S3の仕組みとストレージクラスを解説した記事で確認できます。ただし、Lambda@Edgeの実行課金と、上記の実装・保守にかかる人件費が乗ります。ここを無視した比較は成立しません。
Cloudinaryを見送る3つの条件と自前構成へ寄せる判断基準
受託開発の現場で使っている判断基準を、条件付きで言い切ります。次の3つのいずれかに当たるなら、Cloudinaryは採用しません。
- 月間の画像転送量が恒常的に500GBを超える。この規模ではクレジット換算の帯域コストが自前構成の数倍になり、実装工数を回収できます
- 画像そのものが機微情報にあたる（本人確認書類、医療画像、契約書のスキャン）。保管先を自社のAWSアカウント内に限定する要件と相反します
- すでにCloudFrontとS3で配信基盤が動いており、画像変換だけを足せばよい。配信経路を二重に持つ運用コストのほうが高く付きます
逆に、これらに当たらないなら迷わずCloudinaryに寄せる方針です。とくに立ち上げ期のサービスや、画像点数が数千枚規模の企業サイトでは、変換基盤の実装に2人日から5人日を使うより、URLパラメータで済ませて機能開発に人を回したほうが成果が出ます。SaaSと自社システムの接続設計や、後から自前構成へ移す前提のインターフェース設計で迷う場合は、API開発・システム連携で相談を受け付けています。
移行のしやすさも判断材料です。public_idだけを自社DBに保存し、URL生成を1つの関数に閉じ込めておけば、あとで自前構成へ切り替えるときに差し替えるのはその関数だけで済みます。URLを直接DBに入れる設計にすると、この移行が全件更新になります。
よくある質問
Cloudinaryの導入検討でよく挙がる質問を、公式ドキュメントの定義と実務の判断に沿ってまとめました。
Cloudinaryの無料プランは商用サイトでも使えますか？
Freeプランは月額$0で月25クレジット、ユーザー3名までという条件で提供されており、商用利用を禁じる制限は料金ページに記載されていません。実務上の制約はクレジット量のほうです。画像転送が月20GBを超えると枠を使い切るため、月間10万PV規模のメディアではすぐ上限に触れます。企業のコーポレートサイト程度なら無料枠で運用できます。
クレジットを使い切ると画像の配信は止まりますか？
クレジットは変換・ストレージ・帯域に相互換算される共通単位で、消費が枠に達したあとの扱いはプランとアカウント設定に依存します。運用では枠に達する前に検知する仕組みが要ります。Console上の使用量を定期的に確認し、帯域とストレージが枠の8割に届いた時点で上位プランへの切り替えを検討するのが現実的な運用です。
f_autoとq_autoは両方付けるべきですか？
配信形式と圧縮率は独立して効くため、両方付けるのが基本です。公式ドキュメントでも両者を並べたURL例が示されており、記述順序は結果に影響しません。ただしf_autoはアップロード時の変換や名前付き変換では使えません。ブラウザごとに配信時点で解決する仕組みだからです。
アップロードできるファイルサイズの上限はいくつですか？
最大アップロードサイズはプランとアカウント設定に依存し、公式ドキュメントはConsoleのAccountタブで現在の制限を確認するよう案内しています。実装側で確実に押さえるべき点は、100MBを超えるファイルはチャンク分割でのアップロードが必須という仕様です。動画を扱う場合は、この分割処理に対応したSDKのメソッドを使ってください。
Cloudinaryから他のサービスへ移行するのは難しいですか？
原本はAdmin APIで取得できるため、データそのものの持ち出しは可能です。難所は配信URLのほうで、変換パラメータを含むURLをHTMLやDBに直書きしていると、移行時に全件の書き換えが発生します。public_idだけを保存し、URL生成を1箇所の関数にまとめる設計にしておけば、移行の影響範囲はその関数に限定できます。
関連記事
- CDNとは？仕組み・キャッシュ制御からサービスの選び方まで実装目線で解説：Cloudinaryの第3層にあたる配信の仕組みとキャッシュ制御の前提知識
- Amazon S3とは？オブジェクトストレージの仕組み・ストレージクラスと料金・採用判断：自前構成の保管層にあたるS3の仕組みとクラス選定
- S3の料金を実額で計算する｜東京リージョンの単価内訳とコストを下げる設定手順：自前構成へ切り替えた場合の実額を突き合わせる材料
- 動画配信システム開発：動画側の変換・配信を含む基盤を構築する場合の相談窓口
