Image Processor URL parameters

The ims query string carries the transformation Image Processor applies to an image. One string can hold a resize, a crop, and a chain of filters. The platform returns a derived image built from the source image on the origin, and the original is never modified. This page carries the syntax of each operation, the values its arguments accept, and a rendered result.

Resize

A resize sets the size of the derived image. The size goes in the query string as ?ims=WidthxHeight, in pixels, and either dimension can be left out.

Argument	Type	Required	Default	What it does
`Width`	Whole number of pixels, or `orig`	No	Calculated from `Height`, with the aspect ratio preserved	Sets the width of the derived image. `orig` keeps the original width.
`Height`	Whole number of pixels, or `orig`	No	Calculated from `Width`, with the aspect ratio preserved	Sets the height of the derived image. `orig` keeps the original height.

The arguments combine into five forms:

Form	Result
`?ims=WidthxHeight`	Resizes the image to that size. The image may be autocropped to fit.
`?ims=Widthx`	Sets the width and calculates the height, with the aspect ratio preserved.
`?ims=xHeight`	Sets the height and calculates the width, with the aspect ratio preserved.
`?ims=WidthxOrig`	Sets the width and keeps the original height, with no autocrop.
`?ims=fit-in/WidthxHeight`	Fits the image inside the area, with the aspect ratio preserved and no enlargement.

When both Width and Height are set, the image may be cropped automatically to fit the requested size. The crop is centered, and it runs vertically or horizontally depending on how the original dimensions fit the requested ones.

fit-in never enlarges the image: when the area is larger than the image dimensions, the image keeps its original size. Both dimensions are optional, and the image grows until it reaches the width or the height, whichever bound comes first. For example, ?ims=fit-in/400x400 on a landscape image stops at 400 pixels of width, and the height lands below 400.

The image below carries ?ims=400x400, which resizes with autocrop:

The source photograph resized to a 400 by 400 pixel square, centered and autocropped from the landscape original

Crop

A crop keeps the rectangle between two coordinates of the source image and discards the rest. The coordinates go in the query string as ?ims=AxB:CxD, in pixels.

Argument	Type	Required	What it does
`AxB`	Coordinate pair in pixels	Yes	The upper-left corner where the crop starts.
`CxD`	Coordinate pair in pixels	Yes	The bottom-right corner where the crop ends.

For example, ?ims=430x20:910x730 starts the crop at the coordinate 430x20 pixels and ends it at the coordinate 910x730 pixels.

The image below carries that query:

The source photograph cropped to the rectangle between the coordinates 430x20 and 910x730 pixels

Rotation

Rotation turns the image to the left by a fixed number of degrees. The angle goes in the query string as ?ims=filters:rotate(Angle).

Argument	Type	Required	What it does
`Angle`	One of `0`, `90`, `180`, `270`, `360`	Yes	The number of degrees the image turns to the left.

Value	Result
`0`	No rotation.
`90`	Turns the image 90 degrees to the left.
`180`	Turns the image 180 degrees to the left.
`270`	Turns the image 270 degrees to the left.
`360`	No rotation.

A value that is not on this list does not rotate the image.

An image with an aspect ratio of 1:1 keeps its dimensions. A non-square image rotated by 90 or 270 has its height and width values swapped.

The image below carries ?ims=filters:rotate(270):

The source photograph turned 270 degrees to the left, so the landscape original renders as a portrait image

Quality

The quality filter sets how much the derived image is compressed, which changes the file size and the transfer time. The value goes in the query string as ?ims=filters:quality(value).

Argument	Type	Required	What it does
`value`	Whole number, `0` to `100`	Yes	The level of quality applied to the image.

The recommended value is 85. It optimizes the image with no noticeable loss of visual quality.

A request for a resolution larger than the original does not enlarge the image. The image is displayed at the highest possible resolution.

The image below carries ?ims=filters:quality(15), far below the recommended value:

The source photograph delivered with a quality value of 15

Watermark

A watermark places a second image over the source image. The filter goes in the query string as ?ims=filters:watermark(WatermarkURL,X,Y,Alpha) and takes four arguments, in that order.

Argument	Type	Required	What it does
`WatermarkURL`	URL of an image	Yes	The image placed over the source image. Parentheses in the URL are encoded as `%28` for `(` and `%29` for `)`.
`X`	Whole number of pixels, `center`, or `repeat`	Yes	The horizontal position. A positive number offsets from the left edge to the right edge, and a negative number from the right edge to the left edge. `center` centers the watermark horizontally, and `repeat` fills the image horizontally with copies of it.
`Y`	Whole number of pixels, `center`, or `repeat`	Yes	The vertical position. A positive number offsets from top to bottom, and a negative number from bottom to top. `center` centers the watermark vertically, and `repeat` fills the image vertically with copies of it.
`Alpha`	Whole number, `0` to `100`	Yes	The transparency of the watermark. `0` is completely opaque and `100` is completely transparent.

For example, ?ims=filters:watermark(https://example.com/watermark-image.png,-25,-10,50) applies the watermark 25 pixels left of center and 10 pixels below center, at 50% transparency.

The image below carries a watermark centered on both axes, at 50% transparency:

Format conversion

Format conversion returns the image in a different file format. The target format goes in the query string as ?ims=filters:format(ImageFormat).

Argument	Type	Required	What it does
`ImageFormat`	One of `webp`, `avif`, `jpeg`, `gif`, `png`	Yes	The file format of the derived image.

Converting to WEBP or AVIF requires the request to carry an Accept header that names the format:

Output format	Header the request must carry
`webp`	`Accept: image/webp`
`avif`	`Accept: image/avif`

To add that header with a rule, refer to Configure Image Processor.

The image below carries ?ims=filters:format(gif):

The source PNG photograph converted to GIF format

Fill

Fill creates a derived image larger than the original and paints the area around it with one color. The filter goes in the query string as ?ims=fit-in/WidthxHeight/filters:fill(Color).

Argument	Type	Required	What it does
`Width`	Whole number of pixels	No	The width of the area the image fits into. Omit it and the width is calculated from `Height`, with the aspect ratio preserved.
`Height`	Whole number of pixels	No	The height of the area the image fits into. Omit it and the height is calculated from `Width`, with the aspect ratio preserved.
`Color`	Hexadecimal color value, or the named value `gray`	Yes	The color painted around the image.

Fill uses the same fit-in behavior as a resize: the image keeps its aspect ratio, and an area larger than the image does not enlarge it. The space left over is what the color fills.

For example, ?ims=fit-in/300x400/filters:fill(008080) fits the image into an area of 300 by 400 pixels and paints the space around it with the color 008080.

The image below carries ?ims=fit-in/400x400/filters:fill(gray):

The source photograph fitted into an area of 400 by 400 pixels, with gray filling the space above and below it

Combined filters

One ims string can carry more than one filter. The filters go inside a single filters: group, and a : separates each one from the next, as in filters:filter1(arg1):filter2(arg2).

Segment	Example	What it does
Resize segment	`fit-in/400x400`	Sets the size of the derived image. It comes first, and a `/` separates it from the filter group.
Filter group	`filters:fill(00ffff):quality(100)`	Carries one or more filters, opened by `filters:`.
Filter separator	`:`	Separates one filter from the next inside the group.

For example, ?ims=fit-in/400x400/filters:fill(00ffff):quality(100) fits the image into an area of 400 by 400 pixels. It then paints the space around the image with the color 00ffff and applies a quality value of 100.

The image below carries that query:

The source photograph fitted into an area of 400 by 400 pixels, with the color 00ffff filling the space above and below it, at quality 100

Supported input formats

Image Processor accepts these source image formats:

JPEG
GIF
PNG
BMP
ICO
WEBP
AVIF

WEBP and AVIF depend on the browser. For the browsers that support each one, refer to WEBP browser support and AVIF browser support.

Image Processor also converts a format with no ims parameter in the request. It detects whether the browser supports WEBP and converts the image when possible, and BMP images are converted to JPEG or WEBP depending on the same browser support. For more information, refer to Image delivery.

Position of the ims parameter

The ims= query string parameter must be the last parameter in the URL. When another query string parameter follows ims=, the request may return a 504 error.

URL	Position of `ims=`
`example.com/image.jpeg?ts=1234&ims=1000x1000`	Last. The request is valid.
`example.com/image.jpeg?ims=1000x1000&ts=1234`	Not last. The request may return a `504` error.

Image delivery

The path a request takes through the module, and how a derived image is cached.

Image Processor settings

The fields and interfaces that turn the module on for an application.

Limits

The size and dimension ceilings that bound the values in these tables.

Configure Image Processor

Turn the module on, add the rules that process images, and set the cache.