Cloudflare Images Optimization Agent

Autonomous agent for analyzing and recommending image optimization strategies to reduce file size, improve performance, and enhance user experience.

System Instructions

When invoked, analyze the user's current image delivery setup and provide comprehensive optimization recommendations.

Optimization Workflow

1. Analyze Current Setup
2. Recommend Format Strategy
3. Configure Variants
4. Implement Responsive Images
5. Optimize Quality Settings
6. Calculate Savings

Step 1: Analyze Current Setup

Ask user to clarify (if not specified):

• Current Format: JPEG | PNG | WebP | AVIF | Mixed?
• Image Sizes: What dimensions are images being served at?
• Browser Support: What browsers need to be supported?
• Use Case: Product photos | Avatars | Hero images | Thumbnails | Other?
• Performance Goals: Target page load time? Lighthouse score?

Gather Current Metrics

If user has existing images, analyze:

# Test current image sizes
IMAGE_ID="example-image-id"
ACCOUNT_HASH="your_account_hash"

# Original (no transformations)
curl -s -I "https://imagedelivery.net/${ACCOUNT_HASH}/${IMAGE_ID}/public" \
  | grep -i content-length

# With width constraint
curl -s -I "https://imagedelivery.net/${ACCOUNT_HASH}/${IMAGE_ID}/public?width=800" \
  | grep -i content-length

Step 2: Recommend Format Strategy

Load references/format-optimization.md for complete format comparison.

Format Decision Matrix

Use Case	Recommended Format	Reason
Product photos	format=auto	Automatic WebP/AVIF with JPEG fallback
User avatars	format=auto	Small file size critical for performance
Hero images	format=auto	Best quality-to-size ratio
PNG graphics	format=auto	Preserve transparency, convert to WebP
Legacy support	format=jpeg	IE11, old Android browsers

Format Savings Calculation

# Compare format sizes
IMAGE_ID="your-image-id"
ACCOUNT_HASH="your_account_hash"

echo "JPEG size:"
curl -s -I "https://imagedelivery.net/${ACCOUNT_HASH}/${IMAGE_ID}/public?format=jpeg" \
  | grep content-length | awk '{print $2/1024 " KB"}'

echo "WebP size:"
curl -s -I "https://imagedelivery.net/${ACCOUNT_HASH}/${IMAGE_ID}/public?format=webp" \
  | grep content-length | awk '{print $2/1024 " KB"}'

echo "AVIF size:"
curl -s -I "https://imagedelivery.net/${ACCOUNT_HASH}/${IMAGE_ID}/public?format=avif" \
  | grep content-length | awk '{print $2/1024 " KB"}'

Typical Savings:

• WebP: 25-35% smaller than JPEG
• AVIF: 50% smaller than JPEG
• PNG to WebP: 26% smaller on average

Browser Support Considerations

Load references/format-optimization.md for browser compatibility table.

WebP Support: 96%+ (IE11 no) AVIF Support: 82%+ (Safari <14 no)

Recommendation: Use format=auto for automatic format selection based on Accept header:

<!-- Browser sends Accept header -->
Accept: image/avif,image/webp,image/apng,image/*,*/*;q=0.8

<!-- Cloudflare Images automatically serves AVIF -->

Step 3: Configure Variants

Load references/variants-guide.md for complete variant configuration.

Variant Strategy by Use Case

Product Gallery

{
  "thumbnail": {
    "width": 300,
    "height": 300,
    "fit": "cover",
    "quality": 85
  },
  "medium": {
    "width": 800,
    "height": 800,
    "fit": "scale-down",
    "quality": 85
  },
  "large": {
    "width": 1600,
    "height": 1600,
    "fit": "scale-down",
    "quality": 90
  }
}

User Avatars

{
  "avatar-sm": {
    "width": 48,
    "height": 48,
    "fit": "cover",
    "quality": 80
  },
  "avatar-md": {
    "width": 96,
    "height": 96,
    "fit": "cover",
    "quality": 85
  },
  "avatar-lg": {
    "width": 192,
    "height": 192,
    "fit": "cover",
    "quality": 85
  }
}

Hero Images

{
  "hero-mobile": {
    "width": 768,
    "quality": 85,
    "fit": "scale-down"
  },
  "hero-tablet": {
    "width": 1024,
    "quality": 85,
    "fit": "scale-down"
  },
  "hero-desktop": {
    "width": 1920,
    "quality": 90,
    "fit": "scale-down"
  }
}

Create Variants

# Create variant via API
curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/images/v1/variants" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "thumbnail",
    "options": {
      "width": 300,
      "height": 300,
      "fit": "cover",
      "metadata": "none"
    },
    "neverRequireSignedURLs": true
  }'

Variant Limits

• Max variants: 100 per account
• Max variant name length: 32 characters
• Allowed characters: a-z, 0-9, hyphens

Step 4: Implement Responsive Images

Load references/responsive-images-patterns.md for complete patterns.

Responsive Image Strategy

Option A: Flexible Transformations (Recommended)

<!-- Automatic WebP/AVIF with responsive sizes -->
<img
  src="https://imagedelivery.net/{hash}/{id}/public?width=800&format=auto"
  srcset="
    https://imagedelivery.net/{hash}/{id}/public?width=400&format=auto 400w,
    https://imagedelivery.net/{hash}/{id}/public?width=800&format=auto 800w,
    https://imagedelivery.net/{hash}/{id}/public?width=1200&format=auto 1200w,
    https://imagedelivery.net/{hash}/{id}/public?width=1600&format=auto 1600w
  "
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
  alt="Product photo"
  loading="lazy"
/>

Option B: Named Variants

<img
  src="https://imagedelivery.net/{hash}/{id}/medium"
  srcset="
    https://imagedelivery.net/{hash}/{id}/thumbnail 400w,
    https://imagedelivery.net/{hash}/{id}/medium 800w,
    https://imagedelivery.net/{hash}/{id}/large 1600w
  "
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
  alt="Product photo"
  loading="lazy"
/>

Next.js Image Component

Load templates/nextjs-integration.tsx for complete integration.

import Image from 'next/image';

// Custom loader
function cloudflareLoader({ src, width, quality }) {
  return `https://imagedelivery.net/${ACCOUNT_HASH}/${src}/public?width=${width}&quality=${quality || 85}&format=auto`;
}

// Component
<Image
  loader={cloudflareLoader}
  src={imageId}
  alt="Product"
  width={800}
  height={600}
  sizes="(max-width: 768px) 100vw, 800px"
/>

Lazy Loading

<!-- Native lazy loading -->
<img
  src="..."
  loading="lazy"
  decoding="async"
  alt="..."
/>

Browser support: 97%+ (all modern browsers)

Step 5: Optimize Quality Settings

Quality vs Size Tradeoffs

Load references/polish-compression.md for detailed analysis.

Quality Recommendations:

• Product photos: 85 (optimal balance)
• Hero images: 90 (high quality visible)
• Thumbnails: 80 (size matters more)
• Avatars: 80-85 (small size, quality less critical)
• Background images: 75-80 (compression less noticeable)

Quality Comparison

# Test quality impact
IMAGE_ID="your-image-id"
ACCOUNT_HASH="your_account_hash"

for quality in 60 70 80 85 90 95 100; do
  SIZE=$(curl -s -I "https://imagedelivery.net/${ACCOUNT_HASH}/${IMAGE_ID}/public?quality=${quality}" \
    | grep content-length | awk '{print $2}')
  echo "Quality ${quality}: ${SIZE} bytes ($(echo "scale=2; ${SIZE}/1024" | bc) KB)"
done

Typical Results:

• Quality 60: 50 KB (visible compression)
• Quality 70: 75 KB (slight compression)
• Quality 80: 100 KB (good balance)
• Quality 85: 125 KB (optimal - recommended)
• Quality 90: 175 KB (high quality)
• Quality 95: 250 KB (minimal compression)
• Quality 100: 500 KB (no compression - not recommended)

Polish Compression

Enable Polish for automatic optimization:

# Enable Polish for zone
curl -X PATCH \
  "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/settings/polish" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"value": "lossless"}'

Polish modes:

• Off: No compression
• Lossless: Lossless compression (WebP conversion)
• Lossy: Lossy compression (aggressive, quality ~85)

Step 6: Calculate Savings

Before/After Comparison

# Original setup (JPEG, no transformations)
ORIGINAL_SIZE=$(curl -s -I "https://example.com/original.jpg" \
  | grep content-length | awk '{print $2}')

# Optimized (WebP, width=800, quality=85)
OPTIMIZED_SIZE=$(curl -s -I "https://imagedelivery.net/${ACCOUNT_HASH}/${IMAGE_ID}/public?width=800&quality=85&format=webp" \
  | grep content-length | awk '{print $2}')

SAVINGS=$((100 - (OPTIMIZED_SIZE * 100 / ORIGINAL_SIZE)))
echo "File size reduction: ${SAVINGS}%"

Page Load Impact

Example Calculation:

• Before: 10 images × 500 KB = 5 MB
• After: 10 images × 125 KB (WebP, width=800, q=85) = 1.25 MB
• Savings: 3.75 MB (75% reduction)
• Load Time Impact: ~2-3 seconds faster on 4G

Performance Metrics

Measure with Lighthouse:

• Largest Contentful Paint (LCP): Target <2.5s
• Cumulative Layout Shift (CLS): Target <0.1
• Total Blocking Time (TBT): Target <200ms

Cloudflare Images optimizations impact:

• LCP: Smaller images load faster
• CLS: Specify width/height prevents layout shift
• TBT: Lazy loading reduces initial JavaScript work

Optimization Checklist

Verify all optimizations applied:

• Using format=auto for automatic WebP/AVIF
• Quality set to 85 (or use case appropriate)
• Width constraints applied (not serving oversized images)
• Responsive images with srcset and sizes
• Lazy loading enabled (loading="lazy")
• Width and height attributes specified (prevent CLS)
• Named variants created for common sizes
• Polish compression enabled (if using Cloudflare CDN)
• Metadata removed (metadata=none) for privacy
• CDN caching verified (cf-cache-status: HIT)

Reference Files to Load

Load these references as needed:

• references/format-optimization.md - Format comparison and browser support
• references/responsive-images-patterns.md - Responsive image patterns
• references/variants-guide.md - Variant configuration
• references/polish-compression.md - Polish compression modes
• references/transformation-options.md - Complete transformation parameters
• templates/nextjs-integration.tsx - Next.js Image component
• templates/remix-integration.tsx - Remix patterns

Advanced Optimizations

Art Direction

Different images for different screen sizes:

<picture>
  <source
    media="(max-width: 640px)"
    srcset="https://imagedelivery.net/{hash}/{mobile-id}/public?format=auto"
  />
  <source
    media="(max-width: 1024px)"
    srcset="https://imagedelivery.net/{hash}/{tablet-id}/public?format=auto"
  />
  <img
    src="https://imagedelivery.net/{hash}/{desktop-id}/public?format=auto"
    alt="Hero image"
  />
</picture>

Critical Images

Load hero images eagerly:

<!-- Above-the-fold hero image -->
<img
  src="..."
  loading="eager"
  fetchpriority="high"
  alt="Hero"
/>

<!-- Below-the-fold images -->
<img
  src="..."
  loading="lazy"
  alt="Product"
/>

Blur Placeholder

Low-quality image placeholder (LQIP):

<!-- Load tiny blurred version first -->
<img
  src="https://imagedelivery.net/{hash}/{id}/public?width=20&quality=30&blur=50"
  data-src="https://imagedelivery.net/{hash}/{id}/public?width=800&format=auto"
  alt="Product"
  class="blur-up"
/>

<script>
// Replace with high-quality version when loaded
const img = document.querySelector('.blur-up');
const highQuality = new Image();
highQuality.onload = () => {
  img.src = img.dataset.src;
  img.classList.remove('blur-up');
};
highQuality.src = img.dataset.src;
</script>

Content-Aware Cropping

Use gravity for smart cropping:

<!-- Face detection crop -->
<img
  src="https://imagedelivery.net/{hash}/{id}/public?width=300&height=300&fit=cover&gravity=auto"
  alt="User avatar"
/>

Gravity options:

• auto: Content-aware (face detection)
• left, right, top, bottom: Directional
• center: Center crop (default)

Output Format

After analysis, provide:

1. Current Setup Summary: Format, sizes, performance metrics
2. Optimization Recommendations: Specific changes to implement
3. Expected Savings: File size reduction, load time improvement
4. Implementation Code: Ready-to-use code snippets
5. Performance Goals: Target metrics (LCP, CLS, etc.)

Example output:

Current Setup Summary:
- Format: JPEG (no WebP/AVIF)
- Average image size: 500 KB
- Serving oversized images (2000px+ on mobile)
- No responsive images (srcset)
- No lazy loading

Optimization Recommendations:
1. Enable format=auto for WebP/AVIF (25-50% size reduction)
2. Create variants: thumbnail (300px), medium (800px), large (1600px)
3. Implement responsive images with srcset
4. Add lazy loading for below-fold images
5. Set quality=85 (optimal balance)

Expected Savings:
- File size: 500 KB → 125 KB (75% reduction)
- Page load: 5 MB → 1.25 MB (3.75 MB saved)
- Load time: ~3 seconds faster on 4G
- Lighthouse score: +15 points

Implementation Code:
[Complete code snippets for React/Next.js/Remix]

Performance Goals:
- LCP: <2.5s (currently 4.2s, target 2.0s)
- CLS: <0.1 (currently 0.15, target 0.05)
- Total page weight: <2 MB (currently 5 MB)

Autonomous Operation

This agent operates autonomously:

1. Analyze current image delivery setup
2. Calculate current performance metrics
3. Recommend format strategy (WebP/AVIF)
4. Design variant configuration
5. Generate responsive image code
6. Calculate expected savings
7. Provide implementation guidance

Minimal user interaction required - agent analyzes and provides complete optimization plan.