Resize & Fit
Width and Height
Use w and h to set the output dimensions in pixels.
| Param | Type | Max | Description |
|---|---|---|---|
w | integer | 8192 | Output width in pixels |
h | integer | 8192 | Output height in pixels |
You can specify just w, just h, or both together.
Only width
The height is calculated automatically to preserve the aspect ratio.
/w=400/https://example.com/photo.jpg
A 1200x800 source image becomes 400x267.
Only height
The width is calculated automatically to preserve the aspect ratio.
/h=300/https://example.com/photo.jpg
A 1200x800 source image becomes 450x300.
Both width and height
When both are specified, the fit parameter controls how the image is resized to fill the given box.
/400x400/https://example.com/photo.jpg
Fit Modes
The fit parameter controls behavior when both w and h are provided.
| Value | Description |
|---|---|
contain | Scale to fit within the box, preserving aspect ratio. No cropping. Dimensions may be smaller than requested. (default) |
cover | Scale to fill the entire box, preserving aspect ratio. May crop edges. Output is always the exact requested size. |
crop | Hard crop to the exact dimensions without scaling. No aspect ratio preservation. |
contain (default)
The image is scaled down so it fits entirely within the w x h box. The output image will not exceed either dimension, and no pixels are cropped.
/400x400,contain/https://example.com/photo.jpg
A 1200x800 source image becomes 400x267 - it fits within the 400x400 box while keeping the full image visible.
contain is the default fit mode. If you omit fit, PreviewProxy uses contain.
cover
The image is scaled up or down so it completely fills the w x h box. Excess pixels along one edge are cropped. The output is always exactly w x h.
/400x400,cover/https://example.com/photo.jpg
A 1200x800 source image becomes 400x400 - cropped to a square filling the box.
Use cover when you need uniform thumbnail sizes, such as product grids or avatar images.
crop
The image is hard-cropped to the exact dimensions starting from the top-left, without any scaling. Use this when you need a precise pixel cutout.
/400x400,crop/https://example.com/photo.jpg
A 1200x800 source image becomes 400x400 - the top-left 400x400 pixels of the original, with no resizing applied.
crop does not scale the image. If the requested dimensions are larger than the source, the output will be clamped to the source dimensions.
Dimension Limits
The maximum value for both w and h is 8192 pixels. Requests exceeding this limit will be rejected.
Examples Summary
| Source | Params | Output | Notes |
|---|---|---|---|
| 1200x800 | w=400 | 400x267 | Width only, height scaled proportionally |
| 1200x800 | h=300 | 450x300 | Height only, width scaled proportionally |
| 1200x800 | 400x400 | 400x267 | Both, contain (default) - fits within box |
| 1200x800 | 400x400,contain | 400x267 | Explicit contain - same as above |
| 1200x800 | 400x400,cover | 400x400 | Fills box, crops edges |
| 1200x800 | 400x400,crop | 400x400 | Hard crop from top-left, no scaling |