Image Optimization

On-the-Fly Image Processing

Resize, convert, and optimize images at the edge without modifying your origin files.

How It Works

Image optimization is built into Edge CDN. Simply add query parameters to any image URL to transform it on-the-fly. Transformed images are cached at the edge for instant delivery.

# Original image
https://cdn.yoursite.com/images/hero.jpg

# Resized to 800px wide with WebP format
https://cdn.yoursite.com/images/hero.jpg?width=800&format=webp

# Thumbnail with quality adjustment
https://cdn.yoursite.com/images/hero.jpg?width=200&height=200&fit=cover&quality=80

Screenshot: Side-by-side comparison of original vs optimized image with file size reduction

Transformation Parameters

Resize

Parameter	Description	Example
`width`	Target width in pixels	`width=800`
`height`	Target height in pixels	`height=600`
`fit`	How to fit: cover, contain, fill, inside, outside	`fit=cover`

Format Conversion

Parameter	Description	Example
`format`	Output format: auto, webp, avif, jpeg, png	`format=webp`

Available Formats

auto Automatically selects the best format based on browser support (AVIF → WebP → JPEG)

avif Best compression, smallest files, supported by modern browsers

webp Great compression with wide browser support

jpeg Universal compatibility, good for photos

png Lossless, supports transparency

Recommended: Use format=auto

The auto format inspects the browser's Accept header and serves AVIF to browsers that support it, WebP to those that don't, and JPEG as a fallback. This ensures the smallest possible file size for each visitor.

Quality

Parameter	Description	Example
`quality`	Compression quality 1-100 (default: 80)	`quality=75`

Effects

Parameter	Description	Example
`blur`	Gaussian blur amount (0.3-1000)	`blur=10`
`sharpen`	Sharpen the image	`sharpen=true`
`grayscale`	Convert to grayscale	`grayscale=true`

Low Quality Image Placeholders (LQIP)

Generate tiny placeholder images for lazy loading. Show a blurred preview while the full image loads.

Parameter	Description	Example
`lqip=1`	Returns a tiny (~20px wide) blurred image	`?lqip=1`
`lqip=base64`	Returns a base64-encoded data URL (embed directly in HTML)	`?lqip=base64`
`lqip=blurhash`	Returns a BlurHash string (4-5 bytes, decode client-side)	`?lqip=blurhash`

# Tiny blurred placeholder (raw image)
https://cdn.yoursite.com/hero.jpg?lqip=1

# Base64 data URL (embed in src attribute)
https://cdn.yoursite.com/hero.jpg?lqip=base64

# BlurHash (returns JSON with hash, width, height)
https://cdn.yoursite.com/hero.jpg?lqip=blurhash
# → {"blurhash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj", "width": 4, "height": 3}

Animated GIF Support

Animated GIFs are processed with ImageMagick to preserve all animation frames. You can resize and convert animated GIFs without losing the animation.

Operation	Supported	Notes
Resize	Yes	All frames are resized, animation preserved
Convert to WebP	Yes	Animated WebP output, often smaller than GIF
Convert to PNG	Yes	Animated PNG (APNG) output
Quality adjustment	N/A	GIF is lossless — quality param is ignored for GIF output

# Resize animated GIF to 400px wide
https://cdn.yoursite.com/animation.gif?width=400

# Convert animated GIF to WebP (smaller file, keeps animation)
https://cdn.yoursite.com/animation.gif?width=400&format=webp

Common Use Cases

Responsive Images

Generate multiple sizes for srcset:

<img 
  src="https://cdn.yoursite.com/hero.jpg?width=1200&format=webp"
  srcset="
    https://cdn.yoursite.com/hero.jpg?width=400&format=webp 400w,
    https://cdn.yoursite.com/hero.jpg?width=800&format=webp 800w,
    https://cdn.yoursite.com/hero.jpg?width=1200&format=webp 1200w
  "
  sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
/>

Thumbnail Grid

Create consistent thumbnails:

https://cdn.yoursite.com/product-1.jpg?width=300&height=300&fit=cover&format=webp

Blur Placeholder (LQIP)

Generate a tiny blurred placeholder for lazy loading:

https://cdn.yoursite.com/hero.jpg?width=20&blur=10&quality=30

Supported Formats

JPEG

Input & Output

PNG

Input & Output

WebP

Input & Output

AVIF

Input & Output

GIF

Input only

SVG

Passed through

Default Settings

Configure default image optimization settings in the Configuration tab:

Default Format

Set to auto to serve AVIF/WebP/JPEG based on browser support

Default Quality

Set a global quality (1-100) applied when no URL param is specified

Path Rules

Override quality/format for specific paths like thumbnails

Performance

Image transformations happen at the edge and are cached after the first request:

<100ms

First transformation

<10ms

Cached delivery

~70%

Avg. size reduction

Next Steps

Caching

Learn about cache behavior

Analytics

Monitor image delivery stats