Cloudflare Images 图像托管与转换 API 使用指南 | 支持 AI 人脸裁剪与内容凭证

cloudflare-images by jezweb/claude-skills

328 周安装量

661 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/jezweb/claude-skills --skill cloudflare-images

云服务性能优化 API

🇨🇳中文介绍

Cloudflare Images

状态 : 生产就绪 ✅ 最后更新 : 2026-01-21 依赖项 : 已启用 Images 的 Cloudflare 账户 最新版本 : Cloudflare Images API v2, @cloudflare/workers-types@4.20260108.0

近期更新 (2025) :

2025年2月 : 内容凭证支持 (C2PA 标准) - 保留图像来源链，自动对转换进行加密签名
2025年8月 : AI 人脸裁剪正式发布 (gravity=face 配合 zoom 控制，基于 GPU 的 RetinaFace，99.4% 精确度)
2025年5月 : 媒体转换源站限制 (默认: 仅限同域，可通过仪表板配置)
即将推出 : 背景移除，生成式放大 (计划功能)

弃用通知 : Mirage 已于 2025年9月15日弃用。请迁移至 Cloudflare Images 进行存储/转换，或使用原生的 <img loading="lazy"> 实现延迟加载。

概述

两大功能：Images API (上传/存储及变体) 和 Image Transformations (通过 URL 或 Workers 调整任何图像大小)。

快速开始

1. 启用 : 仪表板 → Images → 获取账户 ID + API 令牌 (Cloudflare Images: Edit 权限)

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

问题 #1: 直接创作者上传 CORS 错误

错误 : Access to XMLHttpRequest blocked by CORS policy: Request header field content-type is not allowed

发生原因 : 服务器 CORS 设置仅允许 multipart/form-data 作为 Content-Type 请求头

// ✅ 正确
const formData = new FormData();
formData.append('file', fileInput.files[0]);
await fetch(uploadURL, {
  method: 'POST',
  body: formData // 浏览器自动设置 multipart/form-data
});

// ❌ 错误
await fetch(uploadURL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' }, // CORS 错误
  body: JSON.stringify({ file: base64Image })
});

问题 #2: 错误 5408 - 上传超时

错误 : 上传约 15 秒后出现 Error 5408

发生原因 : Cloudflare 有 30 秒的请求超时限制；上传速度慢或文件过大超过限制

上传前压缩图像 (使用 Canvas API 在客户端进行)
使用合理的文件大小限制 (例如，最大 10MB)
向用户显示上传进度
优雅地处理超时错误

const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB

if (file.size > MAX_FILE_SIZE) { alert('文件过大。请选择小于 10MB 的图像。'); return; }

问题 #3: 错误 400 - 无效的文件参数

错误 : 400 Bad Request 并附带无用的错误信息

发生原因 : 文件字段必须命名为 file (而不是 image、photo 等)

// ✅ 正确
formData.append('file', imageFile);

// ❌ 错误
formData.append('image', imageFile); // 400 错误
formData.append('photo', imageFile); // 400 错误

问题 #4: CORS 预检请求失败

错误 : 预检 OPTIONS 请求被阻止

发生原因 : 直接从浏览器调用 /direct_upload API (应仅从后端调用)

架构:
浏览器 → 后端 API → POST /direct_upload → 返回 uploadURL → 浏览器上传到 uploadURL

切勿将 API 令牌暴露给浏览器。在后端生成上传 URL，返回给前端。

问题 #5: 错误 9401 - 无效参数

错误 : Cf-Resized: err=9401 - 缺少必需的 cf.image 选项或选项无效

发生原因 : 缺少必需的转换参数或参数值无效

// ✅ 正确
fetch(imageURL, {
  cf: {
    image: {
      width: 800,
      quality: 85,
      format: 'auto'
    }
  }
});

// ❌ 错误
fetch(imageURL, {
  cf: {
    image: {
      width: 'large', // 必须是数字
      quality: 150 // 最大 100
    }
  }
});

问题 #6: 错误 9402 - 图像过大

错误 : Cf-Resized: err=9402 - 图像过大或连接中断

发生原因 : 图像超过最大面积 (100 兆像素) 或下载失败

转换前验证图像尺寸
使用合理的源图像 (最大 10000x10000px)
优雅地处理网络错误

问题 #7: 错误 9403 - 请求循环

错误 : Cf-Resized: err=9403 - Worker 获取自己的 URL 或已调整大小的图像

发生原因 : 对已转换的图像应用转换，或 Worker 获取自身

// ✅ 正确
if (url.pathname.startsWith('/images/')) {
  const originalPath = url.pathname.replace('/images/', '');
  const originURL = `https://storage.example.com/${originalPath}`;
  return fetch(originURL, { cf: { image: { width: 800 } } });
}

// ❌ 错误
if (url.pathname.startsWith('/images/')) {
  // 获取 Worker 自身的 URL，导致循环
  return fetch(request, { cf: { image: { width: 800 } } });
}

问题 #8: 错误 9406/9419 - 无效的 URL 格式

错误 : Cf-Resized: err=9406 或 err=9419 - 非 HTTPS URL 或 URL 包含空格/未转义的 Unicode 字符

发生原因 : 图像 URL 使用 HTTP (而不是 HTTPS) 或包含无效字符

// ✅ 正确
const imageURL = "https://example.com/images/photo%20name.jpg";

// ❌ 错误
const imageURL = "http://example.com/images/photo.jpg"; // 不允许 HTTP
const imageURL = "https://example.com/images/photo name.jpg"; // 空格未编码

始终对 URL 路径使用 encodeURIComponent():

const filename = "photo name.jpg";
const imageURL = `https://example.com/images/${encodeURIComponent(filename)}`;

问题 #9: 错误 9412 - 非图像响应

错误 : Cf-Resized: err=9412 - 源站返回 HTML 而不是图像

发生原因 : 源服务器返回 404 页面或错误页面 (HTML) 而不是图像

// 转换前验证 URL
const originResponse = await fetch(imageURL, { method: 'HEAD' });
const contentType = originResponse.headers.get('content-type');

if (!contentType?.startsWith('image/')) {
  return new Response('不是图像', { status: 400 });
}

return fetch(imageURL, { cf: { image: { width: 800 } } });

问题 #10: 错误 9413 - 超过最大图像面积

错误 : Cf-Resized: err=9413 - 图像超过 100 兆像素

发生原因 : 源图像尺寸超过 100 兆像素 (例如，10000x10000px)

上传前验证图像尺寸
预处理过大的图像
拒绝超过阈值的图像

const MAX_MEGAPIXELS = 100;

if (width * height > MAX_MEGAPIXELS * 1_000_000) { return new Response('图像过大', { status: 413 }); }

问题 #11: 灵活变体 + 签名 URL 不兼容

错误 : 灵活变体不适用于私有图像

发生原因 : 灵活变体不能与 requireSignedURLs=true 一起使用

// ✅ 正确 - 为私有图像使用命名变体
await uploadImage({
  file: imageFile,
  requireSignedURLs: true // 使用命名变体: /public, /avatar 等
});

// ❌ 错误 - 灵活变体不支持签名 URL
// 不能使用: /w=400,sharpen=3 配合 requireSignedURLs=true

问题 #12: SVG 调整大小限制

错误 : SVG 文件无法通过转换调整大小

发生原因 : SVG 本质上是可缩放的 (矢量格式)，调整大小不适用

// SVG 可以被提供但无法调整大小
// 使用任何变体名称作为占位符
// https://imagedelivery.net/<HASH>/<SVG_ID>/public

// SVG 将以原始大小提供，无论变体设置如何

问题 #13: 格式剥离 EXIF 元数据

错误 : 上传的图像中移除了 GPS 数据、相机设置

发生原因 : 默认行为会剥离除版权信息外的所有元数据。关键点 : WebP 和 PNG 输出格式总是丢弃元数据，无论设置如何 - 只有 JPEG 支持保留元数据。

// ✅ 正确 - JPEG 保留元数据
fetch(imageURL, {
  cf: {
    image: {
      width: 800,
      format: 'jpeg', // 或 'auto' (可能变为 jpeg)
      metadata: 'keep' // 保留大多数 EXIF 元数据，包括 GPS
    }
  }
});

// ❌ 错误 - WebP/PNG 忽略元数据设置
fetch(imageURL, {
  cf: {
    image: {
      format: 'webp',
      metadata: 'keep' // 无效 - WebP/PNG 总是剥离元数据
    }
  }
});

元数据选项 (仅限 JPEG):

none: 剥离所有元数据
copyright: 仅保留版权标签 (JPEG 的默认值)
keep: 保留大多数 EXIF 元数据，包括 GPS

✅ JPEG: 所有元数据选项都有效
❌ WebP: 总是剥离元数据 (等同于 none)
❌ PNG: 总是剥离元数据 (等同于 none)

问题 #14: AVIF 分辨率限制模糊性

错误 : 大型 AVIF 转换失败或降级到较低分辨率

发生原因 : 官方文档说明 format=avif 的硬限制为 1,600px，但社区报告指出，截至 2024 年底，最长边的实际限制为 1200px。注意 : 官方文档 (1600px) 与报告行为 (1200px) 之间的差异需要验证。

// ✅ 推荐 - 使用 format=auto 而不是显式的 avif
fetch(imageURL, {
  cf: {
    image: {
      width: 2000,
      format: 'auto' // Cloudflare 选择最佳格式
    }
  }
});

// ⚠️ 可能失败 - 显式 AVIF 配合大尺寸
fetch(imageURL, {
  cf: {
    image: {
      width: 2000,
      format: 'avif' // 如果 >1200px 可能失败
    }
  }
});

// ✅ 变通方案 - 为较大图像使用 WebP
if (width > 1200) {
  format = 'webp'; // WebP 支持更大尺寸
} else {
  format = 'avif'; // 为较小图像使用 AVIF
}

问题 #15: 按设备类型缓存图像 (社区报告)

错误 : 桌面端和移动端看到不同的缓存版本，意外的缓存未命中

发生原因 : 图像会按设备类型意外缓存，且在缓存规则中没有配置选项可以禁用此行为。截至 2024 年 12 月，多名用户确认了此行为。

了解清除缓存需要为每种设备类型分别清除
通过 Cloudflare 仪表板按设备类型手动清除缓存
在缓存失效策略中考虑设备特定的缓存

解决方案/变通方案 : 需要时通过 Cloudflare 仪表板按设备类型手动清除缓存。

问题 #16: PNG 默认不缓存

错误 : PNG 图像不缓存，而其他图像格式正常工作

发生原因 : Cloudflare 默认缓存的文件扩展名不包含 .png。默认缓存的扩展名: .jpg, .jpeg, .gif, .webp, .bmp, .ico, .svg, .tif, .tiff (缺少 PNG)。

预防措施 : 为 PNG 文件创建显式缓存规则:

仪表板 → Caching → Cache Rules
添加规则: URI Path ends with .png → Cache Everything

可直接复制粘贴的常见模式代码:

wrangler-images-binding.jsonc - Wrangler 配置 (无需绑定)
upload-api-basic.ts - 上传文件到 Images API
upload-via-url.ts - 从外部 URL 导入图像
direct-creator-upload-backend.ts - 生成一次性上传 URL
direct-creator-upload-frontend.html - 用户上传表单
transform-via-url.ts - URL 转换示例
transform-via-workers.ts - Workers 转换模式
variants-management.ts - 创建/列出/删除变体
signed-urls-generation.ts - HMAC-SHA256 签名 URL 生成
responsive-images-srcset.html - 响应式图像模式
batch-upload.ts - 用于高容量上传的批量 API

cp templates/upload-api-basic.ts src/upload.ts
# 使用你的账户 ID 和 API 令牌进行编辑

参考资料 (references/)

Claude 可根据需要加载的深入文档:

api-reference.md - 完整的 API 端点 (上传、列出、删除、变体)
transformation-options.md - 所有转换参数及示例
variants-guide.md - 命名变体与灵活变体，各自使用时机
signed-urls-guide.md - HMAC-SHA256 实现细节
direct-upload-complete-workflow.md - 完整架构和流程
responsive-images-patterns.md - srcset、sizes、艺术指导
format-optimization.md - WebP/AVIF 自动转换策略
top-errors.md - 所有 13+ 个错误及详细故障排除

深入研究特定功能
故障排除复杂问题
理解 API 细节
实现高级模式

check-versions.sh - 验证 API 端点是否为最新

自定义域名 : 通过 /cdn-cgi/imagedelivery/<HASH>/<ID>/<VARIANT> 从你的域名提供服务 (要求域名在 Cloudflare 上，且已代理)。使用转换规则实现自定义路径。

批量 API : 通过 batch.imagedelivery.net 使用批量令牌进行高容量上传 (仪表板 → Images → Batch API)

Webhooks : 直接创作者上传的通知 (仪表板 → Notifications → Webhooks)。负载包含 imageId、status、metadata。

内容凭证 (C2PA) : Cloudflare Images 保留并签署图像来源链。当转换包含内容凭证的图像时，Cloudflare 会自动将转换附加到清单中，并使用 DigiCert 证书进行加密签名。通过仪表板 → Images → Transformations → Preserve Content Credentials 启用。注意 : 仅当源图像已包含 C2PA 元数据时有效 (某些相机、DALL-E、兼容的编辑软件)。请在 contentcredentials.org/verify 验证。

浏览器缓存 TTL : 默认浏览器缓存 TTL 为 2 天 (172,800 秒)。可从 1 小时到 1 年自定义 (账户级别或按变体)。重要 : 私有图像 (签名 URL) 不遵守 TTL 设置。当使用相同的自定义 ID 重新上传图像时，可能会导致问题 - 用户可能最多看到旧版本 2 天。解决方案: 使用唯一的图像 ID (附加时间戳/哈希) 或在重新上传后手动清除缓存。

产品合并迁移 (2023年11月) : Cloudflare 将 Image Resizing 合并到 Images 产品中，采用新的定价: 每月每 1,000 次唯一转换 $0.50 (每 30 天对每个唯一转换计费一次)。迁移注意事项 : 旧的 Image Resizing 基于未缓存的请求计费 (由于缓存行为可变，成本不可预测)。新计费基于"唯一转换" (图像 ID + 参数组合)，而不是请求次数。同一转换每月请求 1,000 次 = 计费一次。现有客户可以继续使用旧版本或自愿迁移。

用于成本优化的 R2 集成 : Cloudflare Images 基于 R2 + Image Resizing 构建。为节省成本，可将原始图像存储在 R2 中，并按需使用 Image Transformations:

将图像上传到 R2 存储桶
通过自定义域名配合 /cdn-cgi/image/ 转换提供服务
不存储变体 (转换是临时的/缓存的)

R2: 10GB 存储 + 无限带宽 (免费套餐)
Cloudflare Images: $5/月 (10万张图像) + 每 10 万次转换 $1
R2 + Transformations: R2 存储 + 每 1,000 次唯一转换 $0.50

使用场景 : 如果不需要命名变体、批量上传或直接创作者上传功能，R2 更具成本效益。

与 R2 配合使用的 Workers 模式示例 :

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const imageKey = url.pathname.replace('/images/', '');
    const originURL = `https://r2-bucket.example.com/${imageKey}`;

    return fetch(originURL, {
      cf: {
        image: {
          width: 800,
          quality: 85,
          format: 'auto'
        }
      }
    });
  }
};

问题: 图像未转换

症状 : /cdn-cgi/image/... 返回原始图像或 404

在区域上启用转换: 仪表板 → Images → Transformations → 为区域启用
验证区域是否通过 Cloudflare 代理 (橙色云)
检查源图像是否可公开访问
等待 5-10 分钟让设置传播

问题: 直接上传返回 CORS 错误

症状 : 浏览器控制台中出现 Access-Control-Allow-Origin 错误

使用 multipart/form-data 编码 (让浏览器设置 Content-Type)
不要从浏览器调用 /direct_upload；从后端调用
将文件字段命名为 file (而不是 image)
移除手动设置的 Content-Type 请求头

问题: Worker 转换返回 9403 循环错误

症状 : 响应头中出现 Cf-Resized: err=9403

不要获取 Worker 自身的 URL (使用外部源站)
不要转换已调整大小的图像
检查 URL 路由逻辑以避免循环

问题: 签名 URL 无效

症状 : 访问签名 URL 时出现 403 Forbidden

验证图像是否使用 requireSignedURLs=true 上传
检查签名生成 (HMAC-SHA256)
确保过期时间戳是未来的时间
验证签名密钥是否与仪表板匹配 (Images → Keys)
不能将灵活变体与签名 URL 一起使用 (请使用命名变体)

问题: 图像已上传但未显示

症状 : 上传返回 200 OK 但仪表板中未显示图像

检查响应中是否有 draft: true (直接创作者上传)
等待上传完成 (通过 GET /images/v1/{id} 检查)
验证账户 ID 是否匹配
检查 webhooks 中的上传错误

问题: 重新上传的图像仍显示旧版本

症状 : 即使用户从未访问过页面，重新上传后仍看到旧图像

为每次上传使用唯一的图像 ID: const imageId = \${baseId}-${Date.now()};
设置较短的 Cache-Control 请求头 (例如，max-age=86400 表示 1 天，而不是 30 天)
使用相同 ID 重新上传后，通过仪表板手动清除缓存
了解默认浏览器缓存 TTL 为 2 天 - 用户可能看到缓存版本

根本原因 : Cloudflare 遵守源站的 Cache-Control 请求头。如果源站设置了较长的 max-age (例如 30 天)，即使使用相同 ID 重新上传，图像仍保持缓存状态。

问题: PNG 图像不缓存

症状 : PNG 图像绕过缓存，而其他格式 (JPEG, WebP) 正确缓存

创建显式缓存规则: 仪表板 → Caching → Cache Rules
添加规则: URI Path ends with .png → Cache Everything
默认缓存的扩展名不包含 .png (仅包含 .jpg, .jpeg, .gif, .webp, .bmp, .ico, .svg, .tif, .tiff)

最后验证 : 2026-01-21 API 版本 : v2 (直接上传), v1 (标准上传) 可选 : @cloudflare/workers-types@4.20260108.0

技能版本 : 2.1.0 | 变更 : 新增 3 个问题 (AVIF 限制、按设备缓存、PNG 缓存)，增强了元数据问题的格式细节，添加了内容凭证、浏览器缓存 TTL、产品合并说明、R2 集成模式、Mirage 弃用通知和缓存故障排除指南。错误数量: 13 → 16。

🇺🇸English

Cloudflare Images

Status : Production Ready ✅ Last Updated : 2026-01-21 Dependencies : Cloudflare account with Images enabled Latest Versions : Cloudflare Images API v2, @cloudflare/workers-types@4.20260108.0

Recent Updates (2025) :

February 2025 : Content Credentials support (C2PA standard) - preserve image provenance chains, automatic cryptographic signing of transformations
August 2025 : AI Face Cropping GA (gravity=face with zoom control, GPU-based RetinaFace, 99.4% precision)
May 2025 : Media Transformations origin restrictions (default: same-domain only, configurable via dashboard)
Upcoming : Background removal, generative upscale (planned features)

Deprecation Notice : Mirage deprecated September 15, 2025. Migrate to Cloudflare Images for storage/transformations or use native <img loading="lazy"> for lazy loading.

Overview

Two features: Images API (upload/store with variants) and Image Transformations (resize any image via URL or Workers).

Quick Start

1. Enable : Dashboard → Images → Get Account ID + API token (Cloudflare Images: Edit permission)

2. Upload :

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

3. Serve : https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/public

4. Transform (optional): Dashboard → Images → Transformations → Enable for zone

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

Upload Methods

1. File Upload : POST to /images/v1 with file (multipart/form-data), optional id, requireSignedURLs, metadata

2. Upload via URL : POST with url=https://example.com/image.jpg (supports HTTP basic auth)

3. Direct Creator Upload (one-time URLs, no API key exposure):

Backend: POST to /images/v2/direct_upload → returns uploadURL Frontend: POST file to uploadURL with FormData

CRITICAL CORS FIX :

✅ Use multipart/form-data (let browser set header)
✅ Name field file (NOT image)
✅ Call /direct_upload from backend only
❌ Don't set Content-Type: application/json
❌ Don't call /direct_upload from browser

Image Transformations

URL : /cdn-cgi/image/<OPTIONS>/<SOURCE>

Sizing: width=800,height=600,fit=cover
Quality: quality=85 (1-100)
Format: format=auto (WebP/AVIF auto-detection)
Cropping : gravity=auto (smart crop), gravity=face (AI face detection, Aug 2025 GA), gravity=center, zoom=0.5 (0-1 range, face crop tightness)
Effects: blur=10,sharpen=3,brightness=1.2
Fit: scale-down, , , ,

Workers : Use cf.image object in fetch

fetch(imageURL, {
  cf: {
    image: { width: 800, quality: 85, format: 'auto', gravity: 'face', zoom: 0.8 }
  }
});

Variants

Named Variants (up to 100): Predefined transformations (e.g., avatar, thumbnail)

Create: POST to /images/v1/variants with id, options
Use: imagedelivery.net/<HASH>/<ID>/avatar
Works with signed URLs

Flexible Variants : Dynamic params in URL (w=400,sharpen=3)

Enable: PATCH /images/v1/config with {"flexible_variants": true}
❌ Cannot use with signed URLs (use named variants instead)

Signed URLs

Generate HMAC-SHA256 tokens for private images (URL format: ?exp=<TIMESTAMP>&sig=<HMAC>).

Algorithm : HMAC-SHA256(signingKey, imageId + variant + expiry) → hex signature

See : templates/signed-urls-generation.ts for Workers implementation

Critical Rules

Always Do

✅ Use multipart/form-data for Direct Creator Upload ✅ Name the file field file (not image or other names) ✅ Call /direct_upload API from backend only (NOT browser) ✅ Use HTTPS URLs for transformations (HTTP not supported) ✅ URL-encode special characters in image paths ✅ Enable transformations on zone before using /cdn-cgi/image/ ✅ Use named variants for private images (signed URLs) ✅ Check Cf-Resized header for transformation errors ✅ Set format=auto for automatic WebP/AVIF conversion ✅ Use fit=scale-down to prevent unwanted enlargement

Never Do

❌ Use application/json Content-Type for file uploads ❌ Call /direct_upload from browser (CORS will fail) ❌ Use flexible variants with requireSignedURLs=true ❌ Resize SVG files (they're inherently scalable) ❌ Use HTTP URLs for transformations (HTTPS only) ❌ Put spaces or unescaped Unicode in URLs ❌ Transform the same image multiple times in Workers (causes 9403 loop) ❌ Exceed 100 megapixels image size ❌ Use /cdn-cgi/image/ endpoint in Workers (use cf.image instead) ❌ Forget to enable transformations on zone before use

Known Issues Prevention

This skill prevents 16 documented issues.

Issue #1: Direct Creator Upload CORS Error

Error : Access to XMLHttpRequest blocked by CORS policy: Request header field content-type is not allowed

Source : Cloudflare Community #345739, #368114

Why It Happens : Server CORS settings only allow multipart/form-data for Content-Type header

Prevention :

// ✅ CORRECT
const formData = new FormData();
formData.append('file', fileInput.files[0]);
await fetch(uploadURL, {
  method: 'POST',
  body: formData // Browser sets multipart/form-data automatically
});

// ❌ WRONG
await fetch(uploadURL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' }, // CORS error
  body: JSON.stringify({ file: base64Image })
});

Issue #2: Error 5408 - Upload Timeout

Error : Error 5408 after ~15 seconds of upload

Source : Cloudflare Community #571336

Why It Happens : Cloudflare has 30-second request timeout; slow uploads or large files exceed limit

Prevention :

Compress images before upload (client-side with Canvas API)
Use reasonable file size limits (e.g., max 10MB)
Show upload progress to user
Handle timeout errors gracefully

const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB

if (file.size > MAX_FILE_SIZE) { alert('File too large. Please select an image under 10MB.'); return; }

Issue #3: Error 400 - Invalid File Parameter

Error : 400 Bad Request with unhelpful error message

Source : Cloudflare Community #487629

Why It Happens : File field must be named file (not image, photo, etc.)

Prevention :

// ✅ CORRECT
formData.append('file', imageFile);

// ❌ WRONG
formData.append('image', imageFile); // 400 error
formData.append('photo', imageFile); // 400 error

Issue #4: CORS Preflight Failures

Error : Preflight OPTIONS request blocked

Source : Cloudflare Community #306805

Why It Happens : Calling /direct_upload API directly from browser (should be backend-only)

Prevention :

ARCHITECTURE:
Browser → Backend API → POST /direct_upload → Returns uploadURL → Browser uploads to uploadURL

Never expose API token to browser. Generate upload URL on backend, return to frontend.

Issue #5: Error 9401 - Invalid Arguments

Error : Cf-Resized: err=9401 - Required cf.image options missing or invalid

Source : Cloudflare Images Docs - Troubleshooting

Why It Happens : Missing required transformation parameters or invalid values

Prevention :

// ✅ CORRECT
fetch(imageURL, {
  cf: {
    image: {
      width: 800,
      quality: 85,
      format: 'auto'
    }
  }
});

// ❌ WRONG
fetch(imageURL, {
  cf: {
    image: {
      width: 'large', // Must be number
      quality: 150 // Max 100
    }
  }
});

Issue #6: Error 9402 - Image Too Large

Error : Cf-Resized: err=9402 - Image too large or connection interrupted

Source : Cloudflare Images Docs - Troubleshooting

Why It Happens : Image exceeds maximum area (100 megapixels) or download fails

Prevention :

Validate image dimensions before transforming
Use reasonable source images (max 10000x10000px)
Handle network errors gracefully

Issue #7: Error 9403 - Request Loop

Error : Cf-Resized: err=9403 - Worker fetching its own URL or already-resized image

Source : Cloudflare Images Docs - Troubleshooting

Why It Happens : Transformation applied to already-transformed image, or Worker fetches itself

Prevention :

// ✅ CORRECT
if (url.pathname.startsWith('/images/')) {
  const originalPath = url.pathname.replace('/images/', '');
  const originURL = `https://storage.example.com/${originalPath}`;
  return fetch(originURL, { cf: { image: { width: 800 } } });
}

// ❌ WRONG
if (url.pathname.startsWith('/images/')) {
  // Fetches worker's own URL, causes loop
  return fetch(request, { cf: { image: { width: 800 } } });
}

Issue #8: Error 9406/9419 - Invalid URL Format

Error : Cf-Resized: err=9406 or err=9419 - Non-HTTPS URL or URL has spaces/unescaped Unicode

Source : Cloudflare Images Docs - Troubleshooting

Why It Happens : Image URL uses HTTP (not HTTPS) or contains invalid characters

Prevention :

// ✅ CORRECT
const imageURL = "https://example.com/images/photo%20name.jpg";

// ❌ WRONG
const imageURL = "http://example.com/images/photo.jpg"; // HTTP not allowed
const imageURL = "https://example.com/images/photo name.jpg"; // Space not encoded

Always use encodeURIComponent() for URL paths:

const filename = "photo name.jpg";
const imageURL = `https://example.com/images/${encodeURIComponent(filename)}`;

Issue #9: Error 9412 - Non-Image Response

Error : Cf-Resized: err=9412 - Origin returned HTML instead of image

Source : Cloudflare Images Docs - Troubleshooting

Why It Happens : Origin server returns 404 page or error page (HTML) instead of image

Prevention :

// Verify URL before transforming
const originResponse = await fetch(imageURL, { method: 'HEAD' });
const contentType = originResponse.headers.get('content-type');

if (!contentType?.startsWith('image/')) {
  return new Response('Not an image', { status: 400 });
}

return fetch(imageURL, { cf: { image: { width: 800 } } });

Issue #10: Error 9413 - Max Image Area Exceeded

Error : Cf-Resized: err=9413 - Image exceeds 100 megapixels

Source : Cloudflare Images Docs - Troubleshooting

Why It Happens : Source image dimensions exceed 100 megapixels (e.g., 10000x10000px)

Prevention :

Validate image dimensions before upload
Pre-process oversized images
Reject images above threshold

const MAX_MEGAPIXELS = 100;

if (width * height > MAX_MEGAPIXELS * 1_000_000) { return new Response('Image too large', { status: 413 }); }

Issue #11: Flexible Variants + Signed URLs Incompatibility

Error : Flexible variants don't work with private images

Source : Cloudflare Images Docs - Enable flexible variants

Why It Happens : Flexible variants cannot be used with requireSignedURLs=true

Prevention :

// ✅ CORRECT - Use named variants for private images
await uploadImage({
  file: imageFile,
  requireSignedURLs: true // Use named variants: /public, /avatar, etc.
});

// ❌ WRONG - Flexible variants don't support signed URLs
// Cannot use: /w=400,sharpen=3 with requireSignedURLs=true

Issue #12: SVG Resizing Limitation

Error : SVG files don't resize via transformations

Source : Cloudflare Images Docs - SVG files

Why It Happens : SVG is inherently scalable (vector format), resizing not applicable

Prevention :

// SVGs can be served but not resized
// Use any variant name as placeholder
// https://imagedelivery.net/<HASH>/<SVG_ID>/public

// SVG will be served at original size regardless of variant settings

Issue #13: EXIF Metadata Stripped by Format

Error : GPS data, camera settings removed from uploaded images

Source : Cloudflare Images Docs - Transform via URL

Why It Happens : Default behavior strips all metadata except copyright. CRITICAL : WebP and PNG output formats ALWAYS discard metadata regardless of settings - only JPEG supports metadata preservation.

Prevention :

// ✅ CORRECT - JPEG preserves metadata
fetch(imageURL, {
  cf: {
    image: {
      width: 800,
      format: 'jpeg', // or 'auto' (may become jpeg)
      metadata: 'keep' // Preserves most EXIF including GPS
    }
  }
});

// ❌ WRONG - WebP/PNG ignore metadata setting
fetch(imageURL, {
  cf: {
    image: {
      format: 'webp',
      metadata: 'keep' // NO EFFECT - always stripped for WebP/PNG
    }
  }
});

Metadata Options (JPEG only):

none: Strip all metadata
copyright: Keep only copyright tag (default for JPEG)
keep: Preserve most EXIF metadata including GPS

Format Support :

✅ JPEG: All metadata options work
❌ WebP: Always strips metadata (acts as none)
❌ PNG: Always strips metadata (acts as none)

Issue #14: AVIF Resolution Limit Ambiguity

Error : Large AVIF transformations fail or degrade to lower resolution

Source : Cloudflare Docs + Community Report

Why It Happens : Official docs state 1,600px hard limit for format=avif, but community reports indicate practical limit of 1200px for longest side as of late 2024. Note : Discrepancy between official docs (1600px) and reported behavior (1200px) needs verification.

Prevention :

// ✅ RECOMMENDED - Use format=auto instead of explicit avif
fetch(imageURL, {
  cf: {
    image: {
      width: 2000,
      format: 'auto' // Cloudflare chooses best format
    }
  }
});

// ⚠️ MAY FAIL - Explicit AVIF with large dimensions
fetch(imageURL, {
  cf: {
    image: {
      width: 2000,
      format: 'avif' // May fail if >1200px
    }
  }
});

// ✅ WORKAROUND - Use WebP for larger images
if (width > 1200) {
  format = 'webp'; // WebP supports larger dimensions
} else {
  format = 'avif'; // AVIF for smaller images
}

Issue #15: Image Cache by Device Type (Community-reported)

Error : Desktop and mobile see different cached versions, unexpected cache misses

Source : Cloudflare Community

Why It Happens : Images are cached by device type unexpectedly with no configuration option to disable this behavior in cache rules. Multiple users confirm this behavior as of Dec 2024.

Prevention :

Understand that purging cache requires purging for each device type
Use manual cache purging per device type via Cloudflare dashboard
Account for device-specific caching in cache invalidation strategies

Solution/Workaround : Manual cache purging per device type via Cloudflare dashboard when needed.

Issue #16: PNG Not Cached by Default

Error : PNG images not caching despite other image formats working

Source : Cloudflare Community

Why It Happens : Default file extensions cached by Cloudflare do NOT include .png. Default cached extensions: .jpg, .jpeg, .gif, .webp, .bmp, .ico, .svg, .tif, .tiff (PNG is missing).

Prevention : Create explicit cache rule for PNG files:

Dashboard → Caching → Cache Rules
Add rule: URI Path ends with .png → Cache Everything

Using Bundled Resources

Templates (templates/)

Copy-paste ready code for common patterns:

wrangler-images-binding.jsonc - Wrangler configuration (no binding needed)
upload-api-basic.ts - Upload file to Images API
upload-via-url.ts - Ingest image from external URL
direct-creator-upload-backend.ts - Generate one-time upload URLs
direct-creator-upload-frontend.html - User upload form
transform-via-url.ts - URL transformation examples
transform-via-workers.ts - Workers transformation patterns
variants-management.ts - Create/list/delete variants
signed-urls-generation.ts - HMAC-SHA256 signed URL generation
responsive-images-srcset.html - Responsive image patterns
batch-upload.ts - Batch API for high-volume uploads

Usage :

cp templates/upload-api-basic.ts src/upload.ts
# Edit with your account ID and API token

References (references/)

In-depth documentation Claude can load as needed:

api-reference.md - Complete API endpoints (upload, list, delete, variants)
transformation-options.md - All transform params with examples
variants-guide.md - Named vs flexible variants, when to use each
signed-urls-guide.md - HMAC-SHA256 implementation details
direct-upload-complete-workflow.md - Full architecture and flow
responsive-images-patterns.md - srcset, sizes, art direction
format-optimization.md - WebP/AVIF auto-conversion strategies
top-errors.md - All 13+ errors with detailed troubleshooting

When to load :

Deep-dive into specific feature
Troubleshooting complex issues
Understanding API details
Implementing advanced patterns

Scripts (scripts/)

check-versions.sh - Verify API endpoints are current

Advanced Topics

Custom Domains : Serve from your domain via /cdn-cgi/imagedelivery/<HASH>/<ID>/<VARIANT> (requires domain on Cloudflare, proxied). Use Transform Rules for custom paths.

Batch API : High-volume uploads via batch.imagedelivery.net with batch tokens (Dashboard → Images → Batch API)

Webhooks : Notifications for Direct Creator Upload (Dashboard → Notifications → Webhooks). Payload includes imageId, status, metadata.

Content Credentials (C2PA) : Cloudflare Images preserves and signs image provenance chains. When transforming images with Content Credentials, Cloudflare automatically appends transformations to the manifest and cryptographically signs them using DigiCert certificates. Enable via Dashboard → Images → Transformations → Preserve Content Credentials. Note : Only works if source images already contain C2PA metadata (certain cameras, DALL-E, compatible editing software). Verify at contentcredentials.org/verify.

Browser Cache TTL : Default Browser Cache TTL is 2 days (172,800 seconds). Customizable from 1 hour to 1 year (account-level or per-variant). Important : Private images (signed URLs) do NOT respect TTL settings. Can cause issues when re-uploading images with same Custom ID - users may see old version for up to 2 days. Solution: Use unique image IDs (append timestamp/hash) or manually purge cache after re-upload.

Product Merge Migration (Nov 2023) : Cloudflare merged Image Resizing into Images product with new pricing: $0.50 per 1,000 unique transformations monthly (billing once per 30 days per unique transformation). Migration Gotchas : Old Image Resizing bills based on uncached requests (unpredictable costs due to variable cache behavior). New billing is per "unique transformation" (image ID + params combination), not request count. Same transformation requested 1,000 times/month = billed once. Existing customers can continue using legacy version or migrate voluntarily.

R2 Integration for Cost Optimization : Cloudflare Images is built on R2 + Image Resizing. For cost savings, store original images in R2 and use Image Transformations on-demand:

Upload images to R2 bucket
Serve via custom domain with /cdn-cgi/image/ transformations
No variants stored (transformations are ephemeral/cached)

Cost Comparison :

R2: 10GB storage + unlimited bandwidth (free tier)
Cloudflare Images: $5/month (100k images) + $1 per 100k transformations
R2 + Transformations: R2 storage + $0.50 per 1k unique transformations

Use Case : If you don't need named variants, batch uploads, or Direct Creator Upload features, R2 is more cost-effective.

Example Workers Pattern with R2 :

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const imageKey = url.pathname.replace('/images/', '');
    const originURL = `https://r2-bucket.example.com/${imageKey}`;

    return fetch(originURL, {
      cf: {
        image: {
          width: 800,
          quality: 85,
          format: 'auto'
        }
      }
    });
  }
};

Reference: Cloudflare Reference Architecture

Troubleshooting

Problem: Images not transforming

Symptoms : /cdn-cgi/image/... returns original image or 404

Solutions :

Enable transformations on zone: Dashboard → Images → Transformations → Enable for zone
Verify zone is proxied through Cloudflare (orange cloud)
Check source image is publicly accessible
Wait 5-10 minutes for settings to propagate

Problem: Direct upload returns CORS error

Symptoms : Access-Control-Allow-Origin error in browser console

Solutions :

Use multipart/form-data encoding (let browser set Content-Type)
Don't call /direct_upload from browser; call from backend
Name file field file (not image)
Remove manual Content-Type header

Problem: Worker transformations return 9403 loop error

Symptoms : Cf-Resized: err=9403 in response headers

Solutions :

Don't fetch Worker's own URL (use external origin)
Don't transform already-resized images
Check URL routing logic to avoid loops

Problem: Signed URLs not working

Symptoms : 403 Forbidden when accessing signed URL

Solutions :

Verify image uploaded with requireSignedURLs=true
Check signature generation (HMAC-SHA256)
Ensure expiry timestamp is in future
Verify signing key matches dashboard (Images → Keys)
Cannot use flexible variants with signed URLs (use named variants)

Problem: Images uploaded but not appearing

Symptoms : Upload returns 200 OK but image not in dashboard

Solutions :

Check for draft: true in response (Direct Creator Upload)
Wait for upload to complete (check via GET /images/v1/{id})
Verify account ID matches
Check for upload errors in webhooks

Problem: Re-uploaded image still shows old version

Symptoms : Even users who never visited page see old image after re-upload

Solutions :

Use unique image IDs for each upload: const imageId = \${baseId}-${Date.now()};
Set shorter Cache-Control headers (e.g., max-age=86400 for 1 day instead of 30 days)
Manual purge via dashboard after re-upload with same ID
Understand default Browser Cache TTL is 2 days - users may see cached version

Root Cause : Cloudflare respects origin Cache-Control headers. If origin sets long max-age (e.g., 30 days), images remain cached even after re-upload with same ID.

Problem: PNG images not caching

Symptoms : PNG images bypass cache while other formats (JPEG, WebP) cache correctly

Solutions :

Create explicit cache rule: Dashboard → Caching → Cache Rules
Add rule: URI Path ends with .png → Cache Everything
Default cached extensions don't include .png (only .jpg, .jpeg, .gif, .webp, .bmp, .ico, .svg, , )

Official Documentation

Cloudflare Images : https://developers.cloudflare.com/images/
Get Started : https://developers.cloudflare.com/images/get-started/
Upload Images : https://developers.cloudflare.com/images/upload-images/
Direct Creator Upload : https://developers.cloudflare.com/images/upload-images/direct-creator-upload/
Transform Images : https://developers.cloudflare.com/images/transform-images/
Transform via URL : https://developers.cloudflare.com/images/transform-images/transform-via-url/
Transform via Workers : https://developers.cloudflare.com/images/transform-images/transform-via-workers/
Create Variants : https://developers.cloudflare.com/images/manage-images/create-variants/
Serve Private Images : https://developers.cloudflare.com/images/manage-images/serve-images/serve-private-images/

Package Versions

Last Verified : 2026-01-21 API Version : v2 (direct uploads), v1 (standard uploads) Optional : @cloudflare/workers-types@4.20260108.0

Skill Version : 2.1.0 | Changes : Added 3 new issues (AVIF limits, cache by device, PNG caching), enhanced metadata issue with format details, added Content Credentials, Browser Cache TTL, Product Merge notes, R2 integration pattern, Mirage deprecation notice, and cache troubleshooting guidance. Error count: 13 → 16.

Weekly Installs

328

Repository

jezweb/claude-skills

GitHub Stars

661

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykFail

Installed on

claude-code267

gemini-cli220

opencode216

cursor206

antigravity196

codex191

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

66,100 周安装

Cloudflare Images 图像托管与转换 API 使用指南 | 支持 AI 人脸裁剪与内容凭证

🇨🇳中文介绍

Cloudflare Images

概述

快速开始

相关 Skills

上传方法

图像转换

变体

签名 URL

关键规则

务必做到

切勿做到

已知问题预防

问题 #1: 直接创作者上传 CORS 错误

问题 #2: 错误 5408 - 上传超时

问题 #3: 错误 400 - 无效的文件参数

问题 #4: CORS 预检请求失败

问题 #5: 错误 9401 - 无效参数

问题 #6: 错误 9402 - 图像过大

问题 #7: 错误 9403 - 请求循环

问题 #8: 错误 9406/9419 - 无效的 URL 格式

问题 #9: 错误 9412 - 非图像响应

问题 #10: 错误 9413 - 超过最大图像面积

问题 #11: 灵活变体 + 签名 URL 不兼容

问题 #12: SVG 调整大小限制

问题 #13: 格式剥离 EXIF 元数据

问题 #14: AVIF 分辨率限制模糊性

问题 #15: 按设备类型缓存图像 (社区报告)

问题 #16: PNG 默认不缓存

使用捆绑资源

模板 (templates/)

参考资料 (references/)

脚本 (scripts/)

高级主题

故障排除

问题: 图像未转换

问题: 直接上传返回 CORS 错误

问题: Worker 转换返回 9403 循环错误

问题: 签名 URL 无效

问题: 图像已上传但未显示

问题: 重新上传的图像仍显示旧版本

问题: PNG 图像不缓存

官方文档

包版本

🇺🇸English

Cloudflare Images

Overview

Quick Start

Upload Methods

Image Transformations

Variants

Signed URLs

Critical Rules

Always Do

Never Do

Known Issues Prevention

Issue #1: Direct Creator Upload CORS Error

Issue #2: Error 5408 - Upload Timeout

Issue #3: Error 400 - Invalid File Parameter

Issue #4: CORS Preflight Failures

Issue #5: Error 9401 - Invalid Arguments

Issue #6: Error 9402 - Image Too Large

Issue #7: Error 9403 - Request Loop

Issue #8: Error 9406/9419 - Invalid URL Format

Issue #9: Error 9412 - Non-Image Response

Issue #10: Error 9413 - Max Image Area Exceeded

Issue #11: Flexible Variants + Signed URLs Incompatibility

Issue #12: SVG Resizing Limitation

Issue #13: EXIF Metadata Stripped by Format

Issue #14: AVIF Resolution Limit Ambiguity

Issue #15: Image Cache by Device Type (Community-reported)

Issue #16: PNG Not Cached by Default

Using Bundled Resources

Templates (templates/)

References (references/)

Scripts (scripts/)

Advanced Topics

Troubleshooting

Problem: Images not transforming