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:

https://demo.sirv.com/Examples/test-girl.jpg

Here is the same image scaled to 300px (notice the URL):

https://demo.sirv.com/Examples/test-girl.jpg?scale.width=300

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:

https://demo.sirv.com/Examples/test-girl.jpg?scale.width=300&colortone=texas&frame.style=mirror&text.text=%C2%A9Steve%20Wilson&text.size=40%&text.color=white&text.position=northeast&text.font.family=Shadows%20Into%20Light%20Two

Options

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.

Scale

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:

https://demo.sirv.com/Examples/test-girl.jpg?scale.width=250

250px width image

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

https://demo.sirv.com/Examples/test-girl.jpg?scale.height=100

100px height image

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

https://demo.sirv.com/Examples/test-girl.jpg?scale.width=50%

Image scaled to 50% width

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

https://demo.sirv.com/Examples/test-girl.jpg?scale.width=200%

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

https://demo.sirv.com/Examples/test-girl.jpg?scale.height=150&scale.width=150

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:

https://demo.sirv.com/Examples/test-girl.jpg?scale.width=350&scale.height=120&scale.option=fill

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

https://demo.sirv.com/Examples/test-girl.jpg?scale.width=100&scale.height=200&scale.option=ignore

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:

https://demo.sirv.com/Examples/test-girl.jpg?scale.width=800&scale.height=600&scale.option=noup

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

Rotate

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

https://demo.sirv.com/Examples/test-girl.jpg?rotate=45

Brightness

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

https://demo.sirv.com/Examples/test-girl.jpg?brightness=30

https://demo.sirv.com/Examples/test-girl.jpg?brightness=-30

Contrast

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

https://demo.sirv.com/Examples/test-girl.jpg?contrast=30

https://demo.sirv.com/Examples/test-girl.jpg?contrast=-30

Exposure

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

https://demo.sirv.com/Examples/test-girl.jpg?exposure=20

Overexposed

https://demo.sirv.com/Examples/test-girl.jpg?exposure=-20

Underexposed

Hue

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

https://demo.sirv.com/Examples/test-girl.jpg?hue=20

https://demo.sirv.com/Examples/test-girl.jpg?hue=-20

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

https://sirv.sirv.com/website/demos/adidas/adidas-01-01.jpg?hue=-83
https://sirv.sirv.com/website/demos/adidas/adidas-01-01.jpg?hue=-50
https://sirv.sirv.com/website/demos/adidas/adidas-01-01.jpg?hue=-17
https://sirv.sirv.com/website/demos/adidas/adidas-01-01.jpg?hue=17
https://sirv.sirv.com/website/demos/adidas/adidas-01-01.jpg?hue=50
https://sirv.sirv.com/website/demos/adidas/adidas-01-01.jpg?hue=83

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

Saturation

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

https://demo.sirv.com/Examples/test-girl.jpg?saturation=30

Increased saturation (30)

https://demo.sirv.com/Examples/test-girl.jpg?saturation=-30

Reduced saturation (-30)

Lightness

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

https://demo.sirv.com/Examples/test-girl.jpg?lightness=20

Lighter image (20)

https://demo.sirv.com/Examples/test-girl.jpg?lightness=-20

Darker image (-20)

Shadows

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

https://demo.sirv.com/Examples/test-girl.jpg?shadows=15

Greater shadows (15)

https://demo.sirv.com/Examples/test-girl.jpg?shadows=-15

Reduced shadows (-15)

Highlights

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

https://demo.sirv.com/Examples/test-girl.jpg?highlights=15

Greater highlights (15)

https://demo.sirv.com/Examples/test-girl.jpg?highlights=-15

Reduced highlights (-15)

Grayscale

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

https://demo.sirv.com/Examples/test-girl.jpg?grayscale=true

Blur

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

https://demo.sirv.com/Examples/test-girl.jpg?blur=10

Colortone

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.

sepia

https://demo.sirv.com/Examples/test-girl.jpg?colortone=sepia

warm

https://demo.sirv.com/Examples/test-girl.jpg?colortone=warm

cold

https://demo.sirv.com/Examples/test-girl.jpg?colortone=cold

sunset

https://demo.sirv.com/Examples/test-girl.jpg?colortone=sunset

purpletan

https://demo.sirv.com/Examples/test-girl.jpg?colortone=purpletan

texas

https://demo.sirv.com/Examples/test-girl.jpg?colortone=texas

Vignette

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.

https://demo.sirv.com/Examples/test-girl.jpg?vignette.value=50

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.

https://demo.sirv.com/Examples/test-girl.jpg?vignette.color=red

Red vignette on image

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

https://demo.sirv.com/Examples/test-girl.jpg?vignette.color=ff0000

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

https://demo.sirv.com/Examples/test-girl.jpg?vignette.color=blue&vignette.value=50

Blue vignette

https://demo.sirv.com/Examples/test-girl.jpg?vignette.color=ff8c00&vignette.value=100

Colored vignette

https://demo.sirv.com/Examples/test-girl.jpg?vignette.color=ffffff&vignette.value=40

White vignette

Image format

Output your images in either JPEG, PNG, or WebP format, regardless of the image format you originally upload. Serving the most suitable format for each image helps ensure the best balance between quality and fast downloading.

To change the format, add the ‘format‘ parameter with a value of jpg‘, ‘png‘ or ‘webp‘, for example:

https://demo.sirv.com/Examples/test-girl.jpg?format=png

Optimal

With format set to “optimal”, Sirv will serve the most ideal file format for the users device. This is often WebP format, but might also be an optimized PNG or a compressed JPEG. Whether your original images are in JPEG, PNG or GIF format, choosing “optimal” will ensure every one of your viewers receives the fastest loading image format for their device.

Original

With format set to “original”, Sirv will always serve the original image format to all devices/browsers. Images will be optimized/compressed but they will not change format.

WebP

WebP is an uncommon yet outstanding image format, made easy for you by Sirv.

This new image format compresses images to much lower file-sizes than their PNG and JPEG equivalents. The difference is typically 40-70% smaller file size, without loss of image quality. Developed by Google, WebP supports transparency and alpha, making it a powerful alternative to both JPEG and PNG.

As of October 2016, about 62% of web users could view WebP files and this will grow. Currently, Chrome and Opera support it while Safari and Firefox intend to add WebP support in a future browser version. However, there is no reason not to start using WebP immediately because Sirv automatically detects if a browser supports it. If supported, Sirv serves a WebP version of your image, otherwise it will fall back to either JPEG or PNG.

To tell Sirv to serve your JPEG and PNG images in WebP format, set the ‘format‘ option to ‘webp‘ like so:

https://sirv.sirv.com/Examples/test-image.png?format=webp

If you’re 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. However, when served in WebP format, it is only 25.5kb.

If you’re one of the cutting-edge WebP aficionados who already upload images to Sirv 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):

https://sirv.sirv.com/Examples/test-image.webp

WebP example image

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

Use the ‘webp.fallback‘ option to control what type of image should be served if WebP is not supported by the browser.

If no image format is set, WebP images will fall back to JPEG. You can make it fall back to PNG like so:

https://sirv.sirv.com/Examples/test-image.webp?webp.fallback=png

JPEG

JPEG quality

Sirv compresses your images to 85% 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.

https://demo.sirv.com/Examples/test-girl.jpg?quality=40

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

https://demo.sirv.com/Examples/test-girl.jpg?progressive=true

JPEG subsampling

Subsampling allows you to reduce the filesize of the resulting JPEG image. Subsampling is expressed as a three part ratio J:a:b (e.g. 4:2:2) that 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.

Set the ‘subsampling‘ option with this ratio. The available parameters are: 4:4:4, 4:2:2, 4:2:0. The default is 4:4:4.

https://demo.sirv.com/Examples/test-girl.jpg?subsampling=4:2:2

The image above is about 20% smaller than the original JPEG.

PNG

PNG optimization

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

png.optimize‘ lets you apply PNG optimizations to reduce the PNG file size. Specify the setting with the values ‘true’/’false’ or ‘1’/’0′. The default value is ‘false’, meaning that the optimization is turned off.

https://demo.sirv.com/Examples/test-girl.jpg?format=png&png.optimize=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 will be obvious 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.

https://demo.sirv.com/Examples/test-girl.jpg?format=png&png.compression=1

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

https://demo.sirv.com/Examples/test-girl.jpg?format=png&png.filtering=paeth

Image filters

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

Each filter gives very 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:

https://demo.sirv.com/Examples/test-girl.jg?filter=Hamming

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

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:

https://demo.sirv.com/Examples/test-girl.jpg?crop.width=300

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

https://demo.sirv.com/Examples/test-girl.jpg?crop.height=100

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:

https://demo.sirv.com/Examples/test-girl.jpg?crop.height=166&crop.width=166&crop.x=107&crop.y=17

You can crop around the center of the image by setting crop.x and crop.y to ‘center’:

https://demo.sirv.com/Examples/test-girl.jpg?crop.height=250&crop.width=190&crop.x=center&crop.y=center

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

https://demo.sirv.com/Examples/test-girl.jpg?crop.height=50%&crop.width=100%&crop.y=center&crop.x=center

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

https://demo.sirv.com/Examples/test-girl.jpg?scale.width=50%&scale.height=50%&crop.height=120&crop.width=120&crop.x=40&crop.y=0

Thumbnail

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

https://demo.sirv.com/Examples/test-girl.jpg?thumbnail=150

The largest possible thumbnail is 256px. 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.

Examples:

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

https://sirv.sirv.com/Examples/test-air.jpg?scale.width=300&text.position=south&text.text=The%20new%20Macbook%20Air...&text.size=80%&text.background.opacity=15&text.background.color=white

Example text overlay

https://sirv.sirv.com/Examples/test-lake.jpg?scale.width=300&text.position=southwest&text.text=Canada,%20Summer%202014&text.size=54%&text.font.family=Open%20Sans&text.color=f0f0f0&text.opacity=90

Text

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:

https://sirv.sirv.com/Examples/test-sky.jpg?scale.width=360&text.0.text=Hello&text.0.position=north&text.0.size=20%&text.0.color=ffffff&text.1.text=World!&text.1.position=south&text.1.size=34%&text.1.color=ffffff

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:

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png

The Sirv logo is a PNG image with a width of 418px and a height of 164px. 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.

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest

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

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=tile

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

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=tile&watermark.scale.width=130&watermark.opacity=30%

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:

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest&watermark.scale.height=36&watermark.rotate=-45&watermark.canvas.opacity=0

watermark.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?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest&watermark.scale.height=44&watermark.opacity=50

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:

https://sirv.sirv.com/Examples/test-image.png?scale.height=250&watermark.image=/website/sirv-logo-dark-blue.png&watermark.scale.width=250&watermark.opacity=30%&watermark.position=center&watermark.layer=back

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 (%).

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest&watermark.scale.width=124

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

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest&watermark.scale.height=25

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

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest&watermark.scale.height=24&watermark.scale.option=ignore

Watermark canvas

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

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest&watermark.scale.height=25&watermark.canvas.color=red

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

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest&watermark.scale.height=25&watermark.canvas.color=red&watermark.canvas.opacity=25

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.

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest&watermark.scale.height=25&watermark.canvas.color=red&watermark.canvas.opacity=25&watermark.canvas.width=50%

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.

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest&watermark.scale.height=25&watermark.canvas.color=red&watermark.canvas.opacity=25&watermark.canvas.height=150%

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 (%).

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest&watermark.scale.height=25&watermark.canvas.color=red&watermark.canvas.opacity=25&watermark.crop.width=40&watermark.crop.height=100%

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

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest&watermark.scale.height=25&watermark.canvas.color=red&watermark.canvas.opacity=25&watermark.crop.width=100%&watermark.crop.height=20

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

https://demo.sirv.com/Examples/test-girl.jpg?watermark.image=/website/sirv-logo-dark-blue.png&watermark.position=northwest&watermark.scale.height=49&watermark.canvas.opacity=0&watermark.canvas.width=74&watermark.canvas.height=90&watermark.crop.x=88&watermark.crop.y=0

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:

https://sirv.sirv.com/website/demos/girl-hat.jpg?scale.width=300&watermark.0.image=%2fwebsite%2fdemos%2fchristmas1.png&watermark.0.position=northwest&watermark.0.scale.width=70%&watermark.1.image=%2fwebsite%2fdemos%2fchristmas1.png&watermark.1.position=southeast&watermark.1.rotate=180&watermark.1.scale.width=70%&watermark.2.image=%2fwebsite%2fdemos%2fsnowfall.png&watermark.2.scale.width=300&text.3.text=Merry%20Christmas!&text.3.position=south&text.3.font.weight=bold&text.3.size=75%&text.3.color=white&text.3.outline.color=black&text.3.outline.width=12


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.

Frame

Add borders and effects around your images by using the frame options. The most common frame is a solid color around the image, but other values allow you to bring elements of the image into the surrounding frame.

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

https://sirv.sirv.com/Examples/test-sky.jpg?frame.style=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.

https://sirv.sirv.com/Examples/test-sky.jpg?frame.style=mirror

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

https://sirv.sirv.com/Examples/test-sky.jpg?frame.style=edge

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

https://sirv.sirv.com/Examples/test-sky.jpg?frame.style=dither

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

https://sirv.sirv.com/Examples/test-sky.jpg?frame.style=solid&frame.color=CA6902

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

https://sirv.sirv.com/Examples/test-sky.jpg?frame.style=mirror&frame.color=CA6902

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

https://sirv.sirv.com/Examples/test-sky.jpg?frame.style=mirror&frame.color=CA6902&frame.width=40

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.

https://sirv.sirv.com/Examples/test-sky.jpg?frame.style=mirror&frame.color=white&frame.width=40&frame.rim.color=black

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

https://sirv.sirv.com/Examples/test-sky.jpg?frame.style=mirror&frame.color=white&frame.width=40&frame.rim.color=black&frame.rim.width=6

Canvas

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.

https://sirv.sirv.com/Examples/test-sky.jpg?canvas.width=112%

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:

https://sirv.sirv.com/Examples/test-sky.jpg?canvas.width=112%&canvas.height=260

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

https://sirv.sirv.com/Examples/test-sky.jpg?canvas.width=112%&canvas.height=260&canvas.color=C16303

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.

https://sirv.sirv.com/Examples/test-sky.jpg?canvas.width=112%&canvas.height=260&canvas.color=C16303&canvas.position=west

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:

https://sirv.sirv.com/Examples/test-sky.jpg?canvas.width=112%&canvas.height=260&canvas.color=C16303&;canvas.opacity=50&format=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.

https://sirv.sirv.com/Examples/test-sky.jpg?canvas.width=103%&canvas.height=104%&canvas.color=C16303&frame.style=mirror&frame.color=874300&;frame.width=18

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

https://sirv.sirv.com/Examples/test-bike.jpg?canvas.width=370&canvas.height=256&canvas.color=WhiteSmoke&scale.width=300&text.position=north&text.text=Take%20me%20to%20the%20velodrome&text.font.family=Architects%20Daughter&text.color=black&text.size=50%&frame.style=solid&frame.color=CadetBlue&frame.width=6

Table of options

Enjoy over 70 options for customizing your images:

OptionDefaultOptionsDescription
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
quality850 to 100JPEG image quality (percentage)
progressivefalsetrue / falseLoad JPEG images progressively
subsampling4:4:44: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)
thumbnail256pxCreate a square thumbnail of the image
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.stylenonesolid, 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.colorwhitehex RGB/RGBA or color nameColor of the canvas border e.g. E0AA80 or red
canvas.border.opacity00 to 100Opacity of the canvas border

Optimization

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

  • Metadata is removed.
  • PNG images are re-encoded with Huffman compression.
  • Your default image settings are applied, such as 85% 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.

Color

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:

https://sirv.sirv.com/Examples/test-vibram.jpg?text.position=southwest&text.text=Blue%20text&text.color=01417F&text.size=40%

Profiles

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:

?profile=name

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

https://demo.sirv.com/Examples/test-girl.jpg?profile=Example-Text

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.

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:

https://demo.sirv.com/Examples/test-girl.jpg?scale.wdth=50%

Click the URL below to see the error message:

https://demo.sirv.com/Examples/test-girl.jpg?scale.wdth=50%

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

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

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.

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
space%20
/%2F
!%21
%22
#%23
$%24
%%25
&%26
%27
(%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 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.

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?