Image Processing

Updated on August 29, 2023

Our powerful real-time Image Processing feature transforms and optimizes your images with simple query parameters. Your image management workflow defines the user experience by transforming and optimizing the image delivery for any browser. Process images on the fly to create multiple variants and deliver them from our high performance CDN.

This feature is available for both Pull and Push Zones. Simply set the Image Processing setting to enabled. When the Image Processing setting is set to enabled in a Pull Zone the Origin Shield and Cache Key Host settings will be set to enabled and the Ignore Query String setting will be set to disabled automatically.

It is possible to process images and deliver other content at the same time when this feature is enabled. When enabled, the x-ip and x-ip-info response headers will be added. The x-ip response header indicates the status of the operation. The following values are possible:

0 - The asset was not processed (e.g. CSS or JavaScript).
1 - The image was regularly processed.
2 - The original image is returned because it is smaller than the processed image.

The x-ip-info response header provides additional details about the image processed. The osz value shows the output size, the odim value the output dimensions and the ofmt value the output format. Currently jpeg, png, webp, and tiff image formats are supported. If an error has occurred during the image transformation, the header x-ip-error provides a detailed error message.

Note: Purging a processed image from the CDN cache can only be done by Purge URL. The Cache Key Scheme setting must be disabled.

Parameter	Value	Dependencies	Default
`trim` trim	`0`-`100` integer
`crop=smart` `crop={width,height}` `crop={width,height,x,y}` `crop=fp,{fp-x,fp-y}` `crop=fp,{fp-x,fp-y,fp-z}` `crop=fpd,{fp-x,fp-y}` crop	`0`-`10000` integer (pixels) for width, height, x, y, fp-x, fp-y `0`-`1` float (ratio of base image) for fp-x, fp-y `0`-`100` integer (zoom factor) for fp-z	`smart`,`fp`, `fpd` requires `width` and `height`
`width` resize	`0`-`10000` integer (pixels)
`height` resize	`0`-`10000` integer (pixels)
`fit` resize	`cover`, `contain`, `fill`, `inside`, or `outside` string	`width` and `height`
`position` resize	`top`, `right`, `bottom`, or `left` string	`fit` of `cover` or `contain`
`enlarge` resize	`0` or `1` boolean	`width` or `height`	1
`bg={hex}` `bg={r,g,b}` `bg={r,g,b,a}` resize, extend	`000000`-`ffffff` hex `0,0,0,0.0`- `255,255,255,1.0` rgb with optional alpha	`extend` or `fit` of `contain`
`extend={padding}` `extend={top,right,bottom,left}` extend	`0`-`1000` integer (pixels)
`rotate` compose	`-359`-`359` integer (degrees)
`flip` compose	`0` or `1` boolean
`flop` compose	`0` or `1` boolean
`sharpen` compose	`0`-`100` integer
`blur` compose	`0.3`-`100` float
`gamma` compose	`0`-`3` float
`negate` compose	`0` or `1` boolean
`normalize` compose	`0` or `1` boolean
`threshold` compose	`0`-`255` integer
`tinteger` compose	`000000`-`ffffff` hex
`grayscale` compose	`0` or `1` boolean
`removealpha` compose	`0` or `1` boolean
`olurl` overlay	`URL` string
`olalign` overlay	`center`, `top`, `topright`, `right`,`bottomright`, `bottom`, `bottomleft` or `topleft` string	`olurl`	center
`olx` and `oly` overlay	`0`-`2000` integer (pixels)	`olurl`
`olwidth` overlay	`0`-`1`float `2`-`2000`integer (pixels)	`olurl`
`olheight` overlay	`0`-`1`float `2`-`2000`integer (pixels)	`olurl`
`olscale` overlay	`1`-`99` integer (percent)	`olurl`
`olpadding` overlay	`0`-`1000` integer (pixels)	`olurl`	10
`olalpha` overlay	`1`-`99` integer (percent)	`olurl`
`olrepeat` overlay	`0` or `1` boolean	`olurl`
`format` format	`jpeg`, `png`, or `webp` string
`quality` format	`0`-`100` integer	`jpeg` or `webp`	jpeg: 82 / webp: 80
`progressive` format	`0` or `1` boolean	`jpeg` or `png`	0
`compression` format	`0`-`9` integer	`png`	3
`adaptive` format	`0` or `1` boolean	`png`	0
`alphaquality` format	`0`-`100` integer	`webp`	100
`lossless` format	`0` or `1` boolean	`webp`	0
`nearlossless` format	`0` or `1` boolean	`webp`	0
`metadata` format	`0` or `1` boolean		0

Order of Operations

The query parameters can be defined in any order but our system normalizes the transformation sequence to the following order:

trim
crop
resize
extend
compose
overlay
format

`trim`

Trims pixels from all edges that are similar to the top left pixel.

    
        https://ip.keycdn.com/example.jpg?trim=10

`crop`

Crops the image by smart, {width,height}, {width,height,x,y}, fp,{fp-x,fp-y}, fp,{fp-x,fp-y,fp-z}, or fpd,{fp-x,fp-y}. smart uses an algorithm to automatically focus on the most important part of the image. width, height, x, and y are defined in pixels. fp-x, fp-y are defined in pixels or as a ratio of the base image. fp-z is the zoom factor. fp is the focus point and fpd is the focus point in debug mode that adds a red hairline cross to the image.

    
        https://ip.keycdn.com/example.jpg?crop=smart&width=400&height=400

    
        https://ip.keycdn.com/example.jpg?crop=600,400

    
        https://ip.keycdn.com/example.jpg?crop=600,400,100,0

    
        https://ip.keycdn.com/example.jpg?crop=fp,0.40,0.70,2.2&width=600&height=400

    
        https://ip.keycdn.com/example.jpg?crop=fpd,0.40,0.70&width=800&height=400

`width`

Resizes the image width defined in pixels.

    
        https://ip.keycdn.com/example.jpg?width=600

`height`

Resizes the image height defined in pixels.

    
        https://ip.keycdn.com/example.jpg?height=400

`fit`

Defines how the image should fit within the provided width and height dimensions.

            
                https://ip.keycdn.com/example.jpg?width=400&height=400&fit=cover

            
                https://ip.keycdn.com/example.jpg?width=400&height=400&fit=contain

            
                https://ip.keycdn.com/example.jpg?width=400&height=400&fit=fill

            
                https://ip.keycdn.com/example.jpg?width=400&height=400&fit=inside

            
                https://ip.keycdn.com/example.jpg?width=400&height=400&fit=outside

`position`

Sets the position of the image in the canvas.

            
                https://ip.keycdn.com/example.jpg?width=400&height=200&fit=cover&position=top

            
                https://ip.keycdn.com/example.jpg?width=400&height=400&fit=contain&position=top

            
                https://ip.keycdn.com/example.jpg?width=400&height=400&fit=cover&position=right

            
                https://ip.keycdn.com/example.jpg?width=400&height=200&fit=cover&position=bottom

            
                https://ip.keycdn.com/example.jpg?width=400&height=400&fit=contain&position=bottom

            
                https://ip.keycdn.com/example.jpg?width=400&height=400&fit=cover&position=left

`enlarge`

Defines if the image should be enlarged beyond the original dimensions.

    
        https://ip.keycdn.com/example.jpg?width=730&enlarge=0

`bg`

Sets the background color of the image.

    
        https://ip.keycdn.com/example.jpg?width=400&height=400&fit=contain&bg=2e3234

    
        https://ip.keycdn.com/example.jpg?width=400&height=400&fit=contain&bg=46,50,52

`extend`

Extend the image by {padding} or {top,right,bottom,left} defined in pixels.

    
        https://ip.keycdn.com/example.jpg?extend=100

    
        https://ip.keycdn.com/example.jpg?extend=100,50,100,50

`rotate`

Rotates the output image by a positive or negative degree.

    
        https://ip.keycdn.com/example.jpg?rotate=90

`flip`

Flips the image vertically (y axis).

    
        https://ip.keycdn.com/example.jpg?flip=1

`flop`

Flops the image horizontally (x axis).

    
        https://ip.keycdn.com/example.jpg?flop=1

`sharpen`

Sharpens the image. A higher sharpen value will increase the processing latency.

    
        https://ip.keycdn.com/example.jpg?sharpen=10

`blur`

Blurs the image. A higher blur value will increase the processing latency.

    
        https://ip.keycdn.com/example.jpg?blur=5

`gamma`

Performs a gamma correction by reducing the encoding pre-resize at a factor of 1/gamma then increasing the encoding post-resize at a factor of gamma.

    
        https://ip.keycdn.com/example.jpg?gamma=1.5

`negate`

Creates the negative of the image.

    
        https://ip.keycdn.com/example.jpg?negate=1

`normalize`

Improves output image contrast by lengthening its luminance to cover the full dynamic range.

    
        https://ip.keycdn.com/example.jpg?normalize=1

`threshold`

Changes any pixel value greater than or equal to the threshold value to 255, otherwise to 0.

    
        https://ip.keycdn.com/example.jpg?threshold=100

`tint`

Tints the image using tint hex color value while preserving the image luminance.

    
        https://ip.keycdn.com/example.jpg?tint=047aed

`grayscale`

Converts the image to a 8-bit grayscale with 256 shades of gray. If the input image is in a nonlinear color space (e.g. sRGB), use gamma together with grayscale for optimal results.

    
        https://ip.keycdn.com/example.jpg?grayscale=1

`removealpha`

Removes the alpha channel from the image, if any.

    
        https://ip.keycdn.com/example.jpg?removealpha=1

`olurl`

Specifies the URL of the overlay image (also known as watermark). The valid overlay image formats are svg, jpeg, png and webp. The URL can be plain (e.g. https://logos.keycdn.com/keycdn-logo-black.svg) or encoded (e.g. https%3A%2F%2Flogos.keycdn.com%2Fkeycdn-logo-black.svg).

    
        https://ip.keycdn.com/example.jpg?olurl=https://logos.keycdn.com/keycdn-logo-black.svg

`olalign`

Changes the alignment of the overlay image within the base image.

    
        https://ip.keycdn.com/example.jpg?olurl=https://logos.keycdn.com/keycdn-logo-black.svg&olalign=topright

`olx` and `oly`

Sets the location of the overlay image based on coordinates (pixels). olx and oly will take precedence over olalign.

    
        https://ip.keycdn.com/example.jpg?olurl=https://logos.keycdn.com/keycdn-logo-black.svg&olx=100&oly=300

`olwidth`

Defines the width of the overlay image relative to the base image if <=1 or in absolute pixel if >2.

    
        https://ip.keycdn.com/example.jpg?olurl=https://logos.keycdn.com/keycdn-logo-black.svg&olwidth=400

`olheight`

Defines the height of the overlay image relative to the base image if <=1 or in absolute pixel if >2.

    
        https://ip.keycdn.com/example.jpg?olurl=https://logos.keycdn.com/keycdn-logo-black.svg&olheight=0.75

`olscale`

Defines the width of the overlay image in percent to the width of the base image.

    
        https://ip.keycdn.com/example.jpg?olurl=https://logos.keycdn.com/keycdn-logo-black.svg&olscale=40

`olpadding`

Changes the padding of the overlay image in pixels.

    
        https://ip.keycdn.com/example.jpg?olurl=https://logos.keycdn.com/keycdn-logo-black.svg&olalign=bottomleft&olpadding=100

`olalpha`

Adjusts the alpha transparency of the overlay image.

    
        https://ip.keycdn.com/example.jpg?olurl=https://logos.keycdn.com/keycdn-logo-black.svg&olalpha=35

`olrepeat`

Repeats the overlay image.

    
        https://ip.keycdn.com/example.jpg?olurl=https://logos.keycdn.com/keycdn-logo-black.svg&olrepeat=1

`format`

Specifies the output format of the image.

            
                https://ip.keycdn.com/example.jpg?format=jpeg

            
                https://ip.keycdn.com/example.jpg?format=png

            
                https://ip.keycdn.com/example.jpg?format=webp

`quality`

Sets the quality level of the image.

    
        https://ip.keycdn.com/example.jpg?quality=70

    
        https://ip.keycdn.com/example.jpg?format=webp&quality=70

`progressive`

Specifies to use progressive (interlace) scan of the image.

    
        https://ip.keycdn.com/example.jpg?progressive=1

    
        https://ip.keycdn.com/example.jpg?format=png&progressive=1

`compression`

Defines the zlib compression level of the PNG image.

    
        https://ip.keycdn.com/example.jpg?format=png&compression=5

`adaptive`

Enables adaptive row filtering on PNG images.

    
        https://ip.keycdn.com/example.jpg?format=png&adaptive=1

`alphaquality`

Specifies the quality of the alpha layer.

    
        https://ip.keycdn.com/example.jpg?format=webp&alphaquality=20

`lossless`

This option encodes the WebP image without any loss.

    
        https://ip.keycdn.com/example.jpg?format=webp&lossless=1

`nearlossless`

This option adjusts WebP pixel values to help compressibility, but has minimal impact on the visual quality. It is linked to the quality parameter.

    
        https://ip.keycdn.com/example.jpg?format=webp&nearlossless=1

`metadata`

Keeps the image metadata (EXIF, IPTC, and XMP).

    
        https://ip.keycdn.com/example.jpg?metadata=1

Signing requests

Signing Image Processing requests means securing the URL from unwanted modifications. Once the Zone settings Secure Token and Image Processing are enabled, an image can only be requested with a valid token. Any request with an invalid signature will result in a 403 error. This ensures that an unwanted image operation cannot be executed. Each request will be signed with a individual token. How to generate a valid token is described in our Secure Token article.

    
        https://ipsigned.keycdn.com/example.jpg?flip=1&token=kfgL8ZLmYufEtp-yXZcmiw

Signing overlay requests

Signing overlay images is a special case where the base image from the origin should not be revealed or accessed. In order to achieve this, there are a few important details to consider. First, a canonical header would reveal where the base image is located. That means if the origin server is not authenticating requests then someone could simply use this URL to access the image directly from the origin without the watermark. Therefore, the Zone setting Canonical Header should be disabled. The canonical header should also be removed from the origin server if set.

Next, choosing a secret Origin URL, such as https://urjdh47e.example.com, is recommended as this makes it more difficult to be guessed compared to something more common like https://www.example.com. Limiting acccess to the origin server to only KeyCDN can be implemented for further access control. One way to do this would be through the X-Pull request header, which is a request header that all of KeyCDN's requests contain. A unique X-Pull Key could be set followed by a rule added to the origin server that forbids any requests without that request header and value.

    
        https://ipsigned.keycdn.com/example.jpg?olurl=https://logos.keycdn.com/keycdn-logo-black.svg&olwidth=400&token=bxoFkqiyiKcFVIUmzBcVbg

Support

Image Processing

Order of Operations

trim

crop

width

height

fit

position

enlarge

bg

extend

rotate

flip

flop

sharpen

blur

gamma

negate

normalize

threshold

tint

grayscale

removealpha

olurl

olalign

olx and oly

olwidth

olheight

olscale

olpadding

olalpha

olrepeat

format

quality

progressive

compression

adaptive

alphaquality

lossless

nearlossless

metadata