Dynamic imaging

Discover how to create images of any size or style instantly. It’s fast and easy, with no technical knowledge required. Each option is explained below, with a summary table of 70 options below.

Before you start

The bigger the images you upload, the more options you’ll have.

For best results, upload images of at least:

  • 2500px width
  • 92% quality (if JPEG)

Sirv hosts and delivers any image type (and other files too). It automatically resizes and optimizes images to suit your users device, keeping your originals untouched. If you upload big, high-quality images, you can confidently deliver superb quality Sirv Zooms and permit glorious clarity on hi-res retina screens.

Upload images into your account or check the various image uploading options.

URL format

New images are created by appending options in your image URL.

Here is an image without any options:


Here is the same image scaled to 300px (notice w in the URL, which stands for width):


Pixel values are referenced using the number only. For percentage values, always use the ‘%‘ sign, e.g. 40%.

Here is the same image with lots more options – note that multiple parameters in the URL are separated by the ‘&‘ character:



Every option is described below, with examples.

Your options may also be saved as a profile, which is handy for applying the same options to many images.


Sirv instantly resizes images when you specify width or height in the URL. A new image is immediately created using the dimensions you request.

Width is changed by appending the w parameter to the URL (or scale.width). The JPEG image below was 400px width. It has been scaled to 250px width:


250px width image

Height is changed by appending the h parameter to the URL (or scale.height), for example this 100px height image:


100px height image

Images can also be scaled as a percentage of their original size. This image has 50% of its original width:


Image scaled to 50% width

Images can be stretched larger, beyond their original dimensions. This image is 200% of its original width:


Image upscaled to 200%

Images become blurred when they are scaled up, so the recommended approach is to upload larger images rather than scale images up (at least 2500px width if possible).

If you specify both w and h, the new image will fit inside the two dimensions (maintaining the original aspect ratio). In the example below, w and h are both set to 150px, so Sirv created an image of 150px width and 85px height (because the original image is wider than it is tall):


Scale options

The scale.option parameter lets you control how Sirv scales images.

To generate an image scaled to the larger of either w or h, set the scale.option to fill (fill specified area). The example below disregards the height of 120px and creates an image of 350px width:


To stretch the image, changing the aspect ratio, set the scale.option parameter to ignore (ignore aspect ratio). For example:


To prevent the image from being scaled larger than its original size, set the scale.option to noup (no upscaling of image). The example below sets a size of 800px width and 600px height but the image served doesn’t go beyond its original 400px width and 227px height:


If no scale.option is specified, the default value ‘fit‘ will be used (meaning fit inside the dimensions specified).


To rotate an image, set the ‘rotate‘ option to the required number of degrees, which can range from -180 to 180.



brightness‘ is set on a scale from -100 (very dark) to 100 (very bright opaque). The default is 0.




contrast‘ is set on a scale from -100 (low contrast) to 100 (high contrast). The default is 0.




exposure‘ is set on a scale from -100 (underexposed) to 100 (overexposed).






hue‘ is set on a scale from -100 to 100. The hue refers to the color or shade.



You could use hue (and saturation) to adjust the color of a product, for example:


Hue of -83 Hue of -50 Hue of -17 Hue = 17 Hue = 50 Hue = 83


saturation‘ is set on a scale from -100 to 100. The saturation refers to the intensity of a color.


Increased saturation (30)


Reduced saturation (-30)


lightness‘ is set on a scale from -100 to 100. The lightness adjusts the lightness (white) or darkness (black) of the image.


Lighter image (20)


Darker image (-20)


shadows‘ is set on a scale from -100 to 100. The shadows setting can increase/decrease the impact of shadows in the image.


Greater shadows (15)


Reduced shadows (-15)


highlights‘ is set on a scale from -100 to 100. The highlights setting can increase/decrease the impact of shadows in the image.


Greater highlights (15)


Reduced highlights (-15)


grayscale‘ converts an image to a grayscale version. It can be set to ‘true‘ or ‘false‘, with the default value of ‘false‘.



blur‘ applies blur to an image. The range is set on a scale from 0 (the default) to 100.



colortone‘ alters the color scheme of an image. The default value is ‘none‘.

There are six colortones to choose from: sepia; warm; cold; sunset; purpletan and texas.














A vignette (dark edges) can be added around an image. You’re able to control the amount of vignette and its color.

vignette.value‘ controls how far into the image the vignette appears. It is set with a number from 0 to 100. The default is 20.


Vignette on image (50)

vignette.color‘ sets the color of the vignette. The values are set with hex RGB/RGBA or an HTML color name.


Red vignette on image

If you set the color with a hex value, don’t include a ‘#‘ character in the URL. For example:


Here are examples of ‘vignette.value‘ and ‘vignette.color‘ together:


Blue vignette


Colored vignette


White vignette

Image format

Sirv can serve your images in either JPEG, PNG, GIF or WebP format – regardless of the original image format. By default, it does this automatically with the “optimal” format.


The default image format is called “optimal” and we recommend keeping this setting.

There are no settings to change – simply upload your images to Sirv in whatever format they are and Sirv will serve them in the best possible format for each users device. Often, the smallest file size image format is WebP, so that is the format usually served to Chrome and Opera browsers, though sometimes an optimized PNG or a compressed JPEG may be more suitable.

Whether your original images are in JPEG, PNG or GIF format, the “optimal” format will ensure that every visitor receives the fastest loading image format for their device.


To always serve the original image format to all devices/browsers, set the ‘format‘ parameter to “original”:


Original image format (JPEG)

With the original format, images will be optimized and/or compressed but they will not change the format.


WebP is a modern image format that you’ll instantly benefit from when you use Sirv. The default format “optimal” automatically serves WebP to supporting browsers and serves either JPEG or PNG to unsupporting browsers.

WebP compresses images to much smaller file sizes than their PNG, JPEG and GIF equivalents. File size is typically 40-70% smaller and image quality is typically sharper. Developed by Google, WebP supports transparency, alpha, and animation, making it a powerful alternative to JPEG, PNG, and GIF.

As of September 2017, 73% of web users could view WebP images. Currently, Chrome and Opera support it while Safari and Firefox intend to add WebP support in a future browser version.

As WebP is enabled by default in the “optimal” image format, you do not need to specify it. However, if you want to specifically tell Sirv to serve your JPEG and PNG images in WebP format, set the ‘format‘ option to ‘webp‘ like so:


If you’re currently using Chrome or Opera, you’ll see a WebP image below, otherwise you’ll see a PNG:

PNG served as WebP

When served as a PNG with transparent background, that 250px height image is 87.9kb. When served in WebP format, it is only 25.5kb.

If you’ve uploaded an image that is already in WebP format, your images will be served as WebP and will automatically fall-back to JPEG for unsupporting browsers.

Below is an image that was saved in WebP format before it was uploaded to Sirv. The file size is only 49kb. If the browser does not support WebP, Sirv automatically serves it in JPEG format (72kb file size):


WebP example image

To learn more about WebP, read Google’s official WebP documentation.

Use the ‘webp.fallback‘ option to control what format an original WebP image should fall back to when WebP isn’t supported.

Original WebP images will fall back to JPEG. You can make them fall back to PNG like so:



JPEG quality

Sirv compresses your images to 80% quality by default. This produces a good balance between a high-quality image and small file size for fast-loading. For reference, most digital cameras store images at 96% quality.

Adjust this percentage up or down to either increase image clarity or load images faster. Apply the ‘q‘ option for JPEG quality. The scale ranges from 0-100.


Example image 92% qualityExample image 90% quality
Example image 85% qualityExample image 80% quality
Example image 75% qualityExample image original quality

The final example above uses a setting of ‘q=0’, which makes Sirv use the same quality as the original JPEG uploaded to Sirv (in this case, 99%).

This is useful if you’ve already done post-processing before uploading to Sirv and want to maintain that setting. For best results, we recommend that you upload uncompressed JPEGs – at least 92% quality or above.

By uploading large uncompressed images, you’ll ensure maximum options for the future. Your final image will look sharp, by minimizing the quality loss when creating a JPEG from a JPEG.

Progressive JPEG

There are two primary types of JPEG images: baseline and progressive.

Baseline JPEGs start loading with the fully rendered top of the image and then continue to draw in the rest of the image as the data is received.

Progressive JPEGs load the full image much faster but with fewer pixels. The image momentarily looks pixelated and then sharpens as the rest of the data loads. Progressive JPEGs can make the experience faster for viewers and is the preferred JPEG type for many developers.

By default, Sirv serves baseline JPEG. You can change it to progressive by setting the ‘progressive‘ option to ‘true’.


JPEG subsampling

Chroma subsampling reduces the file size of JPEG images by 25% on average, without any noticeable impact on the image. Smaller file size helps images load faster and reduces data transfer, so Sirv applies subsampling of 4:2:0 by default.

Subsampling is expressed as a three part ratio J:a:b (e.g. 4:2:0) which describes the number of luminance and chrominance samples in a region that is J pixels wide, and 2 pixels high. The parts are (in their respective order):

  • J: horizontal sampling reference (width of the conceptual region). Usually 4.
  • a: number of chrominance samples (Cr, Cb) in the first row of J pixels.
  • b: number of changes of chrominance samples (Cr, Cb) between first and second row of J pixels.

Sometimes, a very subtle color difference can be identified when comparing the original JPEG and the subsampled JPEG. If you have images which display visual differences due to chroma subsampling, you can change the ‘subsampling‘ option. The available settings are 4:4:4, 4:2:2 and 4:2:0, where 4:4:4 has no subsampling and 4:2:2 has some subsampling:


The following 3 JPEG images have settings of 4:4:4, 4:2:2 and 4:2:0 respectively:

Chroma subsampling demo 4:4:4 Chroma subsampling demo 4:2:2 Chroma subsampling demo 4:2:0


PNG optimization

Sirv provides PNG optimization to dramatically reduce the size of your PNG images.

By default, your images will be served using the ‘optimal’ format, which will automatically serve your images as either WebP or optimized PNG, whichever is more efficient.

To force an image to be always served as PNG to all browsers, set ‘format’ to ‘png’:


png.optimize‘ lets you apply PNG optimization with either ‘true’/’false’ or ‘1’/’0′. By default, PNG optimization is disabled when ‘format’ is set to ‘png’. To enable it, set it to ‘true’:


Example image optimized PNG

The amount of optimization applied by Sirv depends on the image size. The smaller the image, the greater the optimization (in steps from 300×300, 500×500, 700×700, 900×900, 1200×1200). PNG images larger than 1500×1500 pixels are not optimized.

While PNG optimization can dramatically speed up the delivery of your images, be aware that it takes longer to process a PNG file when optimization is on.

Sirv performs up to 20 passes to find the best optimizations possible. The first viewer may experience a short delay (typically 0.3 to 3.0 seconds) before the image is served to them. Once the image has processed, it is cached and immediately available for future viewers.

The first viewer probably won’t notice a delay when viewing just one PNG but it may be noticeable when viewing a spinning image, which is typically composed of 36 images.

Compare the unoptimized image to the left (80 KB) against the optimized image to the right (only 20 KB):

PNG compression

Set PNG options to control the size and quality of the resulting PNG image. ‘png.compression‘ is one way to reduce file size. Specify the type of compression (0 = Huffman, 1-9 = zlib). The deault is ‘0’ (Huffman). Zlib compression uses a compression value between 1-9, where 1 is minimal compression and 9 is maximum.


PNG filtering

png.filtering‘ applies advanced filtering algorithm to the PNG image. Note that these are not visual filters — a PNG filter is a precompression step that transforms the image data so that the main compression engine can operate more efficiently.

Available values are: ‘none‘, ‘sub‘, ‘up‘, ‘average‘, ‘paeth‘, and ‘adaptive‘. The default is ‘none’.


Image filters

Sirv provides 31 filters for tweaking how images are resized. When scaling an image (JPEG, PNG, WebP or GIF), a filter algorithm is used to analyze neighboring pixels and determine the color of each pixel in the resized image.

Each filter gives subtle differences in the final image, usually undetectable by the naked eye. Changing the default filter is not needed unless you have a particularly unique image that requires special attention.

Filters can be applied with the ‘filter‘ option, for example:


The available filters are:

  • Bartlett
  • Blackman
  • Bohman
  • Box
  • Catrom
  • Cosine
  • Cubic
  • Gaussian
  • Hamming
  • Hann
  • Hermite
  • Jinc
  • Kaiser
  • Lagrange
  • Lanczos (default filter used for most images)
  • Lanczos2
  • Lanczos2Sharp
  • LanczosRadius
  • LanczosSharp
  • Mitchell (default filter for color-mapped images, matte channel images and enlarged images)
  • Parzen
  • Point
  • Quadratic
  • Robidoux
  • RobidouxSharp
  • Sinc
  • SincFast
  • Spline
  • Triangle
  • Welch


Crop any part of an image by choosing a new width and height plus starting point for the crop.

Choose the new width and/or height – if you omit one, it will default to 100% of the image.

Use ‘cw‘ to specify the new width in pixels or percent (%). The example below was 400px and has been cropped to 300px width:


Use ‘ch‘ to specify the new height in pixels or percent (%). The example below has been cropped to 100px height:


Unless explicitly stated, cropping will start from the top left of the image. This can be adjusted with ‘cx‘ and ‘cy‘ options. These 2 options will move the point of the crop in a specified number of pixels from the top left. For example, the cropping starts at 107 pixels across and 17 pixels down:


You can crop around the center of the image by setting cx and cy to ‘center’:


This image is cropped around the center of the image to 50% of its original height, 100% of its original width:


Cropping can be combined with resizing to create an image of any size and shape:



Sirv can quickly create square thumbnail images with the ‘thumbnail‘ option. Here is a 150px thumbnail image:


The largest possible thumbnail is 1000px. If you need larger square images, use the scale and crop options.

Text overlays

Overlay text on an image with great control over the font, opacity, color and position.


https://sirv.sirv.com/Examples/test-bike.jpg?w=300&text.position=north&text.color=white&text.outline.width=15&text.outline.blur=3&text.size=80&text=Let's hit the road&text.font.family=Architects%20Daughter


Example text overlay



text‘ – the text to be displayed.

The example below is the default small grey text in the bottom right corner. Further down this page, we will change the color, size, weight, and effects to make the text stand out.

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text here!

That URL contains spaces and an exclamation mark (!), which browsers interpret correctly. Some characters such as $, £, €, #, &, © are not interpreted correctly, so use the ASCII character equivalent instead. See the Special characters section below for a list of common codes.

text.size‘ – the width of the text area in percent (%), relative to the image width. This text is 50% of the image width:

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.size=50%

text.color‘ – the text color, applied as RGB/RGBA or a color name. (See the Color section for an explanation of color options in Sirv.)

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.size=50&text.color=FFFFFF

Example image 92% quality

text.opacity‘ – the opacity of the text from 0 (transparent) to 100 (opaque). The default value is ‘100’. The text on the image below is 50% opacity:

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.font.size=24&text.color=FFFFFF&text.opacity=50%

Example text overlay

text.position‘ – the location of the text on the image.

Positions are described with the points of a compass, whereby ‘north’ is the top center. Available values are: center, north, northeast, northwest, south, southeast, southwest, east, and west. The default position is ‘southeast’ (lower right corner).

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.size=50%&text.font.size=24&text.color=FFFFFF&text.position=center

Example text overlay

Alternatively, text can be located anywhere at all, with three further options.

text.position.x‘ – the distance from the left and ‘text.position.y‘ sets the distance from the top. You can use either pixels or percent (%), as either positive or negative values. By default, the position is set from the top left:

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.size=50%&text.color=FFFFFF&text.position.x=52&text.position.y=36

Example custom text position

text.position.gravity‘ – the compass location from which the text position is adjusted. For example, text can be aligned 50px below the center like so:

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.size=50%&text.font.size=24&text.color=FFFFFF&text.position.gravity=center&text.position.y=50

Example text pulled down from center

%0A‘ – add line breaks to your text, for showing multiple lines:


Multi-line text overlay

text.align‘ – align multiple lines of text to the left, right or center. This example aligns the text right:


Align lines of text

Metadata from your images can be displayed in your text overlays. To see an images meta, add ?info to the end of the URL, like so:


To display metadata in a text overlay, use ${metadata path}. This example displays the copyright information from the metadata:


Example metadata text overlay

Text font

text.font.family‘ – sets the text font. The default is Open Sans. You can choose from all the fonts in the expansive Google Fonts library and Google Noto library (for foreign characters).

Here is the Bitter font:

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.size=60&text.font.family=Bitter

Here is the Noto Sans CJK TC (for Traditional Chinese) from Google Noto fonts:

https://demo.sirv.com/Examples/test-girl.jpg?text=這裡是一些中文文本。&text.size=60&text.font.family=Noto Sans CJK TC

text.font.size‘ – sets the height of the font in pixels (px). This lets you fix the size so that it has no relation to the image size. In most cases, ‘text.size‘ (see above) is more suitable. The example below sets a height of 18px:

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.font.size=18

text.font.style‘ – can set the font to be italic instead of the default ‘normal’:

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.font.style=italic

text.font.weight‘ – change the font weight from the default value of ‘400’. Options are 300 or light, 400 or normal, 600 or semi-bold, 700 or bold, 800 or extra-bold. This example sets ‘300’:

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.font.weight=300

This example sets ‘extra-bold’:

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.font.weight=extra-bold

Text outline

text.outline.width‘ – sets an outline (in pixels) around the text characters. The default is ‘0’.

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.size=50&text.color=FFFFFF&text.outline.width=5

text.outline.color‘ – sets the color of the text outline. The default color is ‘black’. Options are explained in the Color section.

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.size=50&text.outline.width=15&text.color=FFFFFF&text.outline.color=404E01

text.outline.opacity‘ – is set on a scale from 0 (transparent) to 100 (opaque). The default value is ‘100’.

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.size=50&text.outline.width=15&text.outline.color=404E01&text.color=FFFFFF&text.outline.opacity=50

text.outline.blur‘ – blurs the edge of the outline. The value is set in pixels with a default value of ‘0’.

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.size=50&text.outline.width=15&text.outline.color=404E01&text.color=FFFFFF&text.outline.blur=10

Text background

You can add a background area behind the text by using ‘text.background.color‘ to choose a color (see the Color section) and text.background.opacity to set the opacity (default is transparent).

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.size=50&text.color=white&text.background.color=874A05&text.background.opacity=50

text.background.opacity‘ is on a scale from 0 (transparent) to 100 (opaque). This example makes the background solid:

https://demo.sirv.com/Examples/test-girl.jpg?text=Overlay text&text.size=50&text.color=white&text.background.color=874A05&text.background.opacity=100

Multiple text layers

You can apply up to 4 text layers to the same image.

Designate each text layer independently as ‘text.n‘, where n is 0, 1, 2, or 3. The following example applies 2 text layers – one above, one below the image:


Image with 2 text layers

The complete set of Sirv text controls are available for each text layer. The example below has a bold image title to the right and a discreet copyright notice in the bottom right:

https://sirv.sirv.com/website/demos/glastonbury.jpg?w=420&text.0.text=%C2%A9Michael Eavis&text.1.text=Glastonbury 2014&text.1.position=east&text.1.size=38%&text.1.background.opacity=50%&text.1.font.weight=bold&text.1.font=Raleway&text.0.color=grey

Image with two text watermarks

Watermark overlays

Overlay images on top of other images to create watermarks and popular photo effects. You can layer up to 4 images on top (or behind) the original image, giving you many creative possibilities.

For the following examples, we will use the Sirv logo as a watermark. To reference a watermark use ‘watermark‘ option, specify the location and filename of the watermark, eg:


The Sirv logo is a large PNG image of 823px width. PNG images are best for watermarks since the opacity can be easily controlled through Sirv options.

watermark.position‘ – sets the position of the watermark. The values, other than ‘center’ and ’tile’, correspond to points on a compass, with ‘north’ located in the top middle. The allowed values are: north, northeast, northwest, center, south, southeast, southwest, east, west, and tile.

center‘ places the watermark in the center of your original image while ‘tile‘ overlays the image with a repeating array of your watermark image.


Here is an example using the ‘tile‘ value for the watermark position:


If using a large watermark image, reduce the ‘watermark.scale.width’ and ‘watermark.opacity’ to achieve the example below:


watermark.rotate‘ – sets the amount of rotation for the watermark image. From -180 to 180, with a default value of ‘0’.

The watermark is prominent with no image behind it. To keep the full image behind your watermark, also set ‘watermark.canvas.opacity‘ to ‘0’ as shown below:


watermark.opacity‘ – is set on a scale from 0 (transparent) to 100 (opaque). The default value is ‘100’.


watermark.layer‘ – lets you change the layer position – either in front of or behind the main image. By default, it is in front. If your image has transparency, like the PNG robot below, you could put an image behind it – in this case the Sirv logo:


In the examples below, the original image (on the left) is a PNG-24 with alpha transparency. Placing different images behind it changes the viewers experience of the bottle.

You can add padding around a watermark by applying watermark.canvas.width and watermark.canvas.height. You can crop a watermark by using watermark.crop.width and watermark.crop.height and you can choose the crop starting point with watermark.crop.x and watermark.crop.y. Read more about this in the ‘Watermark crop‘ section.

Watermark scale

Since the original image we are using has a width of 400px and a height of 227px, the watermark is large in relation to the base image size. Adjust this using the ‘watermark.scale.width‘ and ‘watermark.scale.height‘ options.

watermark.scale.width‘ – sets the width of the canvas, in pixels or percentage (%).


watermark.scale.height‘ – sets the height of the canvas, in pixels or percentage (%).


If the watermark.scale.width (or watermark.scale.height) is specified in percent, the dimensions are calculated from the parent image dimensions, not the watermark original image dimensions. Compare the following links and notice that the watermark.scale.width is the same for both:

watermark.scale.option‘ – sets how the scaling of the watermark is managed in regards to the watermark aspect ratio. Available options are: noup (no upscale), fit (fit specified area), fill (fill specified area), ignore (ignore aspect ratio). The default is ‘noup’.


Watermark canvas

watermark.canvas.color‘ – sets the color of the background for the watermark canvas.


watermark.canvas.opacity‘ – is set on a scale from 0 (transparent) to 100 (opaque) to control the background for the watermark canvas. The default value is ‘100’.


Add padding around a watermark by applying watermark.canvas.width and watermark.canvas.height options.

watermark.canvas.width‘ – sets the width of the canvas, in pixels or percentage (%). Setting a value smaller than the size of the watermark image will result in cropping the image.


watermark.canvas.height‘ – sets the height of the canvas, in pixels or percentage (%). Setting a value smaller than the size of the watermark image will result in cropping the image.


Watermark crop

Crop a watermark using ‘watermark.crop.width‘ and ‘watermark.crop.height‘. Choose the crop starting point with watermark.crop.x and watermark.crop.y. The two options must be used together for cropping to take effect.

watermark.crop.width‘ – sets the width of the watermark, in pixels or percentage (%).


watermark.crop.height‘ – sets the height of the watermark, in pixels or percentage (%).


Choose the crop starting point with ‘watermark.crop.x‘ and ‘watermark.crop.y‘. The example shows only the letter ‘V’ from Sirv showing:


Missing watermark

If the watermark image is missing (or there is an error in the file location you chose), a text message ‘No such file or directory‘ will be shown in the center of the parent image, as illustrated below:

Multiple watermarks

You can apply up to 4 image layers in a profile, giving you heaps of creative freedom. Use them for watermarks, decorative effects, lomo-style effects and other uses for which you might otherwise have used Photoshop.

Designate each layer independently as ‘watermark.n‘. Where n is 0, 1, 2, or 3. The image to the right has 3 image layers – in the top left (holly), bottom right (holly rotated) and over the whole image (snow).

The two holly images are the same – the bottom right one has been rotated 180 degrees. It also has a text layer thrown in for good measure. The code for the image on the right is:


Original image

3 image layers and 1 text layer

When referencing images in the URL, use the HTML encoding character ‘%2F’ to represent the / character.


Add borders and effects around your images by applying the frame option. Frames can have different styles, from a plain solid color around the image to styles that bring elements of the image into the frame.

frame.style‘ – sets the type of frame that surrounds the image. Acceptable values are ‘solid‘, ‘mirror‘, ‘edge‘, ‘dither‘, ‘none‘. The default value is ‘solid‘.


mirror‘ – creates a “silvered” semi-opaque frame around the image, allowing some of the image to be seen underneath. The underlying image is a mirror reflection of the nearby image.


edge‘ – creates a “silvered” semi-opaque frame around the image, and blurs the edges of the image underneath the frame.


dither‘ – creates a “silvered” semi-opaque frame around the image, and “feathers” the image under the frame.


frame.color‘ – sets the color of the surrounding frame. The values are set with hex RGB/RGBA or a color name. The default value is ‘black’.


The example below uses the same color as above, with the ‘mirror’ style:


frame.width‘ – sets the width of the surrounding frame, in pixels or percentage (%). The default value is ‘5%’.


frame.rim.color‘ – sets the color of the inner edge of the surrounding frame. The values are set with hex RGB/RGBA or a color name. The default value is ‘white’. The example below has been changed to black.


frame.rim.width‘ – sets the width in pixels or percentage (%) of the inner edge of the surrounding frame. The default value is ‘1’.



Add space around your image by adjusting the canvas size. The examples below use an original image sized 400px by 227px.

canvas.width‘ – sets the width of the canvas, in pixels or percentage (%). If you choose a value smaller than the width of the original image, the image will be cropped.


Example image with wide canvas

canvas.height‘ – sets the height of the canvas, in pixels or percentage (%). If you choose a value smaller than the height of the original image, the image will be cropped. The image below has a 112% canvas width, so white is added to the left and right:


Example canvas with wide canvas and fixed height canvas

canvas.color‘ – sets the color of the background canvas. The values are set with hex RGB/RGBA or a color name. The default value is ‘white’. Here’s an example with dark orange (C16303):


Example image with colored canvas

canvas.position‘ – sets the position of the canvas behind the image. The values, other than the default ‘center’, correspond to points on a compass, with ‘north’ located in the top middle. The allowed values are: north, northeast, northwest, center, south, southeast, southwest, east, and west.


Example image with canvas aligned left

canvas.opacity‘ – is set on a scale from 0 (transparent) to 100 (opaque). The default value is ‘100’. JPEG doesn’t support transparency, so the example below is served as PNG:


Example image with semi transparent canvas as PNG

Canvas border

The canvas border is great for setting a consistently sized border around an image. It can be used with or without the other canvas options.

canvas.border.width‘ and ‘canvas.border.height‘ are set in px or %:


Example image with 40px border

To specify different widths and heights, use both options:


Example image with different border dimensions

canvas.border.color‘ sets a color as a hex ref:


Example image with colored border

canvas.border.opacity‘ adjusts the transparency – only applied to supporting images (not JPEG):


Example image with colored border

Frame and canvas together

As with all Sirv options, Frame and Canvas values may be combined. When doing so, the frame will appear on the outside of the canvas. In other words, the canvas area is considered to be part of the image before a frame is applied.


Below is another example, combining a canvas, frame and a title:


Table of options

Enjoy over 80 options for customizing your images:

wdynamicpx or %Width of image.
hdynamicpx or %Height of image.
scale.optionfitfit (fit specified area), fill (fill specified area), ignore (ignore aspect ratio), noup (no upscaling)Image scaling options.
rotate0-180 to 180Number of degrees to rotate the image.
brightness0-100 to 100Change the brightness of the image.
contrast0-100 to 100Change the contrast of the image.
exposure0-100 to 100Change the exposure of the image.
hue0-100 to 100Change the hue of the image.
saturation0-100 to 100Change the saturation of the image.
lightness0-100 to 100Change the lightness of the image.
shadows0-100 to 100Change the shadows of the image.
highlights0-100 to 100Change the highlights of the image.
grayscalefalsetrue / falseMake the image black & white.
blur00 to 100Blur the image.
colortonenonesepia, warm, cold, sunset, purpletan, texas, noneChange the color tone of the image.
colortone.color000000hex RGB/RGBA or color nameApply a color tone to an image.
colortone.level1000 to 100Set the level of blending with the original image.
colortone.modesolidsolid, highlights, shadowsApply the color tone to the entire image or shadows/highlights only.
vignette.value200 to 100Adjust the depth of the vignette.
vignette.color000000hex RGB/RGBA or color nameAdd a vignette (dark edges) around the image.
formatjpgjpg, png, webp, optimal, originalImage format to be used (about WebP | about optimal).
webp-fallbackOriginaljpg, pngImage format for browsers without WebP support.
q800 to 100JPEG image quality (percentage).
progressivefalsetrue / falseLoad JPEG images progressively.
subsampling4:4:04:4:4, 4:2:2, 4:2:0Chroma subsampling to reduce JPEG file size.
png.optimizefalsetrue/false or 1/0Apply PNG optimizations to reduce PNG file size.
png.compression00 to 9PNG image compression (0 = Huffman, 1-9 = zlib).
png.filteringnonenone, sub, up, average, paeth, adaptiveAdvanced filtering options for PNG images.
filterMitchell/LanczosBartlett, Blackman, Bohman, Box, Catrom, Cosine, Cubic, Gaussian, Hamming, Hann, Hermite, Jinc, Kaiser, Lagrange, Lanczos, Lanczos2, Lanczos2Sharp, LanczosRadius, LanczosSharp, Mitchell, Parzen, Point, Quadratic, Robidoux, RobidouxSharp, Sinc, SincFast, Spline, Triangle, WelchResize filter.
cwpx or %Crop the image to a specific width.
chpx or %Crop the image to a specific height.
cx0px or % or ‘center’Position to start image crop (from top).
cy0px or % or ‘center’Position to start image crop (from left).
autocropfalsetrue/falseAutomatically crop to detected edge of image contents.
spxResize the image by its longest dimension.
thumbnail256pxCreate a square thumbnail of the image, up to 1000px.
textDisplay text on your image.
text.size25%Width of text area in relation to image.
text.font.sizepxFix the size of the text in px.
text.font.stylenormal, italicStyle of the text.
text.font.familyOpen SansAny Google Fonts or Google Noto fontsChoose a font e.g. “Open Sans”.
text.font.weight400300, 400, 600, 700, 800Choose font weight (light, normal, semi-bold, bold, extra-bold).
text.colorgreyhex RGB/RGBA or color nameText color e.g. E0AA80 or E0AA8020.
text.opacity1000 to 100Text opacity.
text.outline.width0pxAdd an outline around the text.
text.outline.color000000hex RGB/RGBA or color nameColor of the text outline.
text.outline.opacity1000 to 100Opacity of the text outline.
text.outline.blur0pxBlur the edge of the text outline.
text.background.colorhex RGB/RGBA or color nameBackground color e.g. E0AA80 or E0AA8020.
text.background.opacity1000 to 100Background opacity.
text.aligncenterright, left, centerAlign the multiline text.
text.positionsoutheastnorth, northeast, northwest, center, south, southeast, southwest, east, westLocation of the text on the image.
text.position.xno default% or pxLocation of the text (from left).
text.position.yno default% or pxLocation of the text (from top).
text.position.gravitynorthwestnorth, northeast, northwest, center, south, southeast, southwest, east, westMaster location of the text on the image.
watermarkFilepath of the image to be overlayed.
watermark.positionsoutheastnorth, northeast, northwest, center, south, southeast, southwest, east, west, tilePosition of the watermark on the image.
watermark.scale.widthdynamicpx or %Width of watermark.
watermark.scale.heightdynamicpx or %Height of watermark.
watermark.scale.optionnoupnoup (no upscale), fit (fit specified area), fill (fill specified area), ignore (ignore aspect ratio)Options to scale the watermark image.
watermark.rotate0-180 to 180Rotate the watermark (degrees).
watermark.opacity1000 to 100Opacity of the watermark image.
watermark.layerfrontfront / backPlace the layer in front or behind main image.
watermark.canvas.colorhex RGB/RGBA or color nameColor behind watermark e.g. E0AA80 or E0AA8020.
watermark.canvas.opacity1000 to 100Opacity of watermark background.
watermark.canvas.widthpx or %Width of canvas.
watermark.canvas.heightpx or %Height of canvas.
watermark.crop.x0px or %Position to start image crop (from top).
watermark.crop.y0px or %Position to start image crop (from left).
watermark.crop.widthpx or %Width of watermark.
watermark.crop.heightpx or %Height of watermark.
frame.stylesolidsolid, mirror, edge, dither, noneAdd a frame around the image.
frame.colornonehex RGB/RGBA or color nameFrame color e.g. E0AA80 or E0AA8020.
frame.width5%px or %Frame width.
frame.rim.colorwhitehex RGB/RGBA or color nameFrame rim color e.g. E0AA80 or E0AA8020.
frame.rim.width1pxFrame rim width.
canvas.widthpx or %Create a canvas around the image (width).
canvas.heightpx or %Create a canvas around the image (height).
canvas.colorwhitehex RGB/RGBA or color nameColor of the canvas e.g. E0AA80 or red.
canvas.positioncenternorth, northeast, northwest, center, south, southeast, southwest, east, westPosition of the canvas behind the image.
canvas.opacity1000 to 100Opacity of the canvas.
canvas.border.width0px or %Adds additional width left and right of the canvas.
canvas.border.height0px or %Adds additional height above and below the canvas.
canvas.border.colorlightgrayhex RGB/RGBA or color nameColor of the canvas border e.g. E0AA80 or red.
canvas.border.opacity00 to 100Opacity of the canvas border.


Every image served from your Sirv account benefits from these space-saving optimizations:

  • Metadata is removed.
  • PNG images are optimized and re-encoded with Huffman compression.
  • Your default image settings are applied, such as 80% JPEG quality (defaults can be changed).
  • If your original images are WebP, they will be automatically converted to JPEG or PNG for non-supporting browsers.


All color parameters in Sirv are applied in the same way, with RGB or RGBA references.

Parameters that have color are:

  • vignette.color
  • text.color
  • text.outline.color
  • text.background.color
  • watermark.canvas.color
  • frame.color
  • frame.rim.color
  • canvas.color

To set a solid color, use a standard RGB reference such as 01417F in your URL or profile), for example:



You can apply the same options to multiple images by creating profiles.

Profiles let you quickly create and manage image styles on your website. When you change the settings for a profile it will update every image on your site which references that profile.

To apply a profile to an image, add the following to the end of the URL:


name is the name of the profile you’d like to apply (found in /Profiles directory). For example:


Image without a profile Image with a profile

Profiles are text files stored in your account written in JSON. They’re easy to create, by choosing from various options in your account.

Here’s an example, of the content inside a Profile. This one will apply a text layer to your images and spins:

  "image": {
    "scale": {
      "width": 1280
    "frame": {
      "style": "none"
    "text": {
      "text": "Text overlay",
      "style": "simple",
      "font": {
        "family": "Open Sans"
      "position": "southeast",
      "color": "cyan",
      "opacity": 50,
      "background": {
        "color": "red",
        "opacity": 10
      "size": 34
  "spin": {
    "width": 400,
    "zoom": 2.5

To create a profile, go to your Profiles folder and click the “Create profile” button.

Profiles are stored as JSON text files in your /Profiles directory.

Order of processing

Image processing options are applied in the following order:

  1. Auto-crop
  2. Scale
  3. Crop
  4. Canvas
  5. Rotate
  6. Other options

For example, if you set scaling and cropping options, the image will first be scaled and then be cropped. The order of options in the URL does not affect the order of image editing.

If the same option is applied via multiple sources, the source with the highest priority is used, in this hierarchy:

  1. URL
  2. Profile
  3. Default profile

For example, if quality is not set in either the URL or a profile, the quality from the Default profile will be used (80% by default). If quality is set via a custom profile and also in the URL (e.g. q=75), the setting in the URL will take precedence.

Special characters

Different browsers render URLs differently and sometimes unpredictably. If you’re adding special characters to your URL (perhaps to create a text overlay), you may need to use the ASCII equivalent:

ASCII CharacterURL-encoding
More…More HTML character codes

Retina support

Sirv can serve tailored images to Retina and hi-res displays.

There are 3 methods for doing this:

1. Generate double width images with Sirv, then scale them in the browser. With this method, every screen (retina or not) will receive the large image. For example, the image below is 800px wide using w=800 and forced to a 400px width area using width=”400″:

<img src="https://demo.sirv.com/Examples/test-girl.jpg?w=800" width="400" />

retina image

2. Alternatively, you can reference the sirv.js script in your page and Sirv will automatically detect the users display and serve hi-res images to hi-res screens and standard images to non-hi-res screens. Refer to the responsive imaging documentation and the responsive imaging examples.

3. Instead of opening using sirv.js (option 2 above), you can use your own JavaScript to detect the users’ display. Then you can fetch the appropriate hi-res or standard-res image at the dimensions you require.

Download URL

To download a file on Sirv, simply append ?dl to the URL to trigger a browser download. For example:


The download parameter can also be added with other parameters. Here’s the same image, resized and with a frame:


Here’s a PDF converted to a 600px image:


URL errors

If there is an error in your URL, an error message will be sent. To see the message, simply visit the image URL in your browser.

The URL below has an error. It should create a 50% width image but width is misspelt as wdth:


Click the URL below to see the error message:


There is no such option as wdth so the message reads “Additional properties not allowed”:

  "name": "ApiDataValidationError",
  "message": "Supplied data is not valid",
  "validationErrors": [
      "message": "Additional properties not allowed",
      "path": "#/scale",
      "params": {
        "properties": [

If you embed a broken image URL in your web page, nothing will be displayed. To see the error message, visit the image directly in your browser.

Caching & deletion

When images are requested for the very first time, Sirv creates them on-the-fly. Once an image exists, it is cached and ready to be rapidly served to anyone else to view.

If nobody views a Sirv generated file for 30 days it will be deleted. Your original images are unaffected – they are never deleted by Sirv.

If you delete images, they go to the Trash for 30 days. You can recover the files simply by moving them out of Trash and into another folder.

Was this article helpful?