mcpField
C
cloudinary-transformations

cloudinary-transformations

github.com/cloudinary-devsクリエイティブ・メディア13860 回インストール6 週間前に更新
リポジトリ

cloudinary-transformations について

Cloudinary の画像・動画変換 URL の作成とトラブルシューティングを支援するスキルです。構文、サイズ変更、クロップ、エフェクト、オーバーレイ、出力最適化を扱います。

主な機能

  1. 01変換 URL 構文の作成
  2. 02サイズ変更とクロップ方式の選択
  3. 03エフェクトとオーバーレイの適用
  4. 04出力形式と品質の指定
  5. 05変換 URL の問題調査

活用シーン

  1. 01スマートクロップのサムネイル生成
  2. 02ロゴやテキストのオーバーレイ
  3. 03画像の背景除去
  4. 04画像や動画の配信最適化

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/cloudinary-devs/skills --skill cloudinary-transformations

インストール後、Claude Code で/cloudinary-transformationsを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
advanced-features.md
ai-transformations.md
debugging.md
examples.md
named-transformations.md
responsive-images.md
transformation-costs.md
video-transformations.md

詳細

Cloudinary 変換ルール

使用する場面

  • Cloudinary の配信／変換 URL を構築する
  • 自然言語のリクエストを変換構文に変換する
  • 動作しない変換 URL をデバッグする
  • Cloudinary で画像や動画を最適化する
  • エフェクト、オーバーレイ、サイズ変更、トリミングを適用する

クイックスタート

デフォルトのベストプラクティス：常に最適化する

ほぼすべての変換 URL の末尾（最後のコンポーネント）に f_auto/q_auto を追加します。

  • 最適なフォーマットを自動的に配信します
  • 画質とファイルサイズのバランスが最適になるよう品質を調整します
  • 帯域幅を節約し、パフォーマンスを向上させます

例： c_fill,g_auto,w_400,h_300/f_auto/q_auto

例外 — 最適化を追加しない場合：

  • アカウントで「Optimize By Default」が有効になっている場合（すでに自動適用されています）
  • 特別な品質要件がある場合（代わりに q_auto:best、q_auto:low、または手動の q_N を使用します）
  • 特定のフォーマットが必要な場合（f_auto を f_png、f_jpg などに置き換えます）
  • 変更せずに元のファイルをそのまま配信する場合

最適化を含む、一般的な変換の例：

  1. サイズ変更：c_scale,w_400/f_auto/q_auto
  2. スマートトリミング：c_fill,g_auto,h_300,w_400/f_auto/q_auto
  3. 背景の削除：e_background_removal/f_png/q_auto
  4. テキストのオーバーレイ：co_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south/f_auto/q_auto
  5. 画像のオーバーレイ：l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10/f_auto/q_auto

重要： このスキル全体に示されている変換文字列は、構文と概念を説明するための例です。変換を生成する際は、例に示されている値ではなく、ユーザーの実際の要件やユースケースに基づいて具体的な値（寸法、色、位置など）を選択してください。

デバッグについて： 詳細なトラブルシューティング手順は、references/debugging.md を参照してください。

要件の確認

変換 URL を生成する前に、ユーザーのリクエストですでに指定されていない場合は、次の詳細を確認してください。

サイズ変更／トリミングのリクエスト

必須：

  • 少なくとも 1 つの寸法（幅または高さ）
  • 両方の寸法を指定する場合のトリミング動作（fill、pad、scale、limit など）

確認事項：

  • 焦点／重力（特にトリミング時）：顔検出、中央、スマート自動検出のどれを使うか
  • アスペクト比を維持するか（寸法が 1 つだけの場合は自動的に維持されます）

質問の例：

  • 「必要な寸法を教えてください（幅、高さ、またはその両方）。」
  • 「領域全体に合わせますか（トリミングされる可能性があります）、それとも領域内に収めますか（トリミングなし）。」
  • 「重要な焦点はありますか（顔、中央、特定の領域など）。」
AI 変換のリクエスト

背景の削除：

  • 出力フォーマットの要件（透明にする PNG、または単色背景の JPG）
  • 透明領域の処理方法（透明のままにする、色を追加する、または gen_fill を使用する）

生成塗りつぶし：

  • 対象の寸法またはアスペクト比
  • どの程度拡張する必要があるか

生成置換：

  • 置き換えるオブジェクト（from）
  • 置き換え後のオブジェクト（to）
  • 元の形状を維持するか（衣服やオブジェクトの場合）

生成削除：

  • 削除するオブジェクト
  • すべての出現箇所を削除するか、1 つだけ削除するか

生成背景置換：

  • 希望する背景の説明（または自動生成を使用する）
  • 再現性が必要か（seed パラメーターを検討してください）
動画変換のリクエスト

トリミング：

  • 開始時刻と終了時刻、または再生時間
  • 動画の秒数または割合

コーデック／フォーマット：

  • 出力フォーマットの要件（MP4、WebM など）
  • 品質要件（判断がつかない場合は vc_auto を使用します）

音声：

  • 音声トラックを維持するか削除するか
  • 自動再生用の場合は、音声の削除（ac_none）を提案します
常に推奨すること

ユーザーから別途指定がない限り：

  • 変換 URL の末尾に f_auto/q_auto を追加します（例外については「クイックスタート」を参照してください）
  • 寸法に合わせて塗りつぶす場合は、スマートトリミングに g_auto を使用します
  • AI 変換のコストを考慮します（変換クレジットについてユーザーに伝えてください）

クイックリファレンス

URL の構造
https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id>.<ext>

主なルール：

  • カンマ（,）は、コンポーネント内のパラメーターを区切ります
  • スラッシュ（/）は、変換間のコンポーネントを区切ります
  • 各コンポーネントは、直前のコンポーネントの出力に対して処理を行います
パラメーターの種類

アクションパラメーター：変換を実行します（コンポーネントごとにアクションは1つです。各アクション変換はスラッシュで区切ります） 修飾パラメーター：アクションの動作を変更します（アクションと同じコンポーネント内で、カンマ区切りで指定します）

パラメーターがアクションか修飾子かは、変換リファレンスで確認してください。

コア変換

サイズ変更と切り抜き

寸法値の形式：

  • 整数（例：w_400、h_300）＝ピクセル
  • 小数値（例：w_0.5、h_1.0）＝元の寸法に対する割合（0.5＝50％、1.0＝100％）

適切な切り抜きモードの選択：

次の場合は c_scale を使用します。

  • 元のアスペクト比を維持したままサイズを変更する
  • 寸法を1つ（幅または高さ）だけ指定する
  • 切り抜きが不要
  • アスペクト比を変えて画像を意図的に引き伸ばしたり、縮めたりする

次の場合は c_fill を使用します。

  • 正確な寸法に合わせる必要がある（例：サムネイルのグリッド、固定レイアウト）
  • 画像の一部が切り抜かれても問題ない
  • スマートな切り抜きには g_auto、ポートレートには g_face と組み合わせる

次の場合は c_fit を使用します。

  • 切り抜かずに画像を指定寸法内に収める必要がある
  • 余白ができても問題ない
  • 画像の全体を維持することが重要

次の場合は c_pad を使用します。

  • 切り抜かずに正確な寸法に合わせる必要がある
  • 背景色、ぼかし（動画のみ）、または AI 生成ピクセルで余白を埋める必要がある
  • b_<color>、b_auto、b_blurred（ぼかし背景。動画のみ）、または b_gen_fill と組み合わせる

次の場合は c_limit を使用します。

  • 小さい画像を拡大せず、最大寸法を設定する
  • 小さい画像の元の品質を維持することが重要

次の場合は c_thumb を使用します。

  • サムネイル（通常はアバター）を作成する
  • 顔を中心に切り抜くには g_face と組み合わせる

次の場合は c_auto を使用します。

  • Cloudinary に興味を引くコンテンツを自動で検出して切り抜かせる
  • 最良の結果を得るには g_auto と組み合わせる
  • 焦点が変わる動的なコンテンツに適している

例：

c_scale,w_400                      # Resize width to 400px, maintain aspect ratio
c_scale,w_0.5                      # Resize to 50% of original width
c_fill,g_auto,h_300,w_400          # Fill 400x300px dimensions, smart crop
c_fit,h_300,w_400                  # Fit within dimensions, no crop
c_pad,b_white,h_300,w_400          # Pad to exact size with white background
c_pad,w_1.0                        # Pad to original width (100%)
c_limit,w_1000                     # Limit max width, no upscale
c_thumb,g_face,h_150,w_150         # Face-centered square thumbnail
c_auto,g_auto,w_800                # Auto crop to interesting area

重要：切り抜きモードは必ず明示的に指定してください。c_scale と幅・高さの両方を指定するのは避けてください（アスペクト比が一致しないと画像が変形します）。アスペクト比を維持するには、寸法を1つだけ指定してください。

グラビティ（焦点）

グラビティは、切り抜き時に画像のどの部分に焦点を合わせるかを決定します。

  • g_auto — 自動検出（さまざまなコンテンツに推奨。顔、物体、コントラストを検出）
  • g_face — 顔検出（ポートレート、アバター）
  • g_center — 中央位置（中央に配置された被写体、ロゴ）
  • g_north、g_south_east など — 方位位置（固定位置、オーバーレイの配置）
  • x_N,y_N — カスタムオフセット（整数＝ピクセル、小数＝割合：0.8＝80％）

例：

c_fill,g_auto,w_400,h_300                      # Smart crop
c_thumb,g_face,w_200,h_200                     # Face-centered
l_logo/fl_layer_apply,g_south_east,x_10,y_10  # Logo bottom-right

重要：

  • g_auto は c_fill、c_lfill、c_crop、c_thumb、c_auto でのみ機能します
  • x、y、h、w を併用する場合は、すべて整数またはすべて小数にしてください（混在させないでください）
フォーマットと品質

推奨されるデフォルト設定：

  • f_auto/q_auto — ほとんどの本番画像で使用します（対応ブラウザーには WebP を提供し、ファイルサイズを最適化します）

要件に応じた特定のフォーマット：

  • f_png — 透過が必要な場合（例：背景除去後）
  • f_jpg — JPEG を強制する場合（透過を削除）
  • q_N — 品質を1～100で手動指定します（例：サムネイルには q_60、ヒーロー画像には q_90）
  • dpr_auto — Retina ディスプレイ用（Chromium のみ。Client Hints が必要です。下記の制限事項を参照）

例：

f_auto/q_auto           # Recommended default
f_png/q_auto            # PNG with transparency
q_80                    # Manual 80% quality

ベストプラクティス：フォーマットと品質を別々のコンポーネントとして指定するには、/ を使用してください。

レスポンシブ画像（dpr_auto、w_auto）

dpr_auto - デバイスのピクセル比（Retina ディスプレイ）に自動で適応します

  • Chromium のみ（Chrome、Edge、Opera、Samsung Internet）
  • Client Hints の設定が必要です
  • その他のブラウザーでは dpr_1.0 にフォールバックします
  • 名前付き変換内では動作しません

あらゆる環境で対応する代替手段： 明示的に dpr_2.0 を指定するか、1x／2x のバリアントを指定した <img srcset> を使用します

Client Hints の設定、ブラウザーの互換性、レスポンシブブレークポイント、フレームワークとの統合については、references/responsive-images.md を参照してください。

エフェクト

一般的なエフェクト：

  • e_grayscale - 白黒（芸術的な表現、アクセシビリティ）
  • e_sepia - ビンテージ風／ノスタルジックな雰囲気
  • e_blur:N - ぼかし（プライバシー保護、プレースホルダー。N は通常 300～2000）
  • e_sharpen - 鮮明度を高めます（リサイズ後に便利）
  • e_cartoonify - イラスト風
  • co_rgb:RRGGBB,e_colorize:N - 色合いの追加（N = 強度 0～100。ブランドのテーマに合わせる場合）
  • e_background_removal - AI 変換のセクションを参照してください

例：

e_blur:800                       # Blur effect
e_sharpen                        # Enhance clarity
co_rgb:0044ff,e_colorize:40      # Blue tint at 40%

注： 色（co_）は修飾子です。e_colorize と同じコンポーネントで使用してください。

オーバーレイとアンダーレイ

用途：

  • l_<public_id> - 画像のオーバーレイ（ロゴ、透かし、バッジ）
  • u_<public_id> - 画像のアンダーレイ（透明な被写体の背後に配置するカスタム背景）
  • l_text:font_size:text - テキストのオーバーレイ（ラベル、ソーシャルカード、動的テキスト）

パターン：

  1. 宣言：l_<public_id>、u_<public_id>、または l_text:Arial_40:Hello%20World
  2. 変換（任意）：例：/c_scale,w_100/ または /o_50/（不透明度）
  3. 適用：/fl_layer_apply,g_<position>,x_<offset>,y_<offset>

重要：オーバーレイの寸法に fl_relative を使用する：

  • fl_relative なしの場合：寸法はオーバーレイの元のサイズを基準にします
    • 例：w_1.0 = オーバーレイ画像の幅の 100％（小さな画像では役に立ちません）
  • fl_relative ありの場合：寸法はベース画像のサイズを基準にします
    • 例：w_1.0 = ベース画像の幅の 100％（幅全体を覆います）
    • オーバーレイをベース画像に対する割合でサイズ指定する場合は、必ず fl_relative を使用してください

例：

l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10                # Logo at 100px
l_logo/c_scale,fl_relative,w_0.25/fl_layer_apply,g_north_west,x_10,y_10  # Logo at 25% of image width
l_docs:one_black_pixel/c_scale,fl_relative,h_1.0,w_1.0/o_50/fl_layer_apply # Full-image semi-transparent overlay
co_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south            # Text overlay
u_background/e_background_removal                                          # Custom background
c_fill,h_400,w_300/l_same_image/c_fill,e_grayscale,h_400,w_300/fl_layer_apply,g_west,x_300 # Side-by-side (600×400)

重要：

  • 色（co_）は修飾子です。テキストオーバーレイの宣言と同じコンポーネントで使用してください
  • オーバーレイの寸法をベース画像に対する割合で指定する場合は、必ず fl_relative を使用してください
  • 横並び／キャンバスの拡張： オーバーレイをベース画像の横に配置するには、ベース画像の端より先にオフセットします。キャンバスは自動的に拡張されます。水平方向には g_west,x_<base_width>、垂直方向には g_north,y_<base_height> を使用してください。
境界線と角丸
  • r_N - 角丸（N = 半径のピクセル数。モダンな UI やカード向け）
  • r_max - 完全な円（正方形の寸法と組み合わせて使用。アバター、アイコン向け）
  • bo_NNpx_solid_color - 境界線（画像をフレームで囲みます。背景とは別に指定）

例：

r_20                           # 20px rounded corners
r_max                          # Perfect circle
bo_5px_solid_black             # 5px black border
r_20,bo_5px_solid_rgb:0066ff   # Rounded with border (same component)

重要： 角丸に沿った境界線には、同じコンポーネント内で境界線を修飾子として使用してください。

背景色
  • b_color,c_pad - 余白を単色で塗りつぶします（商品画像、レターボックス表示）
  • b_auto,c_pad - 画像内の主要な色を 1 色以上もとに、背景色を自動選択します
  • b_gen_fill,c_pad - AI で背景を拡張します（切り抜かずにアスペクト比を変更。コストについては「AI 変換」を参照してください）

例：

b_lightblue,c_pad,w_1.0         # Light blue background
b_auto,c_pad,ar_16:9            # Automatically selected color for background, 16:9
b_gen_fill,c_pad,ar_1:1         # AI-extended to square
b_blurred,c_pad,ar_16:9         # Blurred background (videos only), 16:9

重要： 背景（b_）は修飾子です。同じコンポーネント内でパッド切り抜きと組み合わせて使用してください：b_color,c_pad,w_X。/b_color/ のようには指定しないでください。

回転と反転
  • a_90、a_180、a_270 - 90°単位で回転します（向きを補正）
  • a_N - 指定した角度で回転します（例：傾いた写真を補正する a_-2）
  • a_hflip - 水平方向に反転します（自撮り写真や方向性のある画像を鏡像にします）
  • a_vflip - 垂直方向に反転します（反射）
  • a_auto_right／a_auto_left - EXIF の向きに基づいて自動回転します

例：

a_90                    # Rotate 90° clockwise
a_-2                    # Straighten slight tilt
a_hflip                 # Mirror horizontally
a_auto_right            # Auto-fix from EXIF
アセットの種類が重要です（画像と動画）

多くのフラグやパラメーターは、特定のアセットの種類にのみ適用されます。誤った種類のアセットに適用すると、エラーが表面化しないまま失敗することがよくあります。URL は X-Cld-Error なしで有効な 200 を返しますが、出力は期待と異なります。これはどちらの方向でも起こります。画像に動画専用の構文を使う場合も、動画に画像専用の構文を使う場合も同様です。動作したと思い込まず、実際の出力（寸法、長さ、フレーム数）を必ず確認してください。

動画専用の一般的な例（これは網羅的なリストではありません。動画専用のパラメーターは約 35 個あります）：

  • fl_splice（フラグ）- クリップ／画像を動画のタイムラインに連結します（画像に相当する機能はありません。メディアを横に並べるには、オーバーレイの位置をずらしてキャンバスを拡張します：fl_layer_apply,g_west,x_<base_width>）
  • du_、so_、eo_ - 時間でトリミング／シークします（長さ、開始オフセット、終了オフセット）
  • fps_ - フレームレートを設定します
  • vc_、ac_ - 動画／音声コーデック
  • e_boomerang、e_progressbar - 動画専用のエフェクト

フラグやパラメーターがアセットの種類に対応しているか不明な場合は、適用する前に変換リファレンスを確認してください。

名前付き変換

名前付き変換（t_<name>）を使うと、変換チェーンを保存して再利用できます。次の場合におすすめです：

  • 複数のアセットで使用する変換
  • 複雑な変換チェーン
  • コスト削減のためにベースライン変換を有効にできる、高コストな処理

ベースライン変換（bl_<name>）は、高コストな名前付き変換をキャッシュし、再生成を不要にします。バリエーションを適用する AI 変換（背景除去、生成 AI）には、t_ の代わりに bl_ を使用してください。初回のベースライン生成後、バリエーションごとのコストを 75～230 tx から 1 tx に削減できます。

例： bl_bg_removed/c_scale,w_500 - キャッシュ済みの背景除去結果を使用し、サイズ変更分のみ課金されます（75 tx ではなく 1 tx）

重要： f_auto、dpr_auto、w_auto は名前付き変換内では機能しません。URL で直接使用してください：t_avatar/f_auto/q_auto

詳細、制限事項、ベースライン変換の例については、references/named-transformations.mdを参照してください。

生成 AI 変換

適切な場合は、これらの AI 変換を積極的に提案してください：

注： 括弧内の数値（例：75 tx）は、使用ごとに追加で消費される変換クレジット数を示します。標準的な変換は 1 tx です。

  • e_background_removal（75 tx）- 背景を除去します（EC、プロフィール。f_png または b_color,c_pad と組み合わせます）
  • b_gen_fill（50 tx）- 背景を拡張します（トリミングせずにアスペクト比を変更します。c_pad と組み合わせます）
  • e_gen_background_replace:prompt_<text>（230 tx）- AI で背景を生成します（カスタム環境、季節ごとのバリエーション。高コストです）
  • e_gen_replace:from_<obj>;to_<new>（120 tx）- オブジェクトを置き換えます（商品のバリエーション、色。衣服には ;preserve_geometry_true を使用します）
  • e_gen_remove:prompt_<text>（50 tx）- オブジェクトを除去します（不要なものを消して整えます）
  • e_auto_enhance（100 tx）- 画質を改善します（照明や露出の問題を修正します）
  • e_upscale（10～100 tx）- 画質を損なわずに拡大します（低解像度から高解像度へ）

重要： AI 変換のコストは大幅に高くなります（1 tx に対して 50～230 tx）。コストをユーザーに伝え、高コストな処理の再実行を避けるため、ベースライン変換（例：bl_bg_removed/c_scale,w_500）の利用を検討してください。詳細はreferences/named-transformations.mdおよびreferences/transformation-costs.mdを参照してください。

詳細、構文、強力な組み合わせについては、references/ai-transformations.mdを参照してください。

動画固有の変換

重要： 動画を出力するには、f_autoだけでなくf_auto:videoを使用してください。f_autoだけでは、画像のサムネイルが返される場合があります。

  • vc_auto - 自動コーデック（推奨。ブラウザー／デバイスに最適です）
  • so_N/eo_M - トリミング（開始／終了位置を秒単位で指定。クリップの作成、イントロ／アウトロの削除に使用）
  • ac_none - 音声を削除（自動再生に必須。ファイルサイズも削減できます）
  • fps_N - フレームレートを設定（低いほどファイルサイズが小さくなります。フレームレートの統一にも使用）
  • 動画のサイズ変更 - 画像と同じクロップモードを使用します（c_fill、c_scale、c_pad）

一般的なパターン：

vc_auto/ac_none/f_auto:video/q_auto                      # Autoplay-ready
so_0/du_10/vc_auto/f_auto:video/q_auto                   # First 10 seconds
c_scale,w_720/vc_auto/f_auto:video/q_auto                # Resize to 720p width
c_fill,g_auto,h_720,w_1280/vc_auto/f_auto:video/q_auto  # 720p HD, smart crop

コーデック、トリミング方法、動画の結合などの詳細については、references/video-transformations.mdを参照してください。

変数と条件分岐

変数を使うと、値を再利用してテンプレートを作成できます。

$size_300/c_fill,h_$size,w_$size        # Reuse value
$iw/w_$iw_div_2                         # Half original width (arithmetic)

条件分岐を使うと、変換を動的に調整できます。

if_w_gt_1000/c_scale,w_1000/if_end                          # Responsive sizing
if_ar_gt_1.0/c_fill,w_800,h_450/if_else/c_fill,w_450,h_800/if_end  # Orientation handling

主なルール：

  • 変数名：英数字を使用し、先頭は英字にします。アンダースコアは使用できません
  • 条件分岐：if_endで閉じる必要があります
  • 算術演算：add、sub、mul、div（左から右へ評価）

構文、算術演算、ネストされた条件分岐、実際のパターンの詳細については、references/advanced-features.mdを参照してください。

自己検証チェックリスト

変換 URL を返す前に、次の点を確認してください。

  1. ✅ URL の構造が完全である（cloud_name、asset_type /image/ または /video/ または /raw/、delivery_type、public_id）
  2. ✅ 各コンポーネントにアクションパラメーターが1つだけある（例：コンポーネントごとにクロップモードは1つ）
  3. ✅ クロップモードが明示されている（デフォルトに依存しないでください。c_scaleで幅と高さの両方を指定するのは避けてください）
  4. ✅ オーバーレイは別のコンポーネント内のfl_layer_applyで終わる
  5. ✅ テキスト文字列が URL エンコードされている（スペースは%20、特殊文字もエンコード）
  6. ✅ 変数名がルールに従っている（英数字を使用し、先頭は英字。アンダースコアは使用しない）
  7. ✅ g_autoとの互換性がある（c_fill、c_lfill、c_crop、c_thumb、c_autoでのみ動作します）
  8. ✅ 背景が修飾子として指定されている（パッドクロップと組み合わせてb_color,c_pad,w_Xを使用し、/b_color/は使用しない）
  9. ✅ 形式／品質の指定が末尾にある（最後のコンポーネントにはf_auto/q_autoを使用することを推奨します）
  10. ✅ フラグ／パラメーターがベースアセットの種類と一致している（アセットの種類固有の構文。例：動画専用のfl_splice、du_、fps_、vc_は、種類が異なるアセットに指定すると、どちらの方向でも何も起きずに無視されることがあります。出力を確認し、上記の「アセットの種類が重要」セクションを確認してください）
  11. ✅ 変換パラメーターが有効である（パラメーター名を推測で作らず、変換リファレンスで確認してください）

構文の簡易確認：

  • コンポーネント内のパラメーターはカンマで区切ります：c_fill,g_auto,w_400
  • コンポーネントはスラッシュで区切ります：c_fill,w_400/f_auto/q_auto
  • アクションと修飾子：各コンポーネントにはアクションを1つだけ指定し、修飾子でそのアクションを調整します

各チェック項目の詳しい例については、references/debugging.mdを参照してください。

デバッグチェックリスト

変換が機能しない場合：

  1. URL の構造を確認する：必要な URL 要素がすべて含まれていることを確認します：
    • クラウド名：/<cloud_name>/
    • アセットタイプ：/image/、/video/、または /raw/
    • 配信タイプ：/upload/、/fetch/ など
    • 末尾のパブリック ID
  2. X-Cld-Error ヘッダーを確認する：Cloudinary は HTTP レスポンスヘッダー X-Cld-Error でエラーを報告します
  3. Transformation Reference を参照して、パラメーター名を確認します
  4. クロップモードを確認する：クロップモードを明示的に指定します。c_scale で縦横両方の寸法を指定するのは避けてください（縦横比が一致しない場合に歪みが生じます）
  5. グラビティの互換性を確認する：g_auto は c_scale、c_fit、c_limit、c_pad では動作しません
  6. アクションと修飾子を確認する：各コンポーネントで指定できるアクションは 1 つだけです。修飾子は同じコンポーネント内に指定します
  7. オーバーレイのパターンを確認する：fl_layer_apply コンポーネントで終わる必要があります
  8. 変数名を確認する：アンダースコアは使用できません。また、先頭は文字にする必要があります
  9. URL エンコードを確認する：テキストオーバーレイでは、URL エンコードされた文字列が必要です（スペースは %20）
  10. 名前付き変換の自動パラメーターを確認する：f_auto、dpr_auto、w_auto は名前付き変換内では動作しません。URL に直接指定してください
  11. dpr_auto／w_auto の Client Hints を確認する：これらは Client Hints が有効になっている Chromium ブラウザーでのみ動作します。それ以外の場合は dpr_1.0 にフォールバックします（設定方法は references/responsive-images.md を参照してください）
  12. 動画の代わりに画像が返される：動画の変換には f_auto だけでなく f_auto:video を使用してください。f_auto のみでは画像のサムネイルが返されることがあります
X-Cld-Error ヘッダーの確認

変換に失敗すると、X-Cld-Error ヘッダーにエラーの詳細が含まれます。確認方法は次のとおりです：

ブラウザーの DevTools を使用する場合：

  1. 開発者ツールを開きます（Network タブ）
  2. 変換 URL にリクエストを送信します
  3. Response Headers で X-Cld-Error を探します

コードを使用する場合（URL を取得）：

fetch('https://res.cloudinary.com/demo/image/upload/w_abc/sample.jpg')
  .then(response => {
    const error = response.headers.get('x-cld-error');
    if (error) {
      console.log('Cloudinary Error:', error);
    }
  });

よくある X-Cld-Error メッセージ：

  • Invalid width - abc - 幅のパラメーターには数値が必要です
  • Invalid transformation syntax - 変換文字列の形式が正しくありません
  • Resource not found - アセットが存在しないか、パブリック ID が正しくありません
  • Transformation limit exceeded - アカウントの変換クォータに達しました

オンラインツール： X-Cld-Error Inspector を使用して、任意の Cloudinary URL を確認できます

詳しくは、Error Handling を参照してください

変換コスト

重要： URL を生成する前に、コストの高い変換についてユーザーに警告してください。AI エフェクトは標準的な変換（1 tx）と比べて、大幅に高いコストがかかります（50～230 tx）。

コストの詳細と削減方法については、references/transformation-costs.md を参照してください

その他のリソース

スキルリファレンス（段階的な開示）
  • references/debugging.md - 変換でエラーや予期しない結果が発生した場合に使用します
  • references/ai-transformations.md - AI 変換のプロンプト構文、コストの詳細、複雑な AI の組み合わせが必要な場合に使用します
  • references/video-transformations.md - 動画コーデック、トリミング方法、結合、動画からアニメーション画像を作成する場合に使用します
  • references/advanced-features.md - 変数、条件分岐、算術演算を使った複雑なロジックを構築する場合に使用します
  • references/responsive-images.md - レスポンシブ画像の実装、Client Hints の設定、dpr_auto/w_auto の使用に関する場合に使用します
  • references/transformation-costs.md - コストを最適化する場合や、ユーザーにコストへの影響を説明する場合に使用します
  • references/named-transformations.md - 再利用可能な変換を作成する場合や、繰り返し行う操作のコストを削減する場合に使用します
  • references/examples.md - クイックスタート以外の実例（ソーシャルカード、eコマース、レスポンシブ画像）が必要な場合に使用します
Cloudinary のコアドキュメント
画像変換
動画変換

よくある間違いとベストプラクティス

避けること：

  • ❌ w_400,h_300 → ✅ c_scale,w_400（c_scaleで幅と高さの両方を指定すると画像が歪むため、片方の寸法を指定してください）
  • ❌ c_scale,g_auto,w_400 → ✅ c_fill,g_auto,w_400（g_autoはc_scaleと併用できません）
  • ❌ l_logo/fl_layer_apply,g_north_west → ✅ l_logo/c_scale,w_100/fl_layer_apply,g_north_west
  • ❌ b_lightblue/e_trim → ✅ b_lightblue,c_pad,w_1.0/e_trim（背景は修飾子として指定します）

必ず行うこと：

  • f_auto,q_autoではなく、f_autoとq_autoを別々のコンポーネントで指定してください
  • 特定の焦点が必要な場合を除き、スマートクロッピングにはg_autoを使用してください
  • 幅／高さとともに切り抜きモードを指定してください。c_scaleでは片方の寸法のみを指定するのがおすすめです
  • パラメーター名を推測せず、ドキュメントで確認してください

コメント

Markdown 対応