Cloudflare Images

What Is Cloudflare Images?

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

• 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

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'

multipart/form-data

3. Serve Image

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

4. Enable Transformations

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

references/setup-guide.md

The 3 Core Features

Feature 1: Images API (Upload & Storage)

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

templates/upload-api-basic.ts

references/direct-upload-complete-workflow.md

Feature 2: Image Transformations

1. URL:

   /cdn-cgi/image/width=800,quality=85/path/to/image.jpg

2. Workers:

   cf.image

   fetch option

references/transformation-options.md

templates/transform-via-workers.ts

Feature 3: Variants

• thumbnail

  : 200x200, fit=cover

• hero

  : 1920x1080, quality=90

• mobile

  : 640, quality=75

references/variants-guide.md

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

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

Use Case 2: Responsive Images

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

• 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

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

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

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

• 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

references/top-errors.md

When to Load References

Core References

references/setup-guide.md

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

references/api-reference.md

• Need complete API documentation
• All endpoints and parameters

references/top-errors.md

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

Upload References

references/direct-upload-complete-workflow.md

• Implementing user uploads
• Need frontend + backend example
• Configuring CORS

references/signed-urls-guide.md

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

references/webhooks-guide.md

• Processing upload completion events
• Implementing webhook handlers with signature verification

Transformation References

references/transformation-options.md

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

references/format-optimization.md

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

references/polish-compression.md

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

references/overlays-watermarks.md

• Adding text or logo watermarks
• Implementing branding/copyright protection

Advanced Features

references/variants-guide.md

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

references/responsive-images-patterns.md

• Building responsive images with srcset
• Implementing picture element for art direction

references/framework-integration.md

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

references/custom-domains.md

• Serving images from branded domains
• CNAME configuration and SSL setup

references/content-credentials.md

• Preserving EXIF/IPTC metadata
• Implementing C2PA Content Credentials for authenticity

references/sourcing-kit.md

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

Using Bundled Resources

References (16 reference files)

Templates (16 template files)

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

/agent <agent-name>

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

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

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

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

./scripts/<script-name>.sh

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/