Cloudflare Images

Status: Production Ready ✅ | Last Verified: 2025-11-26

---

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

Load templates/direct-creator-upload-backend.ts for complete example.

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

Load templates/responsive-images-srcset.html for complete example.

Use Case 3: Transform Existing Images

<!-- Original image on your server -->
<img src="/uploads/photo.jpg" />

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

Load references/transformation-options.md for all options.

Use Case 4: Private Images with Signed URLs

// Generate signed URL (backend)
const expiryTimestamp = Math.floor(Date.now() / 1000) + 3600;  // 1 hour

const message = `/${imageId}/${variant}/${expiryTimestamp}`;
const encoder = new TextEncoder();
const data = encoder.encode(message);
const hashBuffer = await crypto.subtle.digest('SHA-256', data);
const signature = btoa(String.fromCharCode(...new Uint8Array(hashBuffer)));

const signedURL = `https://imagedelivery.net/${ACCOUNT_HASH}/${imageId}/${variant}?exp=${expiryTimestamp}&sig=${signature}`;

Load references/signed-urls-guide.md for complete implementation.

Use Case 5: Batch Upload

const files = ['img1.jpg', 'img2.jpg', 'img3.jpg'];

const uploadPromises = files.map(file =>
  fetch(`https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/images/v1`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_TOKEN}` },
    body: createFormData(file)
  })
);

const results = await Promise.all(uploadPromises);

Load templates/batch-upload.ts for complete example.

---

Common Transformations

Resize

/cdn-cgi/image/width=800,height=600,fit=cover/image.jpg

fit options:

• scale-down: Never enlarge
• contain: Fit within dimensions
• cover: Fill dimensions, crop excess
• crop: Crop to exact size
• pad: Add padding

Optimize

/cdn-cgi/image/quality=85,format=auto/image.jpg

format options:

• auto: WebP/AVIF for supporting browsers
• webp: Force WebP
• avif: Force AVIF
• jpeg, png: Force format

Effects

/cdn-cgi/image/blur=10,sharpen=3,brightness=1.1/image.jpg

Load references/transformation-options.md for complete reference.

---

Top 5 Errors Prevented

Error 1: CORS Issues with Direct Upload

Problem: Browser blocks direct upload

Solution: Configure CORS headers

const response = await fetch(
  `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/images/v2/direct_upload`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      requireSignedURLs: false,
      metadata: { source: 'user-upload' }
    })
  }
);

Load references/top-errors.md for all 10 errors.

Error 2: Multipart Form Data Encoding

Problem: JSON encoding fails for file uploads

Solution: Use multipart/form-data

// ✅ CORRECT
const formData = new FormData();
formData.append('file', file);

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

Error 3: Transformation Error 9401

Problem: Transformations not enabled for zone

Solution: Enable in dashboard

Dashboard → Images → Transformations → Enable for zone

Error 4: Variant Limit (100)

Problem: Trying to create >100 variants

Solution: Use flexible variants or combine similar sizes

// Instead of: thumbnail-100, thumbnail-150, thumbnail-200...
// Use: thumbnail (configurable in URL)

<img src="https://imagedelivery.net/abc/xyz/thumbnail?width=150" />

Error 5: Missing requireSignedURLs Configuration

Problem: Private images accessible without signature

Solution: Enable signed URLs

await fetch(`https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/images/v1/${imageId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    requireSignedURLs: true
  })
});

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

---

When to Load References

Load references/setup-guide.md when:

• First-time Cloudflare Images setup
• Need step-by-step walkthrough
• Setting up direct creator upload
• Enabling transformations

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

• Implementing user uploads
• Need frontend + backend example
• Configuring CORS
• Handling upload callbacks

Load references/transformation-options.md when:

• Need complete transformation reference
• Exploring all fit/format/effect options
• Optimizing image delivery
• Building custom transformation URLs

Load references/variants-guide.md when:

• Creating/managing variants
• Need flexible variants
• Variant best practices
• Troubleshooting variant issues

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

• Implementing private images
• Need signature generation
• Setting expiry times
• Securing image access

Load references/top-errors.md when:

• Encountering any error code
• Troubleshooting upload/transformation issues
• Prevention checklist needed

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

• Building responsive images
• Need srcset examples
• Implementing picture element
• Art direction use cases

Load references/format-optimization.md when:

• Optimizing format selection
• WebP/AVIF conversion
• Quality vs size tradeoffs
• Browser compatibility concerns

Load references/api-reference.md when:

• Need complete API documentation
• All endpoints and parameters
• Rate limits and quotas
• Authentication details

---

Using Bundled Resources

References (references/)

• setup-guide.md - Complete setup walkthrough
• api-reference.md - Complete API documentation
• direct-upload-complete-workflow.md - User upload implementation
• transformation-options.md - All transformation options
• variants-guide.md - Variants management
• signed-urls-guide.md - Private images with signatures
• responsive-images-patterns.md - Responsive image patterns
• format-optimization.md - Format selection and optimization
• top-errors.md - All 10 common errors with solutions

Templates (templates/)

• upload-api-basic.ts - Basic file upload
• upload-via-url.ts - Upload from external URL
• direct-creator-upload-backend.ts - Backend for user uploads
• direct-creator-upload-frontend.html - Frontend for user uploads
• transform-via-url.ts - URL transformation examples
• transform-via-workers.ts - Workers transformation examples
• variants-management.ts - Create/update variants
• signed-urls-generation.ts - Generate signed URLs
• batch-upload.ts - Batch upload implementation
• responsive-images-srcset.html - Responsive images with srcset
• wrangler-images-binding.jsonc - Workers binding configuration
• package.json - Dependencies

---

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/