/cloudflare-images

name: cloudflare-images
description: "This skill should be used when the user asks to \"upload images to Cloudflare\", \"implement direct creator upload\", \"configure image transformations\", \"optimize WebP/AVIF\", \"create image variants\", \"generate signed URLs\", \"add image watermarks\", \"integrate with Next.js/Remix\", \"configure webhooks\", \"debug CORS errors\", \"troubleshoot error 5408/9401-9413\", or \"build responsive images with Cloudflare Images API\"."
license: MIT
metadata:
  version: "3.0.0"
  last_verified: "2025-12-27"
  workers_types_version: "4.20260408.0"
  typescript_version: "5.7.2"
  wrangler_version: "4.81.0"
  production_tested: true
  token_savings: "~65%"
  errors_prevented: 10
  templates_included: 16
  references_included: 16
  agents_included: 3
  commands_included: 3
  examples_included: 3
  diagrams_included: 3
  scripts_included: 5
  keywords:
    - cloudflare images
    - image upload cloudflare
    - imagedelivery.net
    - cloudflare image transformations
    - /cdn-cgi/image/
    - direct creator upload
    - image variants
    - cf.image workers
    - signed urls images
    - flexible variants
    - webp avif conversion
    - responsive images cloudflare
    - error 5408
    - error 9401
    - error 9403
    - CORS direct upload
    - multipart/form-data
    - image optimization cloudflare
    - image watermarks
    - webhooks images
    - nextjs cloudflare images
    - remix cloudflare images
    - custom domains images
    - content credentials
    - c2pa

Cloudflare Images

**Status**: Production Ready ✅ | **Version**: 3.0.0 | **Last Verified**: 2025-12-27

---

What Is Cloudflare Images?

Two powerful features:

1. **Images API**: Upload, store, serve images globally 2. **Image Transformations**: Resize/optimize ANY image

**Key benefits:**

• Global CDN delivery
• Automatic WebP/AVIF conversion
• Up to 100 variants
• Direct creator upload (no API keys in frontend)
• Signed URLs for private images
• Transform any image via URL or Workers

---

Quick Start (5 Minutes)

1. Enable Cloudflare Images

Dashboard → **Images** → **Enable**

Get your **Account ID** and create **API token** (Cloudflare Images: Edit permission)

2. Upload Image

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'

**CRITICAL:** Use `multipart/form-data`, not JSON

3. Serve Image

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

4. Enable Transformations

Dashboard → **Images** → **Transformations** → **Enable for zone**

Transform ANY image:

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

5. Transform via 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
        }
      }
    });
  }
};

**Load `references/setup-guide.md` for complete walkthrough.**

---

The 3 Core Features

Feature 1: Images API (Upload & Storage)

**Upload methods:** 1. File upload (server-side) 2. Upload via URL (ingest from external) 3. Direct creator upload (user uploads, no API keys)

**Load `templates/upload-api-basic.ts` for file upload example.** **Load `references/direct-upload-complete-workflow.md` for user uploads.**

Feature 2: Image Transformations

Optimize ANY image (uploaded or external).

**Methods:** 1. URL: `/cdn-cgi/image/width=800,quality=85/path/to/image.jpg` 2. Workers: `cf.image` fetch option

**Load `references/transformation-options.md` for all options.** **Load `templates/transform-via-workers.ts` for Workers example.**

Feature 3: Variants

Predefined transformations (up to 100).

**Examples:**

• `thumbnail`: 200x200, fit=cover
• `hero`: 1920x1080, quality=90
• `mobile`: 640, quality=75

**Load `references/variants-guide.md` for complete guide.**

---

Critical Rules

Always Do ✅

1. **Use multipart/form-data** for uploads (not JSON) 2. **Enable transformations for zones** before using `/cdn-cgi/image/` 3. **Use direct creator upload** for user uploads (don't expose API tokens) 4. **Set CORS headers** for direct uploads from browser 5. **Use signed URLs** for private images 6. **Configure variants** for common sizes (avoid dynamic transformations) 7. **Use format=auto** for automatic WebP/AVIF 8. **Handle error codes** (9401, 9403, 9413, 5408) 9. **Set quality=85** for optimal size/quality balance 10. **Use fit=cover** for consistent aspect ratios

Never Do ❌

1. **Never expose API tokens** in frontend code 2. **Never use JSON encoding** for file uploads 3. **Never skip CORS configuration** for direct uploads 4. **Never exceed 100 variants** (hard limit) 5. **Never use transformations without enabling for zone** 6. **Never hardcode account IDs** in public code 7. **Never skip error handling** (uploads can fail) 8. **Never use quality >90** (diminishing returns) 9. **Never skip image validation** (size, format, dimensions) 10. **Never use transformations on non-proxied requests**

---

Top 2 Use Cases

Use Case 1: User Profile Pictures

Direct creator upload pattern for user-uploaded images:

// 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 });

**Load `templates/direct-creator-upload-backend.ts` for complete exam