Resize, crop & fit

Set w and h to define the output box. fit controls how the source fills that box; gravity, crop, or fp controls where the crop lands when using fit=cover.

Center vs smart gravity side by side — Off-centre hero — `gravity=center` (left) vs `gravity=smart` (right).

Center crop vs focal point crop — Manual focal point — `gravity=center` (left) vs `fp=x,y` (right).

Hero cropped with rect and aspect ratio — Source crop + 16:9 — `?rect=8%,12%,84%,76&w=1200&ar=16:9`.

Product photo at 21:9 aspect ratio — Wide banner — `?w=1200&ar=21:9&fit=cover`.

Source crop and aspect ratio

Use rect to crop the source before resize/gravity:

?rect=120,80,800,600&w=900&h=600&fit=cover
?rect=10%,15%,80%,70&w=1200&ar=16:9

When only one output dimension is set, ar derives the other (w=1200&ar=16:9 → 675px tall).

Fit strategies

`fit`	Behaviour
`cover` (default)	Fills the box, cropping overflow. Pairs with `gravity` for smart cropping.
`contain`	Fits inside the box, padding with transparency.
`fill`	Stretches to fill the box.
`inside`	Scales down without enlarging.
`outside`	Scales to cover on the smallest axis.

Smart cropping

Mode	When to use
`gravity=auto` (default)	Fast saliency — best default for most photos.
`gravity=smart` / `crop=smart`	Content-aware scoring for off-centre subjects.
`gravity=face`	Centres crop on detected faces; falls through to smart if none found.
`gravity=entropy`	Texture-heavy sources with no obvious subject.
`fp=x,y`	Hand-picked focal point — cheapest and deterministic at scale.

?w=600&h=600&fit=cover&gravity=smart
?w=600&h=400&fit=cover&fp=0.3,0.4
?w=600&h=600&fit=cover&gravity=face

Uncropped hero source image — Full-width source before any crop.

Face-aware crop on a portrait — `gravity=face` portrait crop.

Entropy crop on a texture — `gravity=entropy` texture crop.

For focal-point workflows, palette extraction, and /api/images/analyze, see Smart cropping & image analysis.

Focal zoom (`fp-z`)

fp-z (alias fpZ) zooms toward the focal point by shrinking the crop window before resize. Range 1–10; higher values tighten the crop.

?w=900&h=900&fit=cover&fp=0.35,0.4&fp-z=2

Pair with fp=x,y from manual focal points or /api/images/analyze for art-directed thumbnails that stay centred on the subject at smaller sizes.

Device pixel ratio

dpr multiplies output pixels while preserving layout size in CSS. Render a 400px slot with w=400&dpr=2 to receive an 800px asset for Retina displays. Valid range: 1–4.

?w=400&h=300&dpr=2

When to use dpr vs srcset width descriptors

Technique	Example	Best for
`srcset` + `sizes`	`320w, 640w, 960w, 1280w`	`<ConvertlyImage>`, most responsive layouts — see Responsive images
`dpr=2` with fixed `w`	`w=600&dpr=2`	Density descriptors with Client Hints layouts
Client Hints	`ch=Width,Dpr`	Browser sends width + DPR — see Client Hints guide

You do not need both dpr=2 and 1200w in the same srcset entry — pick one model per image.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Source crop and aspect ratio

Fit strategies

Smart cropping

Focal zoom (`fp-z`)

Device pixel ratio

​Source crop and aspect ratio

​Fit strategies

​Smart cropping

​Focal zoom (fp-z)

​Device pixel ratio

Source crop and aspect ratio

Fit strategies

Smart cropping

Focal zoom (`fp-z`)

Device pixel ratio