Resize Parameters¶
fit - Resize Behavior¶
The fit parameter controls how the optimiser will scale, crop, or pad the image to meet the requested dimensions. Provide a single mode or a comma-separated sequence (for example, fit=facearea,crop,fill). Modes are attempted in order until one succeeds. Fits that rely on cropping automatically fall back to crop=centre when no explicit crop mode is supplied.
Default behaviour. The optimiser preserves the original aspect ratio and adjusts the unspecified dimension automatically. If both w and h are provided the shorter side is derived so the aspect ratio of the source image is maintained.
Downscales the image so that both dimensions fit within the requested bounding box without upscaling. Any remaining space is filled by extending edge pixels, producing a subtle letterbox effect.
Scales the image until both requested dimensions are met, then crops any excess area. Requires both h and w. Supports advanced crop modes such as faces, attention, entropy, edges, low, high, top, bottom, left, right, objects, and focalpoint.
Uses AI-assisted face detection to centre the crop on detected faces. Requires both h and w. If the face detector is unavailable the optimiser crops from the top-left, then falls back to the next fit in a sequence if provided.
Resizes the image to fit within the requested h and w while preserving aspect ratio. Excess canvas is filled using the fill options. Upscaling is permitted when required.
Behaves like fit=fill but never upscales the source image. Any remaining space after downscaling is padded with the configured fill colour.
Downscales the image so the largest dimension matches the requested size while maintaining aspect ratio. The original image is returned untouched if it is already smaller than requested.
Generates an output with the requested aspect ratio without ever upscaling. The optimiser crops to the desired ratio and returns the largest possible region that still fits inside the original image.
Directly scales to the provided w and h by resizing each axis independently. This mode can distort the image when both dimensions are supplied and is intended for deliberate stretching or when an exact pixel grid is required.
h - Height¶
h controls the height of the output image in pixels. If only a single dimension is specified, the aspect ratio will be maintained based on the aspect ratio of the input image.
Type: integer
Range: 1 - 8192 pixels
Default: Original height
w - Width¶
w controls the width of the output image in pixels. If only a single dimension is specified, the aspect ratio will be maintained based on the aspect ratio of the input image.
Type: integer
Range: 1 - 8192 pixels
Default: Original width
dpr - Device Pixel Ratio¶
dpr controls the device-pixel ratio. The dpr parameter causes the w and h parameters to be treated as device independent pixels (also known as "CSS pixels"). A 400×300 image at dpr=2 will actually be a 800×600 pixel image.
Type: float
Range: 0.1 - 8.0
Default: 1.0
When ch=dpr is enabled the optimiser will clone the negotiated DPR across the filter pipeline and advertise every available value in the Variants-06 header (for example, dpr=(1 2)). If no explicit dpr is provided, the derived value is still applied internally while leaving the caller-supplied options untouched.