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 100 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:


Example image without dynamic imaging options

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


Image scaled to 300px 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:


Image with dynamic image options in URL


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


Image scaled to 150px height/width

Scale options

‘scale.option’ – controls how Sirv scales images. It defaults to fit, which scaled the image to within whichever is the lesser of w or h. You can change it to fill to scale an image to whichever is the greater of w or h (to fill a particular area). The example below disregards the height of 120px and creates an image of 350px width:


Image scaled to 350px width with fill

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


Image stretched to 100px width and 200px height

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:


Image with no upscaling


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


Image rotated 45 degrees


‘opacity’ adjusts the transparency of PNG images, from 0 to 100% (default is 100). Here is the Sirv logo with 50% opacity:


Sirv logo with 50% opacity


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


Example image brightened


Example image darkened


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


Example image with increased contrast


Example image with decreased contrast


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


Overexposed image


Underexposed image


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


Example image, different hue = 20


Example image, different hue = -20

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 intensity 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 intensity of highlights in the image.


Greater highlights (15)


Reduced highlights (-15)


Levels can correct the tonal range and color balance of an image.

colorlevel.white‘ is set on a scale from 1 to 255, where 255 is the default.

White level increased


colorlevel.black‘ is set on a scale from 0 to 254, where 0 is the default.

Black level increased


Black and white levels can be applied at the same time:

Black and white levels changed


Levels can be used to obtain pure white backgrounds, desirable for ecommerce product photography. Below, Sirv turns an off-white background to pure white. Then it shows an automatically cropped version, using Sirv’s autocrop feature:

Autocrop and white levels Increased white levels Autocrop and white levels



Sirv can generate a histogram of your image, to help you understand its tonal range. It analyses each pixel of your image and plots it as a chart. The chart’s numerical range goes from 0-255, counting pixels of 0 as totally black and pixels of 255 as totally white.

histogram‘ can be set as ‘rgb‘ (for red, green and blue), or any of r/g/b separately.

Histogram of RGB colors



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


Grayscale image example


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


Image with blur applied


sharpen‘ applies sharpening to an image, to emphasize texture, reduce blur and give focus to the image. The range is set on a scale from 0 (the default) to 100.


Image with sharpening applied


Colorize is a simple way to wash a color over an entire image.bl

colorize.color‘ – sets the color to be overlaid, which is black by default. It can be any hex color or HTML color name.

colorize.opacity‘ – regulates the opacity of the color from 0-100, with a default of 100%.

This example applies the HTML color brown at 30% opacity:


Image with a 30% sandy brown colorized overlay

This example applies the hex color 317bba at 40% opacity:


Image with blue overlay with 40% opacity


colortone‘ alters the color scheme of an image. It can add emotion to images, with Instagram-style effects.

Create your own custom colortone or apply a preset colortone. Preset colortones are: sepia; warm; cold; sunset; purpletan; texas; aurora; blackberry; coffee; clearwater; dusk and stereo. The default value is ‘none‘.



Sepia colortone image



Warm colorone image



Cold colortone image



Sunset colortone image



Purpletan colortone image



Texas colortone image


Aurora colortone image



Blackberry colortone image



Coffee colortone image



Clearwater colortone image



Dusk colortone image



Stereo colortone image

Custom colortones

Create your own style with 3 advanced colortone options: colortone color, colortone level and colortone mode.

‘colortone.color’ sets the color applied to an image. Apply the color with hex RGB or an HTML color name, like so:


Image with orange color tone

Apply a hex RGB color like so:


Image with hex color tone

‘colortone.level’ sets the amount color tone that is applied, with 0 being no tone and 100 being maximum tone (the default).


Original image without color tone

Colortone level 40

Image with colortone level 40

Colortone level 80

Image with colortone level 80

‘colortone.mode’ applies tone to either shadows, highlights or, by default, to the entire image (solid).



Image with color tone applied to the whole image



Image with color tone applied to highlights



Image with color tone applied to shadows

Multiple color tones

For more advanced effects, you can apply up to 3 color tones to an image.

Apply the first tone with colortone.0.color, colortone.0.level and colortone.0.mode. Apply the 2nd tone with colortone.1.color, colortone.1.level and colortone.1.mode. Apply an optional 3rd tone with colortone.2.color, colortone.2.level and colortone.2.mode.

This image has 2 color tones:


Image with 2 color tones

This image has 3 color tones:


Image with 3 color tones

Color tones with other effects

Create an even greater range of styles by combining colortone with other Sirv imaging options. The image to the right has greater contrast, brightness, shadows and a colortone:


Original image without processing options


Image with contrast, brightness, shadows and 2 color tones

Here’s an image with a different combination: increased highlights, shadows and saturation are followed by colortone option:


Original image without dynamic imaging options


Example image with contrast, highlights, shadows and 2 color tones

This image increases contrast, reduces saturation, then applies colortone and vignette:


Original image without dynamic imaging options


Example image with contrast, saturation, vignette and 2 color tones


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 applied as HTML color name

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


Red vignette applied as hex value

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


Blue 50%-vignette on image


Colored 100%-vignette


White 40%-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 their existing format 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)


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 original quality Example image 92% quality
Example image 90% quality Example image 85% quality
Example image 80% quality Example image 75% 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.

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 “optimal” format automatically serves lossy WebP images to supporting browsers and 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 November 2018, 72% of web users could view WebP images. Chrome, Edge, Opera and Android browsers support WebP now, while Firefox will support it from v65 onwards.

As WebP is enabled by default in the “optimal” image format, you need not 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 a WebP supporting browser, 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 KB. When served in WebP format, it is only 18 KB.

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 original WebP. If your browser does not support WebP, Sirv automatically serves it in JPEG format:


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:


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 applies PNG optimization by default, to dramatically reduce the file 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.

The amount of PNG 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.

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


png.optimize‘ lets you control PNG optimization with either true/false or 1/0. By default, PNG optimization is enabled for the optimal format (default) and disabled if ‘format’ is set to a different value.

If you have changed the ‘format’ value and wish to enable PNG optimization, set it to ‘true’, like so:


Example image optimized PNG

PNG optimization dramatically speeds up delivery of your images, though it takes slightly longer to process than a JPEG image. Sirv performs up to 20 passes to find the best optimizations possible. The first viewer may experience a short delay (typically 0.15 to 1.00 second) before the image is served to them. Processed images are cached and immediately available for future viewers.

The first person to view an image won’t notice a delay when viewing just one PNG but it might be noticeable to the first person viewing a 360 spin of PNGs, because spins usually consist of 36 images or more.

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

Unoptimized PNG Optimized PNG

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:


Hamming image filter

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:


Image cropped in width

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


Image cropped in 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:


Image cropped in width and height

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


Image cropped in width and height with center specified as starting point

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


Image cropped to 50% height from center

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


Resized and cropped image


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


Thumbnail image

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


Automatically crop an image on a solid background color. This is useful for achieving a uniform look for your images, for example to standardize ecommerce product images.

Set ‘crop.type‘ to trim:


Original image, not cropped Autocropped image

To increase the space between the object and the image edge, add padding by using ‘crop.pad.x‘ and ‘crop.pad.y‘. This example adds 7% padding:


Autocropped image with 7% padding

Face detection crop

Automatically detect faces in your image and crop them. Sirv uses deep learning neural networks, trained on millions of images to accurately detect faces in images. Faces can be detected in as little as 200ms.

Set ‘crop.type‘ to face. Example:


Original image, not cropped Face detection cropped image

To reduce the size of the face (scale), use ‘ch‘ and ‘cw‘.


Face detected image, scaled to 150px

If there is more than 1 face, specify which face to crop by using ‘crop.face=0‘ where 0 is the number of face (from 0 upwards).


To see how Sirv detects faces, apply ‘crop.dev=1‘ to the image. A red box will be drawn around the face, like so:


Point of interest crop

Automatically identify the most interesting part of the image and crop into it. This machine learning crop algorithm gives you instant creative direction.

Set ‘crop.type‘ to ‘poi‘. Example:


Original image, not cropped Autocropped image based on point of interest

Control the crop using ‘ch‘ and ‘cw‘.


Autocropped image based on point of interest

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=400&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

Bicycle with 'Let's hit the road' text overlay


Macbook Air with text overlay


Landscape with 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!

Example image with text overlay

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%

Example image with 50% text size

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 with 50% size white text

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

Example image with 50% size white text with 50% opacity

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.color=FFFFFF&text.position=center

Example image with 50% size white center-positioned text

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 image with 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.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

Bitter text font

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

Noto Sans CJK TC text font

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

Overlay text font size 18px

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

Overlay text italic style

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

Light text font weight

This example sets ‘extra-bold’:

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

Extra-bold text font weight

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

5px outline around text overlay

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

Colored 15px outline around text overlay

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 overlay with colored 50%-opacity outline

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 overlay with colored blurred outline

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 overlay with colored 50%-opacity background

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

Text overlay with solid colored background

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

Each text layer can have their own options and up to 100 characters of text. 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 customized text watermarks

Watermark overlays

Overlay images on top of others to create watermarks and other creative designs. Up to 4 images can be overlaid on top (or behind) an image, giving you many creative possibilities. PNG images are usually preferable as you can control their opacity.

watermark‘ – specifies the filepath of the overlaid image in your Sirv account, starting with /. This example overlays a Sirv logo on a bag:


Image with PNG watermark overlaid

watermark.scale.width‘ and ‘watermark.scale.height‘ – set the width and/or height of the watermark in pixels or percentage (%). This example sets 75px height:


Watermark with scaled height

When set in percent, the watermark is scaled according to the parent image. The following images have the same watermark.scale.width of 25%, so they inherit 25% of however wide the parent image is:

Watermark with scaled width
Watermark with scaled width

watermark.scale.option‘ – sets how the watermark scales when both watermark.scale.width and watermark.scale.height are set. The default ‘noup’ will not upscale the watermark beyond its original size. You can also choose ‘fit’ to fit inside the specified width/height, ‘fill’ to fill the width/height (and spill over) or ‘ignore’ to stretch the watermark.

watermark.position‘ – sets the position of the watermark as either ‘center’, ’tile’ or the point on a compass: ‘north’, ‘northeast’, ‘northwest’, ‘south’, ‘southeast’, ‘southwest’, ‘east’, ‘west’. The default is ‘center’.

This example sets it to ‘northwest’:


Image with watermark positioned at Northwest

The ‘tile‘ setting repeats the watermark across the image:


Image with tile watermatk

Combine it with other settings to achieve the example below:


Image with resized opaque tile watermark

Alternatively, watermarks can be located elsewhere, with a choice of three options.

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

watermark.position.gravity‘ – sets the starting point for shifting the x & y values. The default compass position is northwest (top left) and can be changed to any compass location, or center. The example below moves the watermark down (watermark.position.y) by 23% from the north position:


Example image without watermark overlay Example image with watermark overlay

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


Image with half-transparent watermark

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


Image with watermark rotated by 45 degrees

watermark.layer‘ – lets you change the layer position – either in front or behind the 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:


Sirv watermark behind image

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

Bottle image with no background Bottle with party background Bottle image with beach background Bottle image with ice background

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 ‘0’.

watermark.canvas.color‘ – sets the color of the background for the watermark canvas. The default is transparent.


Image with watermark on red 25%-transparent background

watermark.canvas.width and watermark.canvas.height – changes the size of the canvas to add padding, in pixels or percentage (%). A value smaller than the size of the watermark image will crop it.


Image with watermark on 25% red background 150% width and height canvas

Watermark crop

watermark.crop.width‘ and ‘watermark.crop.height‘ – crop the watermark in either pixels or percentage (%).


Image with watermark on red 25%-transparent background cropped to 45% width

watermark.crop.x‘ and ‘watermark.crop.y‘ – set the starting point of the crop:


Image with watermark cropped by width and height

Missing watermark

If the watermark image is missing, a text message ‘No such file or directory‘ will be shown in the center of the image:

Image with missing watermark

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 with no overlays
Original image
Image with 3 watermarks and 1 text
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‘.


Example image with solid black frame

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.


Example image with mirror frame

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


Example image with edge frame

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


Example image with dither 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’.


Example image with solid colored frame

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


Example image with mirror-style colored frame

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


Example image with 40%-width frame

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.


Example image with black-rimmed frame

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


Frame with 6%-width black rim


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 image 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.


Exanple image with colored canvas and solid colored frame

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


Example image with text overlay, solid dark-blue frame and colored canvas

Table of options

Enjoy over 90 options for customizing your images:

Option Default Options Description
w dynamic px or % Width of image.
h dynamic px or % Height of image.
scale.option fit fit (fit specified area), fill (fill specified area), ignore (ignore aspect ratio), noup (no upscaling) Image scaling options.
rotate 0 -180 to 180 Number of degrees to rotate the image.
opacity 100 0 to 100 Opacity of PNG images.
brightness 0 -100 to 100 Change the brightness of the image.
contrast 0 -100 to 100 Change the contrast of the image.
exposure 0 -100 to 100 Change the exposure of the image.
hue 0 -100 to 100 Change the hue of the image.
saturation 0 -100 to 100 Change the saturation of the image.
lightness 0 -100 to 100 Change the lightness of the image.
shadows 0 -100 to 100 Change the shadows of the image.
highlights 0 -100 to 100 Change the highlights of the image.
colorlevel.black 0 0-254 Adjust black level of image.
colorlevel.white 255 1-255 Adjust white level of image.
histogram rgb r/g/b Display a histogram of RGB levels.
grayscale false true / false Make the image black & white.
blur 0 0 to 100 Blur the image.
sharpen 0 0 to 100 Sharpen the image.
colorize.color black hex RGB or color name Overlay a color on the image.
colorize.opacity 100 0 to 100 Opacity of the color overlay.
colortone none sepia, warm, cold, sunset, purpletan, texas, aurora, blackberry, coffee, clearwater, dusk, stereo, none Change the color tone of the image.
colortone.color 000000 hex RGB or color name Apply a color tone to an image.
colortone.level 100 0 to 100 Set the level of blending with the original image.
colortone.mode solid solid, highlights, shadows Apply the color tone to the entire image or shadows/highlights only.
vignette.value 20 0 to 100 Adjust the depth of the vignette.
vignette.color 000000 hex RGB/RGBA or color name Add a vignette (dark edges) around the image.
format jpg jpg, png, webp, optimal, original Image format served (about WebP, about optimal).
webp-fallback Original jpg, png Image format for browsers without WebP support.
q 80 0 to 100 JPEG image quality (percentage).
progressive false true / false Load JPEG images progressively.
subsampling 4:4:0 4:4:4, 4:2:2, 4:2:0 Chroma subsampling to reduce JPEG file size.
png.optimize false true/false or 1/0 Apply PNG optimizations to reduce PNG file size.
filter Mitchell/Lanczos Bartlett, 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, Welch Resize filter.
gif.lossy 5 0-100 Apply lossy compression, to reduce GIF file size.
cw px or % Crop the image to a specific width.
ch px or % Crop the image to a specific height.
cx 0 px or % or ‘center’ Position to start image crop (from top).
cy 0 px or % or ‘center’ Position to start image crop (from left).
autocrop false true/false Automatically crop to detected edge of image contents.
s px Resize the image by its longest dimension.
thumbnail 256 px Create a square thumbnail of the image, up to 1000px.
page 0 number Page number of PDF when converted to image.
text Display text on your image.
text.size 25 % Width of text area in relation to image.
text.font.size px Fix the size of the text in px.
text.font.style normal, italic Style of the text.
text.font.family Open Sans Any Google Fonts or Google Noto fonts Choose a font e.g. “Open Sans”.
text.font.weight 400 300, 400, 600, 700, 800 Choose font weight (light, normal, semi-bold, bold, extra-bold).
text.color grey hex RGB/RGBA or color name Text color e.g. E0AA80 or E0AA8020.
text.opacity 100 0 to 100 Text opacity.
text.outline.width 0 px Add an outline around the text.
text.outline.color 000000 hex RGB/RGBA or color name Color of the text outline.
text.outline.opacity 100 0 to 100 Opacity of the text outline.
text.outline.blur 0 px Blur the edge of the text outline.
text.background.color hex RGB/RGBA or color name Background color e.g. E0AA80 or E0AA8020.
text.background.opacity 100 0 to 100 Background opacity.
text.align center right, left, center Align the multiline text.
text.position southeast north, northeast, northwest, center, south, southeast, southwest, east, west Location of the text on the image.
text.position.x no default % or px Location of the text (from left).
text.position.y no default % or px Location of the text (from top).
text.position.gravity northwest north, northeast, northwest, center, south, southeast, southwest, east, west Master location of the text on the image.
watermark Filepath of the image to be overlayed.
watermark.position center north, northeast, northwest, center, south, southeast, southwest, east, west, tile Position of the watermark on the image.
watermark.position.x no default % or px Location of the watermark (from left).
watermark.position.y no default % or px Location of the watermark (from top).
watermark.position.gravity northwest north, northeast, northwest, center, south, southeast, southwest, east, west Master location of the watermark on the image.
watermark.scale.width dynamic px or % Width of watermark.
watermark.scale.height dynamic px or % Height of watermark.
watermark.scale.option noup noup (no upscale), fit (fit specified area), fill (fill specified area), ignore (ignore aspect ratio) Options to scale the watermark image.
watermark.rotate 0 -180 to 180 Rotate the watermark (degrees).
watermark.opacity 100 0 to 100 Opacity of the watermark image.
watermark.layer front front / back Place the layer in front or behind main image.
watermark.canvas.color hex RGB/RGBA or color name Color behind watermark e.g. E0AA80 or E0AA8020.
watermark.canvas.opacity 100 0 to 100 Opacity of watermark background.
watermark.canvas.width px or % Width of canvas.
watermark.canvas.height px or % Height of canvas.
watermark.crop.x 0 px or % Position to start image crop (from top).
watermark.crop.y 0 px or % Position to start image crop (from left).
watermark.crop.width px or % Width of watermark.
watermark.crop.height px or % Height of watermark.
frame.style solid solid, mirror, edge, dither, none Add a frame around the image.
frame.color none hex RGB/RGBA or color name Frame color e.g. E0AA80 or E0AA8020.
frame.width 5% px or % Frame width.
frame.rim.color white hex RGB/RGBA or color name Frame rim color e.g. E0AA80 or E0AA8020.
frame.rim.width 1 px Frame rim width.
canvas.width px or % Create a canvas around the image (width).
canvas.height px or % Create a canvas around the image (height).
canvas.color hex RGB/RGBA or color name Color of the canvas e.g. E0AA80 or red.
canvas.position center north, northeast, northwest, center, south, southeast, southwest, east, west Position of the canvas behind the image.
canvas.opacity 100 0 to 100 Opacity of the canvas.
canvas.border.width 0 px or % Adds additional width left and right of the canvas.
canvas.border.height 0 px or % Adds additional height above and below the canvas.
canvas.border.color lightgray hex RGB/RGBA or color name Color of the canvas border e.g. E0AA80 or red.
canvas.border.opacity 0 0 to 100 Opacity 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:


Example image with customized text overlay


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 Character URL-encoding
space %20
/ %2F
! %21
# %23
$ %24
% %25
& %26
( %28
) %29
* %2A
+ %2B
, %2C
© %A9
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 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:


The dl option downloads a processed image with the default account settings plus additional settings in the URL. It cannot be used to download the unmodified original 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?