Transformations Overview
Transform images on the fly using URL query parameters.
Tuzzle transforms images on delivery by appending query parameters to the CDN URL. No pre-processing needed.
https://cdn.tzzl.io/{space}/{file}?w=400&h=300&f=webp&q=80&r=fit&g=center
Query Parameters
| Parameter | Name | Values | Default |
|---|---|---|---|
w | Width | Pixels (integer) | Original width |
h | Height | Pixels (integer) | Original height |
r | Resize mode | scale, fit, fill, crop, thumb | fit |
g | Gravity | center, north, south, east, west, northeast, northwest, southeast, southwest, face, faces, eyes, auto | center |
f | Format | jpeg, png, webp, avif, tiff, gif, pdf | Auto-negotiated |
q | Quality | 1-100 | Dynamic based on size |
How It Works
- A request hits the CDN with transformation parameters
- The CDN checks for a cached version
- If cached, the variant is served immediately
- If not cached, the CDN fetches the original, applies transformations, caches the result, and returns it
- Subsequent identical requests are served from cache
Auto-Format Negotiation
When no f parameter is specified, Tuzzle reads the Accept header and selects the best format:
- If the client supports AVIF, serves AVIF
- Otherwise if WebP is supported, serves WebP
- Falls back to the original format
Dynamic Quality
When q is not specified, quality is automatically selected based on the output image dimensions:
| Largest Dimension | Quality |
|---|---|
| Up to 1000px | 90 |
| 1000-2500px | 85 |
| 2500-5000px | 80 |
| 5000-7500px | 75 |
| 7500-10000px | 70 |
| Over 10000px | 60 |
Two-Phase Validation
Transformations are validated in two phases:
- Pre-meta validation: Checks parameter formats before fetching the image (e.g., valid numbers, valid resize mode)
- Post-meta validation: Checks parameters against the actual image metadata (e.g., crop dimensions require both width and height, format pixel limits)
Validation errors return a 422 status with details in the x-tzzl-errors response header. Non-blocking warnings are returned in x-tzzl-warnings.
Response Headers
Transformed responses include these custom headers:
| Header | Description |
|---|---|
x-image-width | Original image width |
x-image-height | Original image height |
x-blurhash | Blurhash placeholder string |
x-tzzl-warnings | JSON array of transformation warnings |
x-tzzl-errors | JSON array of validation errors (on 422) |
cache-control | public, max-age=2592000 (30 days) |