Setting the file. One moment.
Chapter 04 · Cloudflare Deploy
Subchapter 4.110
references/images/gotchas.mdMarkdown2 KBView on GitHub
| Mode | Best For | Behavior |
|---|---|---|
cover | Hero images, thumbnails | Fills space, crops excess |
contain | Product images, artwork | Preserves full image, may add padding |
scale-down | User uploads | Never enlarges |
crop | Precise crops | Uses gravity |
pad | Fixed aspect ratio | Adds background |
format: 'auto' // Recommended - negotiates best formatSupport: AVIF (Chrome 85+, Firefox 93+, Safari 16.4+), WebP (Chrome 23+, Firefox 65+, Safari 14+)
| Use Case | Quality |
|---|---|
| Thumbnails | 75-80 |
| Standard | 85 (default) |
| High-quality | 90-95 |
width/height ≤ 12000quality 1-100, dpr 1-3Implement caching and exponential backoff:
for (let i = 0; i < 3; i++) {
try { return await env.IMAGES.input(buffer).transform({...}).output(); }
catch { await new Promise(r => setTimeout(r, 2 ** i * 1000)); }
}Pre-process images before upload (max 100MB, 12000×12000px)
Supported: JPEG, PNG, GIF, WebP, AVIF, SVG
Verify API token has Cloudflare Images → Edit permission
| Resource | Limit |
|---|---|
| Max input size | 100MB |
| Max dimensions | 12000×12000px |
| Quality range | 1-100 |
| DPR range | 1-3 |
| API rate limit | ~1200 req/min |
const format = /image\/avif/.test(request.headers.get('Accept') || '') ? 'avif' : 'webp';// ❌ No caching - transforms every request
return env.IMAGES.input(buffer).transform({...}).output().response();
// ❌ cover without both dimensions
transform({ width: 800, fit: 'cover' })
// ✅ Always set both for cover
transform({ width: 800, height: 600, fit: 'cover' })
// ❌ Exposes API token to client
// ✅ Use Direct Creator Upload (patterns.md)// Check response headers
console.log('Content-Type:', response.headers.get('Content-Type'));
// Test with curl
// curl -I "https://imagedelivery.net/{hash}/{id}/width=800,format=avif"
// Monitor logs
// npx wrangler tail