Skip to content
Console

Resize images

All examples below use this original image: https://demo.bitiful.com/girl.jpeg

Parameters

ParameterMeaningDefaultValues
wTarget width–Pixels (up to 10000), or a percentage such as 50%
hTarget height–Same as above
dprAdditional scale factor; the target width and height are multiplied by this value1Greater than 0, up to 10
modeResize mode; see the table belowcropcrop / clip / fill / scale / adapt
posPosition to keep when cropping; see belowcenterA preset position, custom coordinates, or smart crop
fillPadding method; applies only when mode=fillsolidsolid / blur / dominant / auto
bgBackground color used for paddingWhiteHex color

In URLs, write % as %25, for example w=50%25.

Resize modes

modeBehaviorOutput size
cropResizes proportionally, then crops off the excessExactly w × h
clipResizes proportionally to fit within a w × h box, without croppingNo larger than w × h
fillResizes proportionally to fit within the box, then pads to the target sizeExactly w × h
scaleStretches to the target size without preserving the aspect ratioExactly w × h
adaptChooses automatically: uses crop when little would be cropped, otherwise fillExactly w × h
  • If you specify only one of w or h, the image is always resized proportionally.
  • If you specify both w and h without mode, crop is used.

Padding methods

When mode=fill, fill determines what fills the empty area:

fillEffect
solidThe solid color set by bg
blurAn enlarged, blurred copy of the original image as the background
dominantThe dominant color of the original image
autoContent-aware: extends the edges naturally when they are a solid color or a smooth gradient; otherwise uses a blurred background

Crop position

When mode=crop, pos determines which part of the image to keep.

FormValues
Nine-gridtop-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right
Offset from centertop-center, bottom-center, left-center, right-center: starts from the center and shifts toward that direction
Custom coordinatesx,y, each 0 to 1 or 0% to 100%, such as 0.25,0.75
Smart cropsmart (face and auto are equivalent)

Smart crop

pos=smart detects faces, people, cats and dogs, and salient subjects in the image and automatically picks the crop window that keeps them most intact. When faces are present, it places them naturally toward the upper part of the frame.

  • Detection runs only when the aspect ratios of the original and the target differ by more than 25%; otherwise the image is center-cropped.
  • Animated images are not analyzed and are center-cropped.

We recommend pos=smart whenever you need to crop images of varying aspect ratios to a uniform ratio, such as avatars, product images, and feed covers.

Examples

Demo: width only, w=200, proportional resize
Demo: height only, h=200, proportional resize
Demo: both w=200 & h=200 (default mode=crop, pos=center)
Demo: w=200 & h=200, mode=clip fits proportionally within the box
Demo: w=200 & h=200, dpr=0.5 outputs 100 × 100
Demo: w=200 & h=200, pos=top keeps the top
Demo: w=200 & h=200, pos=bottom keeps the bottom
Demo: w=200 & h=200, pos=smart smart crop
Demo: w=300 & h=200, mode=fill padded with a blurred background