Cloudflare Images

Cloudflare Images Skill

Status: Production Ready ✅ Last Updated: 2025-10-26 Token Savings: ~60% (10,000 → 4,000 tokens) Errors Prevented: 13+ documented issues

---

Auto-Trigger Keywords

Primary Keywords

• cloudflare images
• image upload cloudflare
• imagedelivery.net
• cloudflare image transformations
• /cdn-cgi/image/
• direct creator upload
• image variants cloudflare
• cf.image workers
• cloudflare cdn images

Secondary Keywords

• image optimization cloudflare
• image resizing cloudflare
• responsive images cloudflare
• signed urls images
• flexible variants
• webp avif conversion
• cloudflare images api
• image storage cloudflare
• cloudflare image delivery

Technology Keywords

• cloudflare workers image
• fetch cf image
• multipart/form-data upload
• hmac-sha256 signed urls
• one-time upload url
• image variants api
• srcset responsive

Use Case Keywords

• user uploaded images
• private images signed url
• image cdn cloudflare
• thumbnail generation
• format auto detection
• image quality optimization
• crop resize images

Error-Based Keywords

• error 5408 cloudflare images
• error 9401 cf.image
• error 9403 request loop
• error 9406 https required
• error 9412 non-image response
• error 9413 image too large
• CORS direct upload
• "content-type is not allowed"
• "image too large" cloudflare
• signed urls not working
• direct upload cors error
• multipart form data error
• flexible variants signed urls

---

What This Skill Does

Complete Cloudflare Images knowledge covering:

Images API (Upload & Storage):

• ✅ Upload methods: file upload, URL ingestion, direct creator upload
• ✅ Variants management: named variants (up to 100), flexible variants
• ✅ Serving: imagedelivery.net, custom domains, signed URLs
• ✅ Batch API for high-volume uploads
• ✅ Webhooks for upload notifications

Image Transformations:

• ✅ URL transformations (/cdn-cgi/image/width=800,quality=85/...)
• ✅ Workers transformations (fetch(url, { cf: { image: {...} } }))
• ✅ All transform options: resize, crop, quality, format, effects
• ✅ Format optimization: auto WebP/AVIF conversion
• ✅ Responsive images: srcset patterns

---

Known Issues Prevented

Issue	Error	Source	Prevention
CORS Upload Error	content-type is not allowed	CF #345739	Use multipart/form-data, name field file
Upload Timeout	Error 5408 after 15s	CF #571336	Compress images, max 10MB limit
Invalid File Parameter	400 Bad Request	CF #487629	Field MUST be named file
CORS Preflight Fail	OPTIONS request blocked	CF #306805	Call /direct_upload from backend only
Invalid Arguments	Error 9401	CF Docs	Verify all cf.image params
Image Too Large	Error 9402/9413	CF Docs	Max 100 megapixels
Request Loop	Error 9403	CF Docs	Don't fetch Worker's own URL
Invalid URL Format	Error 9406/9419	CF Docs	HTTPS only, URL-encode paths
Non-Image Response	Error 9412	CF Docs	Verify origin returns image
Flex Variants + Signed URLs	Not compatible	CF Docs	Use named variants for private images
SVG Resizing	Doesn't resize	CF Docs	SVG inherently scalable
EXIF Metadata Stripped	GPS/camera data removed	CF Docs	Use metadata=keep option
Transformations Not Working	404 or original image	Common issue	Enable transformations on zone

---

When to Use This Skill

Use this skill when:

• ✅ Setting up Cloudflare Images storage
• ✅ Implementing user-uploaded images
• ✅ Creating responsive images with srcset
• ✅ Optimizing image formats (WebP/AVIF)
• ✅ Resizing images via URL or Workers
• ✅ Debugging CORS errors with direct uploads
• ✅ Handling image transformation errors
• ✅ Implementing signed URLs for private images
• ✅ Managing image variants
• ✅ Building image CDNs
• ✅ Migrating to Cloudflare Images
• ✅ Creating thumbnails and previews

Don't use when:

• ❌ Using a different image CDN (Imgix, Cloudinary, etc.)
• ❌ Storing videos (use Cloudflare Stream instead)
• ❌ Client-side image editing (use Canvas API)

---

Quick Example

Direct Creator Upload (User Upload)

Backend:

// Generate one-time upload URL
const response = await fetch(
  `https://api.cloudflare.com/client/v4/accounts/${accountId}/images/v2/direct_upload`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      requireSignedURLs: false,
      metadata: { userId: '12345' }
    })
  }
);

const { uploadURL } = await response.json();
return json({ uploadURL });

Frontend:

const formData = new FormData();
formData.append('file', fileInput.files[0]); // MUST be named 'file'

await fetch(uploadURL, {
  method: 'POST',
  body: formData // Browser sets multipart/form-data
});

Image Transformations

URL Method:

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

Workers Method:

return fetch('https://example.com/image.jpg', {
  cf: {
    image: {
      width: 800,
      quality: 85,
      format: 'auto' // WebP/AVIF auto-detection
    }
  }
});

---

What's Included

Templates (11 files)

• wrangler-images-binding.jsonc - Configuration
• upload-api-basic.ts - File upload to API
• upload-via-url.ts - Ingest from external URL
• direct-creator-upload-backend.ts - Generate 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/manage variants
• signed-urls-generation.ts - HMAC-SHA256 signed URLs
• responsive-images-srcset.html - Responsive image patterns
• batch-upload.ts - Batch API usage

References (8 docs)

• api-reference.md - Complete API endpoints
• transformation-options.md - All transform params
• variants-guide.md - Named vs flexible variants
• signed-urls-guide.md - HMAC-SHA256 implementation
• direct-upload-complete-workflow.md - Full architecture
• responsive-images-patterns.md - srcset, sizes, art direction
• format-optimization.md - WebP/AVIF strategies
• top-errors.md - All 13+ errors with solutions

Scripts (1 file)

• check-versions.sh - Verify API endpoints

---

Critical CORS Fix (Most Common Issue)

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

Solution:

// ✅ CORRECT
const formData = new FormData();
formData.append('file', fileInput.files[0]); // Name MUST be 'file'
await fetch(uploadURL, {
  method: 'POST',
  body: formData // NO Content-Type header - browser sets it
});

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

Architecture:

Browser → Backend API → POST /direct_upload → uploadURL
         ← Returns uploadURL ←

Browser → Upload to uploadURL (multipart/form-data) → Cloudflare

---

Dependencies

Required:

• Cloudflare account with Images enabled
• Account ID and API token (Images: Edit permission)

Optional:

• @cloudflare/workers-types@latest - TypeScript types

API Version: v2 (direct uploads), v1 (standard uploads)

---

Official Documentation

• Images Overview: 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/
• API Reference: https://developers.cloudflare.com/api/resources/images/

---

Production Validated

Based on:

• ✅ Official Cloudflare documentation
• ✅ Cloudflare community issue tracking
• ✅ Real-world CORS error solutions
• ✅ API error code documentation
• ✅ Production deployment patterns

---

Next Steps

1. Install Skill: ./scripts/install-skill.sh cloudflare-images
2. Read SKILL.md: Complete setup guide
3. Copy Templates: Start with upload-api-basic.ts or direct-creator-upload-backend.ts
4. Enable Transformations: Dashboard → Images → Transformations → Enable
5. Create Variants: Dashboard → Images → Variants → Create
6. Test Upload: Use Direct Creator Upload workflow
7. Transform Images: Try URL or Workers method

---

Last Updated: 2025-10-26 | Maintainer: Claude Skills Collection