cloudflare-images

Cloudflare Images

ステータス：本番環境対応 ✅ | バージョン：3.0.0 | 最終確認日：2025-12-27

---

Cloudflare Images とは？

2 つの強力な機能を利用できます。

1. Images API：画像をアップロードして保存し、グローバルに配信します
2. 画像変換：あらゆる画像をリサイズ・最適化します

主なメリット：

• グローバル CDN による配信
• WebP／AVIF への自動変換
• 最大 100 個のバリアント
• アップロードするユーザーから直接アップロード可能（フロントエンドに API キーは不要）
• 非公開画像用の署名付き URL
• URL または Workers 経由であらゆる画像を変換

---

クイックスタート（5 分）

1. Cloudflare Images を有効にする

ダッシュボード → Images → 有効にする

アカウント ID を取得し、API トークンを作成します（Cloudflare Images：編集権限）。

2. 画像をアップロードする

curl --request POST \
  --url https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/images/v1 \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@./image.jpg'

重要： JSON ではなく、multipart/form-data を使用してください。

3. 画像を配信する

<img src="https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/public" />

4. 画像変換を有効にする

ダッシュボード → Images → Transformations → ゾーンで有効にする

あらゆる画像を変換できます。

<img src="/cdn-cgi/image/width=800,quality=85/uploads/photo.jpg" />

5. Workers 経由で変換する

export default {
  async fetch(request: Request): Promise<Response> {
    return fetch("https://example.com/image.jpg", {
      cf: {
        image: {
          width: 800,
          quality: 85,
          format: "auto"  // WebP/AVIF
        }
      }
    });
  }
};

詳しい手順については、references/setup-guide.md を読み込んでください。

---

3 つの主要機能

機能 1：Images API（アップロードとストレージ）

アップロード方法：

1. ファイルのアップロード（サーバー側）
2. URL 経由でのアップロード（外部から取り込み）
3. アップロードするユーザーからの直接アップロード（API キー不要）

ファイルのアップロード例については、templates/upload-api-basic.ts を読み込んでください。
ユーザーによるアップロードについては、references/direct-upload-complete-workflow.md を読み込んでください。

機能 2：画像変換

アップロード済みまたは外部のあらゆる画像を最適化します。

方法：

1. URL：/cdn-cgi/image/width=800,quality=85/path/to/image.jpg
2. Workers：cf.image フェッチオプション

すべてのオプションについては、references/transformation-options.md を読み込んでください。
Workers の例については、templates/transform-via-workers.ts を読み込んでください。

機能 3：バリアント

あらかじめ定義された変換（最大 100 個）です。

例：

• thumbnail：200x200、fit=cover
• hero：1920x1080、quality=90
• mobile：640、quality=75

詳しいガイドについては、references/variants-guide.md を読み込んでください。

---

重要なルール

必ず行うこと ✅

1. アップロードには JSON ではなく multipart/form-data を使用する
2. /cdn-cgi/image/ を使用する前に、ゾーンで画像変換を有効にする
3. ユーザーによるアップロードには 直接アップロードを使用する（API トークンを公開しない）
4. ブラウザーからの直接アップロードには CORS ヘッダーを設定する
5. 非公開画像には 署名付き URL を使用する
6. よく使うサイズには バリアントを設定する（動的変換を避ける）
7. WebP／AVIF の自動変換には format=auto を使用する
8. エラーコード（9401、9403、9413、5408）を 処理する
9. サイズと画質の最適なバランスを得るため、quality=85 に設定する
10. アスペクト比を統一するため、fit=cover を使用する

絶対に行わないこと ❌

1. フロントエンドのコードで API トークンを絶対に公開しない
2. ファイルのアップロードに JSON エンコードを絶対に使用しない
3. 直接アップロードで CORS 設定を絶対に省略しない
4. バリアント数の上限 100 個を絶対に超えない（ハードリミット）
5. ゾーンで有効にせずに 画像変換を絶対に使用しない
6. 公開コードに アカウント ID を絶対にハードコードしない
7. エラー処理を絶対に省略しない（アップロードは失敗する可能性があります）
8. quality >90 を絶対に使用しない（効果が頭打ちになります）
9. 画像の検証を絶対に省略しない（サイズ、形式、寸法）
10. プロキシを経由しないリクエストで 画像変換を絶対に使用しない

---

主な 2 つのユースケース

ユースケース 1：ユーザープロフィール画像

ユーザーがアップロードする画像には、直接アップロードのパターンを使用します。

// Backend: Generate upload URL
const response = await fetch(
  `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/images/v2/direct_upload`,
  { method: 'POST', headers: { 'Authorization': `Bearer ${API_TOKEN}` } }
);
const { result } = await response.json();
return Response.json({ uploadURL: result.uploadURL });

// Frontend: Upload file
const formData = new FormData();
formData.append('file', file);
await fetch(uploadURL, { method: 'POST', body: formData });

完全な例については、templates/direct-creator-upload-backend.ts を読み込んでください。
動作する完全なプロジェクトについては、examples/basic-upload/ を参照してください。

ユースケース 2：レスポンシブ画像

最適なパフォーマンスを実現する、srcset を使ったレスポンシブ画像：

<img
  srcset="
    https://imagedelivery.net/abc/xyz/width=400 400w,
    https://imagedelivery.net/abc/xyz/width=800 800w,
    https://imagedelivery.net/abc/xyz/width=1200 1200w
  "
  sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
  src="https://imagedelivery.net/abc/xyz/width=800"
/>

完全な例については、templates/responsive-images-srcset.html を読み込んでください。 動作する完全なプロジェクトについては、examples/responsive-gallery/ をご覧ください。

その他のユースケース：

• 既存の画像を変換する：references/transformation-options.md を読み込んでください
• プライベート画像：references/signed-urls-guide.md を読み込むか、examples/private-images/ をご覧ください
• 一括アップロード：templates/batch-upload.ts を読み込んでください
• フレームワークとの統合：Next.js、Remix、Astro については references/framework-integration.md を読み込んでください
• ウォーターマーク：references/overlays-watermarks.md と templates/overlay-watermark.ts を読み込んでください
• カスタムドメイン：references/custom-domains.md を読み込んでください
• Webhooks：references/webhooks-guide.md と templates/webhook-handler.ts を読み込んでください

---

防止できる主な 2 つのエラー

エラー 1：ダイレクトアップロードでの CORS の問題

問題： ブラウザーが、自分のドメインからのダイレクトアップロードをブロックします。

解決策： アップロード URL の生成時に CORS ヘッダーを設定します。

const response = await fetch(
  `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/images/v2/direct_upload`,
  {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_TOKEN}` },
    body: JSON.stringify({
      requireSignedURLs: false,
      metadata: { source: 'user-upload' }
    })
  }
);

エラー 2：マルチパートフォームデータのエンコード

問題： ファイルのアップロードでは JSON エンコードが失敗します（multipart/form-data を使う必要があります）。

解決策：

// ✅ CORRECT
const formData = new FormData();
formData.append('file', file);
await fetch(uploadURL, { method: 'POST', body: formData });

// ❌ WRONG
const json = JSON.stringify({ file: base64File });

その他のよくあるエラー：

• エラー 9401（変換が有効になっていない）：references/top-errors.md を読み込んでください
• エラー 9403（無効な変換）：references/top-errors.md を読み込んでください
• エラー 9413（バリアント数の上限超過）：references/top-errors.md を読み込んでください
• エラー 5408（アップロードのタイムアウト）：references/top-errors.md を読み込んでください
• requireSignedURLs の不足：references/signed-urls-guide.md を読み込んでください

10 件すべてのエラーと完全な解決策については、references/top-errors.md を読み込んでください。

---

リファレンスを読み込むタイミング

コアリファレンス

次の場合は references/setup-guide.md を読み込んでください：

• Cloudflare Images を初めてセットアップするとき
• 手順を追ったガイドが必要なとき

次の場合は references/api-reference.md を読み込んでください：

• API ドキュメント一式が必要なとき
• すべてのエンドポイントとパラメーターを確認するとき

次の場合は references/top-errors.md を読み込んでください：

• エラーコード（5408、9401～9413）が発生したとき
• アップロードや変換の問題をトラブルシューティングするとき

アップロード関連リファレンス

次の場合は references/direct-upload-complete-workflow.md を読み込んでください：

• ユーザーによるアップロードを実装するとき
• フロントエンドとバックエンドの例が必要なとき
• CORS を設定するとき

次の場合は references/signed-urls-guide.md を読み込んでください：

• アクセス制御付きのプライベート画像を実装するとき
• HMAC-SHA256 署名の生成が必要なとき

次の場合は references/webhooks-guide.md を読み込んでください：

• アップロード完了イベントを処理するとき
• 署名検証付きの Webhook ハンドラーを実装するとき

変換関連リファレンス

次の場合は references/transformation-options.md を読み込んでください：

• 変換リファレンス一式が必要なとき
• fit／format／effect のすべてのオプションを確認するとき

次の場合は references/format-optimization.md を読み込んでください：

• フォーマットの選択（WebP／AVIF）を最適化するとき
• 品質とサイズのトレードオフを確認するとき

次の場合は references/polish-compression.md を読み込んでください：

• Lossless／Lossy／WebP 圧縮モードの詳細が必要なとき
• メタデータの処理（EXIF の削除）を確認するとき

次の場合は references/overlays-watermarks.md を読み込んでください：

• テキストやロゴのウォーターマークを追加するとき
• ブランディングや著作権保護を実装するとき

高度な機能

次の場合は references/variants-guide.md を読み込んでください：

• バリアントを作成・管理するとき（上限は 100）
• 柔軟なバリアントと名前付きバリアントの違いを確認するとき

次の場合は references/responsive-images-patterns.md を読み込んでください：

• srcset を使ったレスポンシブ画像を構築するとき
• アートディレクションのために picture 要素を実装するとき

次の場合は references/framework-integration.md を読み込んでください：

• Next.js、Remix、Astro、SvelteKit と統合するとき
• フレームワーク固有のパターンやローダーが必要なとき

次の場合は references/custom-domains.md を読み込んでください：

• ブランド化されたドメインから画像を配信するとき
• CNAME の設定や SSL のセットアップを行うとき

次の場合は references/content-credentials.md を読み込んでください：

• EXIF／IPTC メタデータを保持するとき
• 信頼性を証明するために C2PA Content Credentials を実装するとき

次の場合は references/sourcing-kit.md を読み込んでください：

• Cloudinary、Imgix、S3 から移行するとき
• 外部 CDN から一括インポートするとき

---

同梱リソースの使用

参考資料（16 ファイル）

コア: setup-guide.md、api-reference.md、top-errors.md

アップロード: direct-upload-complete-workflow.md、signed-urls-guide.md、webhooks-guide.md

変換: transformation-options.md、format-optimization.md、polish-compression.md、overlays-watermarks.md

応用: variants-guide.md、responsive-images-patterns.md、framework-integration.md、custom-domains.md、content-credentials.md、sourcing-kit.md

テンプレート（16 ファイル）

アップロード: upload-api-basic.ts、upload-via-url.ts、direct-creator-upload-backend.ts、direct-creator-upload-frontend.html、batch-upload.ts

変換: transform-via-url.ts、transform-via-workers.ts、overlay-watermark.ts

バリアント: variants-management.ts、signed-urls-generation.ts、responsive-images-srcset.html

統合: nextjs-integration.tsx、remix-integration.tsx、webhook-handler.ts

設定: wrangler-images-binding.jsonc、package.json

エージェント（3 つの自律型エージェント）

• troubleshooting-agent - アップロード／変換エラーを診断します（5408、9401-9413）
• upload-workflow-agent - アップロード実装全体を案内します（フロントエンド + バックエンド）
• optimization-agent - 画像の最適化戦略を提案します

使用方法: /agent <agent-name> を実行するか、関連する場合は Claude に自動検出させます

コマンド（3 つのスラッシュコマンド）

• /check-images - API の簡易ヘルスチェックと設定の検証
• /validate-config - wrangler.jsonc のバインディングと設定を検証
• /generate-variant - 対話型のバリアントジェネレーター

使用方法: /<command-name>

例（3 つの完全な動作プロジェクト）

• basic-upload/ - Hono + Workers を使った最小限のアップロード実装
• responsive-gallery/ - srcset と遅延読み込みを使ったレスポンシブ画像ギャラリー
• private-images/ - 有効期限とアクセス制御を設定した署名付き URL

クローンして実行: cd examples/<example-name> && npm install && npm run dev

アーキテクチャ図（3 点）

• direct-upload-workflow.md - クリエイターによる直接アップロードフローのシーケンス図
• transformation-pipeline.md - 変換処理を示すフローチャート
• variants-structure.md - 名前付きバリアントと柔軟なバリアントの比較

表示場所: assets/diagrams/

ユーティリティスクリプト（5 本）

• test-upload.sh - サンプル画像のアップロードで API 接続をテストします
• generate-signed-url.sh - 有効期限付き署名 URL を生成する CLI ツール
• validate-variants.sh - すべてのバリアントを一覧表示し、バリアント数（最大 100）を確認します
• analyze-usage.sh - API に問い合わせてストレージ使用量と推定コストを確認します
• check-versions.sh - パッケージのバージョンが最新であることを確認します

実行方法: ./scripts/<script-name>.sh（.env に CF_ACCOUNT_ID と CF_API_TOKEN が必要です）

---

料金

Images API: 保存 10 万件あたり $5、配信 10 万件あたり $1
変換: 1,000 件あたり $0.50（ゾーンごとに月 10 万件まで無料）
直接アップロード: API 料金に含まれます

---

公式ドキュメント

• Images の概要: https://developers.cloudflare.com/images/
• アップロード API: https://developers.cloudflare.com/images/upload-images/
• 変換: https://developers.cloudflare.com/images/transform-images/
• クリエイターによる直接アップロード: https://developers.cloudflare.com/images/upload-images/direct-creator-upload/
• バリアント: https://developers.cloudflare.com/images/manage-images/create-variants/