Resize images to specific dimensions while automatically maintaining aspect ratio. Generate responsive images for different screen sizes, create consistent thumbnails, or optimize oversized images for faster loading.Documentation Index
Fetch the complete documentation index at: https://docs.bunny.net/llms.txt
Use this file to discover all available pages before exploring further.
When both width and height are specified, Bunny Optimizer automatically uses
whichever produces the smaller image while preserving aspect ratio.
Parameters
Resize the image to match the given width in pixels while maintaining aspect
ratio.Unit: pixels
Resize the image to match the given height in pixels while maintaining aspect
ratio.Unit: pixels
Allows the image to be enlarged beyond its original dimensions.Values:
off, resamplingDefault: offThe default upscaling behaviour can be changed to
resampling (so you don’t need to specify the query parameter each time)
in the Pull Zone config via the Update Pull Zone API by setting
OptimizerEnableUpscaling to true.How it works
When you apply width or height parameters, Bunny Optimizer:- Calculates the new dimensions based on your specified value
- Maintains the original aspect ratio automatically
- Resizes the image proportionally
- Delivers the optimized result from the edge cache
Usage
Width-based resizing
Specify a width to resize the image proportionally. The height adjusts automatically to maintain aspect ratio. Ideal for creating responsive images where you need consistent widths across different screen sizes or generating multiple sizes forsrcset attributes.
| Original | width=300 |
|---|---|
 |  |
Smaller width
| Original | width=150 |
|---|---|
|  |
Height-based resizing
Specify a height to resize the image proportionally. The width adjusts automatically to maintain aspect ratio. Perfect for layouts where vertical space is constrained, such as horizontal carousels, fixed-height containers, or product listing grids.| Original | height=150 |
|---|---|
|  |
Smaller height
| Original | height=100 |
|---|---|
|  |
Combining width and height
When both width and height are specified, Bunny Optimizer intelligently selects whichever produces the smaller image while preserving aspect ratio. This ensures images fit within specific layout constraints while maintaining their original proportions.| width=100 | height=75 | width=100&height=75 (result) |
|---|---|---|
 |  |  |
height=75 produces a smaller image (113×75) compared to width=100 (100×67), so the height parameter takes effect.
Combining with other transformations
Resizing works seamlessly with other Bunny Optimizer parameters. Reduce bandwidth by combining with quality adjustments, convert formats for better compression, or apply filters to enhance resized images:Resize with quality adjustment
Resize with format conversion
Resize with sharpen filter
Crop operations have priority over width
or height parameters. If any crop is defined in the query, it will be applied
first, then resizing is applied to the cropped result.
Upscaling
By default, Bunny Optimizer does not enlarge images beyond their original size. Useupscaling=resampling to permit standard resampling-based upscaling. When enabled, upscaling is limited to an output size of 24 megapixels while preserving aspect ratio.
This limit applies only when the result would be larger than the original image. If the original image is already larger than 24 megapixels, it is not reduced unless another transformation requires it.
Upscale 1024x512 image to 2048x1024
Upscale 1024x512 image to 1536x768
Downscale 1024x512 image to 512x256. No upscaling (target is smaller than original).