On-The-Fly Media Optimization and Dynamic Image Manipulation

Zesty.io's DAM has on-the-fly (OTF) rendering options to improve and manipulate media that both developers and content authors can use.

Auto Image Optimization - Default Output

Zesty.io automatically transforms images as the content-type "webp", which is a format made to optimized image download speed and rendering speed, developed by Google.

WebP is a modern image format that provides superior lossless and lossy compression for images on the web. Using WebP, webmasters and web developers can create smaller, richer images that make the web faster. - Read the full Google launch article https://developers.google.com/speed/webp

When optimization happens, Zesty.io does a few things to the file:

  • All metadata (for example, EXIF, XMP, or ICC) will is removed.

  • Any ICC profile on the image is applied directly to the image to ensure color output is correct. If the image doesn't have an ICC profile, a default profile is added.

  • If the source image contains orientation metadata, this orientation will be applied directly to the image data and metadata will be removed.

  • Images are served with their original name and extension, but will still output as content-type "webp"

OTF DAM Quick Examples

<!-- using the direct media url, append query parameters to the url -->
<img src="https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?width=200" alt="space ship example">
<!-- using parsley, append query paramters outside th call -->
<img src="{{this.image.getImage()}}?width200&crop=1:1" alt="parsley example">
<!-- example using src set images to be used at different display pixel densities -->
<img srcset="{{this.image.getImage()}}?width=320&dpr=1.5 1.5x,
{{this.image.getImage()}}?width=320&dpr=2 2x"
src="{{this.image.getImage()}}?width=320"/>
<!-- HTML5 art direction, use different images based on browser width -->
<picture>
<source srcset="{{this.image.getImage()}}?width=600&crop=16:9" media="(min-width: 600px)"/>
<img src="{{this.image.getImage()}}?width=320&crop=1:1"/>
</picture>
<style>
.header {
background-image: url(https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?width=2000)
}
</style>

Bypass Image Optimization

To bypass image optimization to get the raw encoding and data of the origin image, append ?raw=true to the end of the image request like so:

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?raw=true

This is useful for fetching EXIF data or other meta data hidden in your image file.

Image Manipulation Options

All image may be manipulated on-the-fly by passing query parameter to the end of the image URL. See the example below

Original Image Source: https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg

We recognize the following parameters in the query string of the image request:

Parameter

Description

auto

Enable optimization features automatically.

bg-color

Set the background color of an image.

bypass

Ignore all optimization and fetch the raw original image

blur

Set the blurriness of the output image.

brightness

Set the brightness of the output image.

canvas

Increase the size of the canvas around an image.

contrast

Set the contrast of the output image.

crop

Crop an image by removing pixels from an image based on a ratio. Great for thumbnails.

dpr

Device Pixel Ratio - Serve correctly sized images for devices that expose a device pixel ratio.

fit

Set how the image will fit within the width and height provided.

height

Resize the height of the image.

optimize

Automatically apply optimal quality compression.

orient

Change the cardinal orientation of the image.

pad

Add pixels to the edge of an image, like css padding.

quality

Optimize the image to the given compression level for lossy file formatted images.

saturation

Set the saturation of the output image.

sharpen

Set the sharpness of the output image.

trim

Remove pixels from the edge of an image.

width

Resize the width of the image.

Image Manipulation Processing order

Manipulation query parameters can be specified in any order, but they are processed in this order:

Order

Query Call

1

trim

2

crop

3

orient

4

width height dpr fit

5

pad canvas bg-color

6

brightness contrast saturation

7

sharpen

8

blur

9

auto optimize quality profile level

Zesty.io OTF DAM: On-The-Fly Image Options API

All query parameters listed below may be used in conjunction with one another, and may be stacked. Some query params conflict with each other, for example pad and canvas. This behavior is documented under each example API call.

get
Auto Optimize: /image.jpg?auto=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?auto=webp
Enables optimizations based on content negotiation. Although the WebP format produces images at a higher compression ratio with a lower loss of quality, it is not supported in all browsers. ?auto=webp Deliver lossless (because input image is lossless) WebP where client support is available, otherwise deliver a PNG ?format=pjpg&auto=webpDeliver lossy (because format=pjpg is lossy) WebP where client support is available, otherwise deliver a progressive JPEG ?format=png&auto=webp Deliver lossless (because format=png is lossless) WebP where client support is available, otherwise deliver a PNG
Request
Response
Request
Query Parameters
auto
optional
string
webp is the only option, see notes above
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?format=pjpg&auto=webp
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?format=pjpg&auto=webp

get
Background Color: /image.jpg?bg-color=

https://9skdl6.media.zestyio.com/parsley-logo-brackets.png?bg-color=690167
Change the background color of a transparent image. Tip: you can make background transparent using a decimal value on the end like 125,80,200,0.5
Request
Response
Request
Query Parameters
bg-color
optional
string
Hex RBG: 690167Decimal: 105,1,103,0.5
Response
200: OK
https://9skdl6.media.zestyio.com/parsley-logo-brackets.png?bg-color=006699
https://9skdl6.media.zestyio.com/parsley-logo-brackets.png?bg-color=105,1,103
https://9skdl6.media.zestyio.com/parsley-logo-brackets.png?bg-color=323CF3

get
Bypass: /image.jpg?raw=true

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?raw=true
Bypass any optimization and return the original image.
Request
Response
Request
Query Parameters
raw
optional
string
true
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?raw=true

get
Gaussian Blur: /image.jpg?blur=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?blur=20
Gaussian blur your image.
Request
Response
Request
Query Parameters
blur
optional
number
0.5 to 1000
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?blur=20
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?blur=20

get
Brightness: /image.jpg?brightness=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?brightness=20
Adjusts the "brightness" of an image. This effect adds perceived light to an image.
Request
Response
Request
Query Parameters
brightness
optional
integer
0 unchanged || -100 black || 100 white
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?brightness=20
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?brightness=20

Canvas

Canvas is used for advanced targeted cropping of images.

The canvas image modifier query parameter takes multiple values which can get complicated, so we included example references as they are best to understand the behavior. To get a feel for it, experiment with the image url example provided, and play with the numbers.

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?canvas=500,100

The canvas query param takes comma separated values SIZE,POSITION, where SIZE is a pixel width and height 500,100or a ratio like 2:1. The POSITION is represented as a percentage offset from the center of the image using offset-x and offset-ylike offset-x50,offset-y95 . POSITION and SIZE together look like this:canvas=400,130,offset-x50,offset-y95. If POSITION is omitted, the image centers by default.

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?width=500&canvas=320,100
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?width=1000&canvas=400,130,offset-x50,offset-y95
  • The background color of the canvas will default to transparency for image output formats that support transparency and white for formats that don't. This behavior can be changed by adding the bg-color parameter.

  • When using canvas and pad at the same time, pad will be ignored.

  • Fractional pixel measurements are rounded to the nearest whole pixel.

get
Canvas Control: /image.jpg?canvas=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?canvas=500,100
Allows the user to precisely crop an image by specific positions as described above.
Request
Response
Request
Query Parameters
canvas
optional
string
See above documentation
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?canvas=500,400,offset-x20,offset-y20

get
Contrast: /image.jpg?contrast=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?contrast=20
Change the image contrast, the value can be anything between -100 and 100, negative numbers start to wash out the image, positive number increase the vibrancy of the images colors.
Request
Response
Request
Query Parameters
contrast
optional
integer
-100 to 100
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?contrast=100
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?contrast=100

get
Crop: /image.jpg?crop=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?crop=1:1
Crop an image evenly from all sides by passing in a ratio 1:1 is a perfect square, 16:9 is letter box, 10:1 is a slim rectangle etc. Great for making thumbnails by passing in a width and a crop, ?crop=1:1&width=50 makes a tiny square, for example. To crop before other commands are run, use precrop instead of crop
Request
Response
Request
Query Parameters
precrop
optional
string
use over crop when needed before other changes
crop
optional
string
1:1 || 10:1 || 16:9
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?crop=1:1&width=400
Crop Example: https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?crop=1:1&width=200
Crop example: https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?crop=4:1&width=800

get
Device Pixel Ratio (dpr): /image.jpg?dpr=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?dpr=2
For optimizing delivery of images to devices with high pixel ratios. The iPhone XS, for example, has a resolution of 375x812 pixels, but its device to pixel ration is 3, so it renders 1125x2436. A developer can access this value from JavaScript by calling window.devicePixelRatio DPR will increase the delivered size by a multiple 1-10 to accommodate for the device Pixel Ratio. Use with JavaScript dynamically when rendering a view and you know the clients Device Pixel Ratio.
Request
Response
Request
Query Parameters
dpr
optional
number
1-10
Response
200: OK
DPR example: https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?dpr=2&width=200

get
Fit: /image.jpg?fit=cover&height=200&width=200

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?fit=cover&height=200&width=200
The fit parameter controls how the image will be constrained within the provided size (width and height) values, in order to maintain proportions that fit within the confines of the width and height. Note: width and height must be pass with fit to work properly. Use the the navigation on the right to search on width and height. An example of this is image.jpg?fit=cover&height=200&width=200 bounds fit entirely within the specified region, making one dimension smaller if needed. cover cover the specified region, making one dimension larger if needed. crop Resize and crop the image centrally to exactly fit the specified region.
Request
Response
Request
Query Parameters
fit
optional
string
bounds || cover || crop
width
required
number
width in pixels
height
required
number
height in pixels
Response
200: OK
Fit Crop Example: https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?fit=crop&width=200&height=400
Fit Bounds example keeps within the width, reducing height: https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?fit=bounds&width=200&height=400
Fit cover fits within the largest bounds, which is height in this examples: https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?fit=cover&width=200&height=400

get
Height: /images.jpg?height=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?height=200
Control the height of the image, the width, if not provided, will adapt to match the original ratio of the image.
Request
Response
Request
Query Parameters
height
optional
number
A height in pixels
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?height=100
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?height=100

get
Image Optimize /image.jpg?optimize=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?optimize=high
Difference and output are minimal for most images that use this param, to be more aggressive in sizing, use the QUALITY param. log Output image quality will be similar to the input image quality. medium More optimization is allowed. Visual quality of the input is preserved. high Minor visual artifacts may be visible. This produces the smallest file.
Request
Response
Request
Query Parameters
optimize
optional
string
Response
200: OK

get
Orientation: /image.jpg?orient=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?orient=l
Rotate the image on 90 degree angles r Orient the image right. l Orient the image left. h Flip the image horizontally. v Flip the image vertically. hv Flip the image both horizontally and vertically (also vh). rv Flip the image horizontally, then orient the image left (also rv or vr). vl Flip the image horizontally, then orient the image right (also lvor vl).
Request
Response
Request
Query Parameters
orient
optional
string
see above docs for options
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?orient=l
Orientation example: https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?orient=l

get
Image Padding: /image.jpg?pad=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?pad=10,20,50,10
Add extra pixels around an image by following the same standards as the CSS padding attribute. For example: top, right, bottom, left: 10,20,10,20 single number to get even all around: 100 top bottom and left and right as: 100,200 Tip: combine with bg-color to change the padding color
Request
Response
Request
Query Parameters
pad
optional
string
100,20,200,111
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?pad=10,10,50,10&bg-color=FFC0CB&width=500

get
Image Quality: /image.jpg?quality=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?quality=55
Control the file size of the image by reducing the quality.
Request
Response
Request
Path Parameters
optional
string
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?quality=55
Reduced from 56KB to 4KB https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?quality=1
56KB full quality https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?quality=100&width=500

get
Saturation: /image.jpg?saturation=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?saturation=-50
Play with the intensity levels of colors, also use to grayscale an image by passing -100
Request
Response
Request
Path Parameters
optional
string
-100 for grayscale 0 is normal 100 is intense
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?saturation=-50
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?saturation=100
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?saturation=-100

get
Sharpen: /image.jpg?sharpen

https://9skdl6.media.zestyio.com?sharpen=a5,r5,t4
Change the sharpness of an image, which can create really interesting artistic outputs amount:0-10, radius:0-1000, and threshold:0-100
Request
Response
Request
Path Parameters
optional
string
aX,rX,tX where X is an integer
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?sharpen=a5,r5,t4
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?sharpen=a10,r1000,t100
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?sharpen=a5,r5,t4
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?sharpen=a10,r500,t10

get
Trim /image.jpg?trim=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?trim=25,50,75,100
Values are accept the same as CSS padding or margin values. The numbers may be pixels or percentages. Pixel value example: 25,50,75,100 Percentage example 25p,50p,20p,10p
Request
Response
Request
Path Parameters
optional
string
Response
200: OK
Trim: https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?trim=25p,50p,20p,10p

get
Width: /image.jpg?width=

https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?width=100
Constrain the width of the image, the height, if not passed, will auto size itself to the original ratio of thr image.
Request
Response
Request
Query Parameters
width
optional
number
Integer
Response
200: OK
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?width=800
https://9skdl6.media.zestyio.com/Arcade-Space-Ship-Example.jpg?width=800

About Zesty.io On-The-Fly Media Technology

Zesty.io leverages Fastly's Image Optimization technology layered on top of the Zesty.io DAM Media Manager. Features documented here relate to what is supported through Zesty.io WebEngine and Media services.