Support

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

Image Processing

Updated on April 6, 2020
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. If the value is 0 the request was not processed (e.g. CSS or JavaScript). If the value is 1 the request was processed. The x-ip-info response header indicates the output of the processed request. The osz value indicates the output size, the odim value indicates the output dimensions, and the ofmt value indicates the output format. Currently jpeg, png, webp, and tiff image formats are supported.

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
int
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
int (pixels) for width, height, x, y, fp-x, fp-y
0-1
float (ratio of base image) for fp-x, fp-y
0-100
int (zoom factor) for fp-z
smart,fp, fpd requires width and height
width
resize
0-10000
int (pixels)
height
resize
0-10000
int (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
int (pixels)
rotate
compose
-359-359
int (degrees)
flip
compose
0 or 1
boolean
flop
compose
0 or 1
boolean
sharpen
compose
0-100
int
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
int
tint
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
int (pixels)
olurl
olwidth
overlay
0-1float
2-2000int (pixels)
olurl
olheight
overlay
0-1float
2-2000int (pixels)
olurl
olscale
overlay
1-99
int (percent)
olurl
olpadding
overlay
0-1000
int (pixels)
olurl10
olalpha
overlay
1-99
int (percent)
olurl
olrepeat
overlay
0 or 1
boolean
olurl
format
format
jpeg, png, or webp
string
quality
format
0-100
string
jpeg or webpjpeg: 85 / webp: 80
progressive
format
0 or 1
boolean
jpeg or png0
compression
format
0-9
int
png3
adaptive
format
0 or 1
boolean
png0
alphaquality
format
0-100
int
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. 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
    
KeyCDN uses cookies to make its website easier to use. Learn more about cookies.