Cloudflare Images Skill for Claude

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

10. 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)

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