Support

Find answers, guides, and tutorials to supercharge your content delivery.

Image Processing

Updated on April 6, 2022
Image Processing

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.
ParameterValueDependenciesDefault
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-4000
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 height1
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
olurlcenter
olx and oly
overlay
0-2000
integer (pixels)
olurl
olwidth
overlay
0-1float
2-2000integer (pixels)
olurl
olheight
overlay
0-1float
2-2000integer (pixels)
olurl
olscale
overlay
1-99
integer (percent)
olurl
olpadding
overlay
0-1000
integer (pixels)
olurl10
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 webpjpeg: 82 / webp: 80
progressive
format
0 or 1
boolean
jpeg or png0
compression
format
0-9
integer
png3
adaptive
format
0 or 1
boolean
png0
alphaquality
format
0-100
integer
webp100
lossless
format
0 or 1
boolean
webp0
nearlossless
format
0 or 1
boolean
webp0
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:

  1. trim
  2. crop
  3. resize
  4. extend
  5. compose
  6. overlay
  7. 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=600&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
    
KeyCDN uses cookies to make its website easier to use. Learn more about cookies.