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 the URL):


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 scale.width parameter to the URL. The JPEG image below was 400px width. It has been scaled to 250px width:


250px width image

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


100px height image

Images can also be scaled as a percentage of their original size. This image is 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 scale.width and scale.height, the new image will fit inside the two dimensions (maintaining the original aspect ratio). In the example below, scale.width and scale.height 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 scale.width or scale.height, 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 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 support.

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 ‘quality‘ option for JPEG quality. The scale ranges from 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 ‘quality=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 ‘crop.width‘ to specify the new width in pixels or percent (%). The example below was 400px and is being cropped to 300px:


Use ‘crop.height‘ to specify the new height in pixels or percent (%).


Unless explicitly stated, cropping will start from the top left of the image. This can be adjusted with ‘crop.x‘ and ‘crop.y‘ 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 crop.x and crop.y 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?scale.width=300&text.position=north&text.color=white&text.outline.width=15&text.outline.blur=3&text.size=80&text.text=Let's hit the road&text.font.family=Architects%20Daughter


Example text overlay



text.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.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.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.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.text=Overlay text&text.font.size=24&text.color=FFFFFF&text.opacity=50%

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

The positions are aligned as the points of a compass, with ‘north’ being top center of the image. You can also choose the center. Available values are: north, northeast, northwest, center, south, southeast, southwest, east, and west. The default position is ‘southeast’ (lower right corner).

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

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.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=這裡是一些中文文本。&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.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.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.text=Overlay text&text.font.weight=300

This example sets ‘extra-bold’:

https://demo.sirv.com/Examples/test-girl.jpg?text.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.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.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.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.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.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.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?scale.width=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.image‘ 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

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 70 options for customizing your images:

scale.widthdynamicpx or %Width of image
scale.heightdynamicpx 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 of the image
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
quality800 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 filesize
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
crop.widthpx or %Crop the image to a specific width
crop.heightpx or %Crop the image to a specific height
crop.x0px or % or ‘center’Position to start image crop (from top)
crop.y0px or % or ‘center’Position to start image crop (from left)
autocropfalsetrue/falseAutomatically crop to detected edge of image contents
thumbnail256pxCreate a square thumbnail of the image, up to 1000px
text.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.positionsoutheastnorth, northeast, northwest, center, south, southeast, southwest, east, westLocation of the text on the image
watermark.imageFilepath 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.color000000hex 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 across 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 onto 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.

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 scale.width=800 and forced to a 400px width area using width=”400″:

<img src="https://demo.sirv.com/Examples/test-girl.jpg?scale.width=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?