Resize Modes

The r parameter controls how images are resized. Each mode handles aspect ratio and cropping differently.

Modes

fit (default)

Scales the image to fit inside the specified dimensions while maintaining the aspect ratio. The output may be smaller than the requested dimensions.

?w=400&h=300&r=fit

A 1600x1200 image becomes 400x300. A 1600x900 image becomes 400x225 (maintains 16:9).

scale

Resizes to the exact dimensions, distorting the image if the aspect ratio doesn't match.

?w=400&h=300&r=scale

The output is always exactly 400x300, regardless of the original aspect ratio.

fill

Covers the specified dimensions, cropping edges that extend beyond the bounds. The crop is centered by default.

?w=400&h=300&r=fill

A 1600x900 image is scaled and center-cropped to exactly 400x300.

crop

Extracts a region of the specified dimensions from the image. Supports compass gravity and facial gravity for positioning.

?w=400&h=300&r=crop&g=north

Both w and h are required for crop mode.

limit

Like fit, but never upscales. If the original is smaller than the requested dimensions, it is returned at its original size.

?w=2000&h=1500&r=limit

An 800x600 original stays 800x600 instead of being enlarged.

lfill

Like fill, but never scales the original up. The output covers as much of the requested dimensions as the original allows.

?w=2000&h=2000&r=lfill

An 800x600 original is center-cropped to 600x600 instead of being enlarged to 2000x2000.

thumb

Generates a thumbnail with smart cropping. When combined with facial gravity (g=face), it uses face detection to center the crop on the most prominent face.

?w=200&h=200&r=thumb&g=face

Both w and h are required for thumb mode.

Dimension Defaults

Single Dimension

When only one dimension is provided, the other is calculated to maintain the aspect ratio:

?w=400        # Height calculated proportionally
?h=300        # Width calculated proportionally

Format-Specific Limits

WebP and AVIF formats have a maximum dimension of 2000px. If the output would exceed this limit:

• In fit mode, the image is scaled down to fit within 2000px
• In crop or scale mode, an error is returned

Examples

# Fit a hero image into 1200x600
?w=1200&h=600&r=fit

# Exact 400x400 square avatar
?w=400&h=400&r=fill

# Crop from the top of the image
?w=800&h=400&r=crop&g=north

# Face-centered thumbnail
?w=150&h=150&r=thumb&g=face

# Responsive image that never exceeds its source resolution
?w=1600&r=limit&f=auto