Image Transforms

On-demand image resizing, cropping, and format conversion with CDN caching.

URL Format

text

/api/img/{asset_id}?w=800&h=600&fit=cover&format=webp&q=80

Parameters

Param	Type	Default	Description
w	int	original	Target width in pixels
h	int	original	Target height in pixels
fit	string	cover	cover, contain, fill, inside, outside
format	string	auto	webp, jpeg, png, avif (auto = browser Accept header)
q	int	80	Quality 1-100
blur	float	0	Gaussian blur radius (0.3-1000)
fp-x	float	0.5	Focal point X (0.0-1.0)
fp-y	float	0.5	Focal point Y (0.0-1.0)

Examples

Thumbnail (400px wide, WebP)

/api/img/42?w=400&format=webp

Square crop (profile avatar)

/api/img/42?w=200&h=200&fit=cover

Hero banner (full width, high quality)

/api/img/42?w=1600&h=400&fit=cover&q=90&format=webp

Blurred placeholder

/api/img/42?w=20&blur=10&q=30

Focal point crop (face on the right)

/api/img/42?w=800&h=600&fit=cover&fp-x=0.8&fp-y=0.3

In HTML

html

<!-- Responsive image with srcset -->
<img
  src="/api/img/42?w=800&format=webp"
  srcset="
    /api/img/42?w=400&format=webp 400w,
    /api/img/42?w=800&format=webp 800w,
    /api/img/42?w=1200&format=webp 1200w
  "
  sizes="(max-width: 600px) 400px, 800px"
  alt="Description"
  loading="lazy"
/>

Caching

Transformed images are cached in two layers:

Application cache — Transform results are stored in R2/S3 with a cache key based on parameters. Subsequent requests for the same transform return a 302 redirect to the cached file.
CDN cache — Cloudflare (or your CDN) caches the redirect target. Set cache rules for /api/img/* paths.

BlurHash

For instant image placeholders, request a tiny blurred version (?w=20&blur=10&q=30) and display it while the full image loads. The React SDK's MediaImage component handles this automatically.

← Video Streaming Private Assets