Image Delivery
Overview
Every image uploaded to a Purple Hub is served through Tachyon, an on-the-fly image resizing and optimization CDN based on humanmade/tachyon. Instead of pre-generating a fixed set of thumbnail sizes on upload, Tachyon resizes, crops and compresses the original image the first time a given size is requested, then caches that result so every subsequent request is served instantly from the CDN.
The hub rewrites image src and srcset attributes automatically, so most editors and integrations never have to think about this. It becomes relevant when you're building a custom frontend, app, or headless integration and need to request a specific image size yourself.
How it works
- Every uploaded media file gets a canonical URL under the hub's uploads path, e.g. https://example.com/wp-content/uploads/2026/08/photo.jpg.
- Appending query parameters (?w=600, ?resize=300,200, ...) to that URL requests a resized/transformed variant.
- On the first request for a given combination of parameters, the image is fetched, transformed, and cached. All following requests for that exact URL are served directly from the cache with a 1 year Cache-Control header.
- If the source file isn't a supported image type, or no recognized parameters are present, the original file is served unmodified.
Basic usage
Append one or more query parameters to any image URL on the hub:
https://example.com/wp-content/uploads/2026/08/photo.jpg?w=600
https://example.com/wp-content/uploads/2026/08/photo.jpg?resize=300,200&crop_strategy=smart
https://example.com/wp-content/uploads/2026/08/photo.jpg?fit=800,600&quality=70Supported source formats are jpg, jpeg, png, gif and webp. Other file types (e.g. svg) are passed through unchanged.
Parameters
Resizing
Parameter | Description | Example |
|---|---|---|
`w` | Resize to this width (px), preserving aspect ratio. Never upscales. | `?w=600` |
`h` | Resize to this height (px), preserving aspect ratio. Never upscales. | `?h=400` |
`resize` | Resize and crop to fill an exact `width,height` box. Crops from the center by default — pair with `gravity` or `crop_strategy` to control what's kept. | `?resize=300,200` |
`fit` | Resize to fit inside a `width,height` bounding box without cropping or upscaling. Aspect ratio is preserved, so the result may be smaller than the box on one axis. | `?fit=800,600` |
`lb` | Letterbox: like `fit`, but pads the image to the exact `width,height` box using a background color, instead of leaving it smaller. Combine with `background`. | `?lb=800,600` |
`crop` | Crop the source image before any resize is applied, as `left,top,width,height`. Values are treated as a percentage of the original image unless suffixed with `px`. | `?crop=10,10,50,50` (percent) or `?crop=100px,100px,400px,300px` |
Crop focus
Parameter | Description | Example |
|---|---|---|
`gravity` | Anchors which part of the image is kept when `resize` crops it. One of `north`, `northeast`, `east`, `southeast`, `south`, `southwest`, `west`, `northwest`, `center`. | `?resize=400,400&gravity=north` |
`crop_strategy` | Alternative to `gravity` for `resize`. `smart` uses content-aware cropping to keep the most visually interesting region; `entropy` and `attention` are additional Sharp-based strategies. | `?resize=400,400&crop_strategy=smart` |
Output quality
Parameter | Description | Example |
|---|---|---|
`quality` | JPEG/WebP compression quality, `0`–`100`. Defaults to `82`, automatically reduced for high `zoom` values to control file size. | `?w=600&quality=70` |
`webp` | Force the output to WebP regardless of the source format. | `?w=600&webp=1` |
`zoom` | Multiplies the requested dimensions, for serving higher-density (retina) images at the same layout size. | `?w=600&zoom=2` |
`background` | Background color used to pad images with `lb`. Defaults to `black`. | `?lb=800,600&background=white` |
Examples
Resize to a fixed width, preserving aspect ratio:
https://example.com/wp-content/uploads/2026/08/photo.jpg?w=800Crop to a square thumbnail, keeping the most interesting part of the image:
https://example.com/wp-content/uploads/2026/08/photo.jpg?resize=400,400&crop_strategy=smartFit inside a bounding box without cropping:
https://example.com/wp-content/uploads/2026/08/photo.jpg?fit=1200,800Serve a 2x/retina variant at reduced quality to manage file size:
https://example.com/wp-content/uploads/2026/08/photo.jpg?w=400&zoom=2&quality=65Force WebP output:
https://example.com/wp-content/uploads/2026/08/photo.jpg?w=600&webp=1Caching and performance
- Each unique combination of source image and query parameters is processed once and cached; repeat requests for the same URL are served from cache.
- Cached variants are served with Cache-Control: max-age=31536000 (1 year), so they're also cached by browsers and any CDN/proxy in front of the hub.
- Changing any parameter (including their order) produces a distinct cached variant.
Error handling
Tachyon is designed to fail safe: if anything about a request can't be honored, it falls back to serving the original file unmodified rather than returning an error.
Situation | Behavior |
|---|---|
No recognized query parameters are present | Request is not processed; the original file is served as-is. |
A single parameter has an invalid value (e.g. `quality=abc`) | That parameter is dropped; any other valid parameters on the same request still apply. |