Transforms
Transformation Parameters
Size
width & height
Resize the image to the specified dimensions in pixels. Both width and height are required — you cannot specify only one.
| Type | Integer |
| Range | 1–4000 each |
| Default | Original dimensions (no resize) |
?width=600&height=600
?width=800&height=450
| 200×200 | 400×400 | 400×250 |
|---|---|---|
 |  |  |
Dimension budget: When
width+heightexceeds 4000, both are proportionally reduced to fit within the budget. This prevents abuse while preserving the requested aspect ratio.
pad
Add inner padding (in pixels) around the image. The target dimensions shrink by the padding amount, and the image is then re-extended with the fill color.
| Type | Integer |
| Range | 0+ |
| Default | 0 |
?width=800&height=800&pad=20&fill=solid&fill-color=ffffff
Useful for product images that need breathing room against a background.
Fit & Crop
fit
Controls how the image fits within the target width × height. Requires both width and height to be set.
| Value | Behavior |
|---|---|
cover | (default) Resize to fill the entire target area, cropping the overflow. Center-crop. |
crop | Alias for cover. |
contain | Resize to fit entirely within the target area. May leave empty space (letterboxing). |
fill | Resize to fit, then fill empty space with a solid color or blur. Combine with fill-color. |
?width=800&height=600&fit=contain
?width=800&height=600&fit=fill&fill=solid&fill-color=f5f5f5
cover (default) | contain | fill (white bg) |
|---|---|---|
 |  |  |
fill
When fit=fill, controls what fills the empty space.
| Value | Behavior |
|---|---|
solid | Fill with a solid color specified by fill-color. |
?width=800&height=800&fit=fill&fill=solid&fill-color=ffffff
fill-color
Hex color for the fill area. The # prefix is optional.
| Type | Hex color string |
| Default | White (ffffff) |
| Aliases | fill-color, fillColor |
?fill-color=f5f5f5
?fillColor=000000
Format & Quality
fm
Output image format. Automatic format negotiation is the recommended approach — omit fm and let the CDN + Accept header determine the optimal format.
| Value | MIME Type | Notes |
|---|---|---|
webp | image/webp | Recommended for web. ~25-35% smaller than JPEG at same quality. |
png | image/png | Lossless. Use for images with transparency. |
jpeg / jpg | image/jpeg | Universal compatibility. Good for photos. |
gif | image/gif | Returned as-is (no transformation applied to animated GIFs). |
?fm=webp
?fm=png
SVG files are always returned as-is without transformation, regardless of other parameters.
q
Output quality for lossy formats (JPEG, WebP).
| Type | Integer |
| Range | 1–100 |
| Default | 80 |
?q=85
?fm=webp&q=75
Quality guidelines:
| Use case | Recommended q | Notes |
|---|---|---|
| Thumbnails / listings | 70–75 | Small images tolerate lower quality |
| Product detail | 80–85 | Good balance of quality and size |
| Hero images / banners | 85–90 | Visible quality difference above 90 is negligible |
| Print / download | 95–100 | When file size doesn't matter |
Cache Control
c
Cache-buster parameter. Forces a new transformation and bypasses all cache layers.
| Type | String |
| Default | None |
?width=400&c=v2
⚠ Warning: Each unique
cvalue creates a new transformation that is not served from cache. This means:
- Slower load times — the image must be re-processed from the original instead of served from the disk cache.
- Higher cost — every uncached transformation is billed. Frequent cache-busting directly increases your monthly usage.
Avoid randomizing
cor using timestamps per request. If you need to update an image, re-upload it — the file will receive a new storage path and all caches will naturally serve the new version.
Cache Purge
We do not support manual cache purge. To ensure a fresh version of an image:
- Re-upload the image — this gives it a new storage path.
- Update the URL in your application to point to the new path.
All cache layers (edge CDN, memory, disk) will automatically serve the new image since the URL has changed. This is the fastest and most cost-effective way to update images.
Trim
trim
Auto-trim whitespace/solid borders from the image edges.
| Type | Boolean (presence-based) |
| Default | Off |
?trim
?trim=true
Useful for product images with inconsistent whitespace padding from suppliers.