Cloudflare Images

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

What Is Cloudflare Images?

Two powerful features:

Images API: Upload, store, serve images globally
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:

File upload (server-side)
Upload via URL (ingest from external)
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:

URL: /cdn-cgi/image/width=800,quality=85/path/to/image.jpg
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 ✅

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

Never Do ❌

Never expose API tokens in frontend code
Never use JSON encoding for file uploads
Never skip CORS configuration for direct uploads
Never exceed 100 variants (hard limit)
Never use transformations without enabling for zone
Never hardcode account IDs in public code
Never skip error handling (uploads can fail)
Never use quality >90 (diminishing returns)
Never skip image validation (size, format, dimensions)
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 example. See examples/basic-upload/ for complete working project.

Use Case 2: Responsive Images

Responsive images with srcset for optimal performance:

<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"
/>

Load templates/responsive-images-srcset.html for complete example. See examples/responsive-gallery/ for complete working project.

Additional Use Cases:

Transform Existing Images: Load references/transformation-options.md
Private Images: Load references/signed-urls-guide.md or see examples/private-images/
Batch Upload: Load templates/batch-upload.ts
Framework Integration: Load references/framework-integration.md for Next.js, Remix, Astro
Watermarking: Load references/overlays-watermarks.md and templates/overlay-watermark.ts
Custom Domains: Load references/custom-domains.md
Webhooks: Load references/webhooks-guide.md and templates/webhook-handler.ts

Top 2 Errors Prevented

Error 1: CORS Issues with Direct Upload

Problem: Browser blocks direct upload from your domain.

Solution: Configure CORS headers when generating 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}` },
    body: JSON.stringify({
      requireSignedURLs: false,
      metadata: { source: 'user-upload' }
    })
  }
);

Error 2: Multipart Form Data Encoding

Problem: JSON encoding fails for file uploads (must use multipart/form-data).

Solution:

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

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

Additional Common Errors:

Error 9401 (Transformations not enabled): Load references/top-errors.md
Error 9403 (Invalid transformation): Load references/top-errors.md
Error 9413 (Variant limit exceeded): Load references/top-errors.md
Error 5408 (Upload timeout): Load references/top-errors.md
Missing requireSignedURLs: Load references/signed-urls-guide.md

Load references/top-errors.md for all 10 errors with complete solutions.

When to Load References

Core References

Load references/setup-guide.md when:

First-time Cloudflare Images setup
Need step-by-step walkthrough

Load references/api-reference.md when:

Need complete API documentation
All endpoints and parameters

Load references/top-errors.md when:

Encountering any error code (5408, 9401-9413)
Troubleshooting upload/transformation issues

Upload References

Load references/direct-upload-complete-workflow.md when:

Implementing user uploads
Need frontend + backend example
Configuring CORS

Load references/signed-urls-guide.md when:

Implementing private images with access control
Need HMAC-SHA256 signature generation

Load references/webhooks-guide.md when:

Processing upload completion events
Implementing webhook handlers with signature verification

Transformation References

Load references/transformation-options.md when:

Need complete transformation reference
Exploring all fit/format/effect options

Load references/format-optimization.md when:

Optimizing format selection (WebP/AVIF)
Quality vs size tradeoffs

Load references/polish-compression.md when:

Need details on Lossless/Lossy/WebP compression modes
Metadata handling (EXIF removal)

Load references/overlays-watermarks.md when:

Adding text or logo watermarks
Implementing branding/copyright protection

Advanced Features

Load references/variants-guide.md when:

Creating/managing variants (up to 100 max)
Need flexible variants vs named variants

Load references/responsive-images-patterns.md when:

Building responsive images with srcset
Implementing picture element for art direction

Load references/framework-integration.md when:

Integrating with Next.js, Remix, Astro, SvelteKit
Need framework-specific patterns and loaders

Load references/custom-domains.md when:

Serving images from branded domains
CNAME configuration and SSL setup

Load references/content-credentials.md when:

Preserving EXIF/IPTC metadata
Implementing C2PA Content Credentials for authenticity

Load references/sourcing-kit.md when:

Migrating from Cloudinary, Imgix, or S3
Bulk import from external CDNs

Using Bundled Resources

References (16 reference files)

Core: setup-guide.md, api-reference.md, top-errors.md

Upload: direct-upload-complete-workflow.md, signed-urls-guide.md, webhooks-guide.md

Transform: transformation-options.md, format-optimization.md, polish-compression.md, overlays-watermarks.md

Advanced: variants-guide.md, responsive-images-patterns.md, framework-integration.md, custom-domains.md, content-credentials.md, sourcing-kit.md

Templates (16 template files)

Upload: upload-api-basic.ts, upload-via-url.ts, direct-creator-upload-backend.ts, direct-creator-upload-frontend.html, batch-upload.ts

Transform: transform-via-url.ts, transform-via-workers.ts, overlay-watermark.ts

Variants: variants-management.ts, signed-urls-generation.ts, responsive-images-srcset.html

Integration: nextjs-integration.tsx, remix-integration.tsx, webhook-handler.ts

Config: wrangler-images-binding.jsonc, package.json

Agents (3 autonomous agents)

troubleshooting-agent - Diagnose upload/transformation errors (5408, 9401-9413)
upload-workflow-agent - Guide complete upload implementation (frontend + backend)
optimization-agent - Recommend image optimization strategies

Use: /agent <agent-name> or let Claude auto-detect when relevant

Commands (3 slash commands)

/check-images - Quick API health check and configuration validation
/validate-config - Validate wrangler.jsonc bindings and configuration
/generate-variant - Interactive variant generator

Use: /<command-name>

Examples (3 complete working projects)

basic-upload/ - Minimal upload implementation with Hono + Workers
responsive-gallery/ - Responsive image gallery with srcset and lazy loading
private-images/ - Signed URLs with time-based expiry and access control

Clone and run: cd examples/<example-name> && npm install && npm run dev

Architecture Diagrams (3 diagrams)

direct-upload-workflow.md - Sequence diagram of direct creator upload flow
transformation-pipeline.md - Flowchart showing transformation processing
variants-structure.md - Named vs flexible variants comparison

View in: assets/diagrams/

Utility Scripts (5 scripts)

test-upload.sh - Test API connectivity with sample image upload
generate-signed-url.sh - CLI tool to generate signed URLs with expiry
validate-variants.sh - List all variants and check variant count (max 100)
analyze-usage.sh - Query API for storage usage and estimated costs
check-versions.sh - Verify package versions are current

Run: ./scripts/<script-name>.sh (requires CF_ACCOUNT_ID and CF_API_TOKEN in .env)

Pricing

Images API: $5/100k stored, $1/100k delivered Transformations: $0.50/1k (100k/month free per zone) Direct Upload: Included in API pricing

Official Documentation

Images Overview: https://developers.cloudflare.com/images/
Upload API: https://developers.cloudflare.com/images/upload-images/
Transformations: https://developers.cloudflare.com/images/transform-images/
Direct Creator Upload: https://developers.cloudflare.com/images/upload-images/direct-creator-upload/
Variants: https://developers.cloudflare.com/images/manage-images/create-variants/