Sizing and scaling
The Media Delivery API lets you resize an image by setting a width, a height, or an upper bound on either, then control how it fills the space you have asked for. Scale mode decides what happens when the source and target aspect ratios differ, and point of interest decides which part of the image survives a crop.
Base URL pattern
The parameters on this page are appended to a Dynamic Media image URL. For the URL pattern and how parameters chain together, see the Media Delivery API guide.
SizingLink copied!
The parameters here work in two pairs. w and h set an exact output size, while maxW and maxH set a ceiling that only applies when a request exceeds it. Both pairs preserve the aspect ratio - changing the shape of an image is the job of scale mode.
Tip
These parameters resize at delivery time without altering the master asset. To resize the asset itself as part of an automated workflow, use the Adjust image size action in Workforce flows.
w - WidthLink copied!
Sets the output width in pixels. If only w is specified, height is calculated automatically to preserve the aspect ratio. See the height example below.
h - HeightLink copied!
Sets the output height in pixels. If only h is specified, width is calculated automatically to preserve the aspect ratio. Set a width below to override the automatic calculation; clear it to return to aspect-ratio scaling.
Tip
Add a width above and see how the URL updates - a width parameter is appended, chained with a &.
maxW - Maximum widthLink copied!
Sets the maximum width for the returned image. Requests above it are clamped, with the height then following the aspect ratio from the clamped width. Can also be configured at the account level.
ExampleLink copied!
Requests 2000px from the 6000×4000 source; the output is clamped to 1200px wide, with the height following the aspect ratio:
maxH - Maximum heightLink copied!
Sets the maximum height for the returned image. Requests above it are clamped, with the width then following the aspect ratio from the clamped height. Can also be configured at the account level.
ExampleLink copied!
Requests 2000px tall; the output is clamped to 1200px, and the width follows the aspect ratio (1800px for this source):
Scale modeLink copied!
If you ask for a width and height that don't match the shape of the original image - for example, a square from a landscape photo - the image can't fill that space exactly. These parameters let you choose what happens - whether it's cropped or stretched to fit, which part of it is kept, and how it's redrawn at the new size.
Tip
sm - Scale modeLink copied!
Controls how the image is positioned or cropped when it does not fit exactly to the requested width and height.
| Value | Description |
|---|---|
c | Crop to fit |
s | Stretch |
tl | Top left |
tc | Top center |
tr | Top right |
ml | Middle left |
mc | Middle center |
mr | Middle right |
bl | Bottom left |
bc | Bottom center |
br | Bottom right |
aspect | Maintain aspect ratio - ratio needs to be specified for example sm=aspect&aspect=16:9 |
edge | Resize to a specified edge - see sm=edge |
clamp | Fit within area without padding - see sm=clamp |
This example requests a portrait window from a landscape scene, so every mode must crop or stretch - switch between the corner values to watch the crop move across the scene:
Example - maintain aspect ratioLink copied!
sm=edge - Resize to edgeLink copied!
Resizes the image so that a specific edge matches a target length. Requires resize.edge and resize.edge.length.
| Parameter | Values | Description |
|---|---|---|
resize.edge | w, h, largest, smallest | Which edge to target |
resize.edge.length | Integer (pixels) | Target length in pixels |
sm=clamp - Clamp to boundsLink copied!
Fits the image into the specified width and height while maintaining the aspect ratio and avoiding any padding.
scaleFit - Scale fit modeLink copied!
Specifies how to position the crop area when using sm.
| Value | Description |
|---|---|
center | Default |
poi | Crop using the point of interest focal point |
See scaleFit=poi in action in the poi example below.
poi - Point of interestLink copied!
Defines a focal point for cropping. Takes four comma-separated values representing the focal region as percentages of the image dimensions.
| Component | Description |
|---|---|
x | Left edge of the focal point as a percentage of image width |
y | Top edge of the focal point as a percentage of image height |
w | Width of the focal point as a percentage of image width |
h | Height of the focal point as a percentage of image height |
Tip
The source image is 1028 x 685 pixels - try playing with scaleFit at these settings too.
filter - Resize algorithmLink copied!
The resampling algorithm used when resizing the image.
| Value | Description |
|---|---|
q | Quadratic |
s | Sinc |
l | Lanczos (default) |
p | Point |
c | Cubic |
h | Hermite |
Resampling differences are most visible when fine patterns are downscaled hard - compare the algorithms on the checked and striped fabric:
upscale - Upscale behaviourLink copied!
Controls whether the image can be scaled larger than the original.
| Value | Description |
|---|---|
true | Allow upscaling |
false | Do not upscale |
padd | Draw the image, unscaled, on a canvas of the requested size. Specify both w and h to define the canvas - with one dimension the canvas matches the image and no padding appears. Alignment is set via sm; background colour via bg |
Example - padd with a defined canvasLink copied!
Both dimensions define the canvas; the 1280×853 original is drawn unscaled and centred, with the background colour filling the remainder: