# Image Processor URL parameters The `ims` query string carries the transformation [Image Processor](/en/documentation/platform/applications/#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](/assets/docs/images/image-processor/Image_Processor_1.png?ims=400x400) --- ## 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](/assets/docs/images/image-processor/Image_Processor_1.png?ims=430x20:910x730) --- ## 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. > **Caution** > > 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](/assets/docs/images/image-processor/Image_Processor_1.png?ims=filters:rotate\(270\)) --- ## 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. > **Note** > > 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](/assets/docs/images/image-processor/Image_Processor_1.png?ims=filters:quality\(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: ![The Azion logo placed over the source photograph, centered on both axes at 50% transparency](/assets/docs/images/image-processor/Image_Processor_1.png?ims=filters:watermark\(https://www.azion.com/assets/docs/images/azion-logo.png,center,center,50\)) --- ## 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](/en/documentation/guides/application-performance/delivery-optimization/process-images/). The image below carries `?ims=filters:format(gif)`: ![The source PNG photograph converted to GIF format](/assets/docs/images/image-processor/Image_Processor_1.png?ims=filters:format\(gif\)) --- ## 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](/assets/docs/images/image-processor/Image_Processor_1.png?ims=fit-in/400x400/filters:fill\(gray\)) --- ## 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](/assets/docs/images/image-processor/Image_Processor_1.png?ims=fit-in/400x400/filters:fill\(00ffff\):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](https://caniuse.com/webp) and [AVIF browser support](https://caniuse.com/avif). 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](/en/documentation/platform/applications/image-processor/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. | --- ## Related resources - [Image delivery](/en/documentation/platform/applications/image-processor/image-delivery.md): The path a request takes through the module, and how a derived image is cached. - [Image Processor settings](/en/documentation/platform/applications/image-processor/settings.md): The fields and interfaces that turn the module on for an application. - [Limits](/en/documentation/platform/applications/limits.md#image-processor): The size and dimension ceilings that bound the values in these tables. - [Configure Image Processor](/en/documentation/guides/application-performance/delivery-optimization/process-images.md): Turn the module on, add the rules that process images, and set the cache.