Dynamic imaging

Create images of any size or style instantly. It's fast and easy, with no technical knowledge required. Each option is explained in this guide, with a list of 100 options below. Or try all options in the image wizard.

For best results, we recommend uploading your highest quality images.

URL format

New images are created by appending options to the image URL.

This image URL has no options:

https://demo.sirv.com/looks.jpg

This image URL has a w option that scales it to 300px width:

https://demo.sirv.com/looks.jpg?w=300

Pixel values are referenced using the number only. For percentage values, add a % sign, e.g. 40%.

Here is the same image with many options - notice how multiple parameters in the URL are separated by the & character:

https://demo.sirv.com/looks.jpg?w=300&colortone=texas&frame.style=mirror&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, with examples, to the left.

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

Table of options

Use over 100 options to customize your images:

Optimization

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.

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=Blue%20text&text.size=40%&text.color=01417F

Profiles

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:

?profile=name

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

https://demo.sirv.com/look.jpg?profile=Example-Text

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:

Retina support

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

There are 3 methods for doing this:

1. Use the srcset attribute in your img tag. This way the user's browser will automatically load the appropriate image according to their display's pixel density.
<img src="https://demo.sirv.com/look.jpg" srcset="https://demo.sirv.com/look.jpg?w=400 1x, https://demo.sirv.com/look.jpg?w=800 2x, https://demo.sirv.com/look.jpg?w=1200 3x" width="400" />

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:

https://demo.sirv.com/example.jpg?dl

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

https://demo.sirv.com/example.jpg?w=500&frame.style=mirror&frame.width=25&dl

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

https://demo.sirv.com/dyson.pdf?w=600&dl

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 returned. 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/look.jpg?scale.wdth=50%

Click the URL below to see the error message:

https://demo.sirv.com/look.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.

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.

Timestamps

If a URL contains a timestamp (e.g. for file versioning), this will be ignored because Sirv is designed for on-the-fly processing and CDN caching. Sirv instantly invalidates old files, so timestamping via the query string is not required. Instead, to update an old file, you should either overwrite the original file with the new one or change its name.

Master images

The bigger the images you upload, the more options you'll have. For best results, we recommend:

• 2500-4000px width
• 92% JPEG quality or higher

Sirv hosts and delivers any image type (and other files too). It automatically resizes and optimizes images to suit your users device, keeping the 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.

Note that Sirv does not limit the number of image variations, nor does it count the variations towards your storage usage. This makes it a very attractive alternative to Cloudinary.

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

Processing large images

If you upload images larger than 16 MB in file size, they will be pre-processed, to accelerate future image processing. This contributes towards Sirv's extremely fast on-the-fly image processing and allows us to potentially process master images as large as 128 MB.

The pre-processed version of an image will be stored in the /.processed folder, which is hidden within your account at my.sirv.com but can be seen via FTP/S3/REST API. Do not delete the images, otherwise it won't be possible to serve them. If a pre-processed image is deleted, the master image should be reuploaded.

If a master image is deleted from your account, the pre-processed version will also be deleted.

Pre-processed images count towards the total storage used by your account. They are usually much less than half the size of the master image, so the additional storage is relatively low. If the pre-processed and master images are both larger than 33.55 MB in file size, then that would exceed Sirv's maximum image processing file size, so processing won't be possible and the pre-processed version will be deleted. In such a case, you should upload a smaller master image - either reduce the dimensions of your image or apply some light compression to it before upload.

Pre-processing is applied to all image formats (JPEG, PNG, TIFF, PSD) and PDF files between 16 MB and 128 MB.

Image formats

Sirv can convert and transform all types of image. All the following file types can be resized, optimized and served in the most optimal format:

• JPEG
• PNG
• WebP
• AVIF
• GIF
• EPS
• TIFF
• PSD (Adobe Photoshop)
• AI (Adobe Illustrator)
• PDF

Hundreds of other file types can also be served by Sirv, automatically optimized/minified for fast loading. They are all delivered from Sirv's fast, global CDN.

Cheat sheet

This PDF list of all dynamic imaging options is a quick way to reference all the parameters you can use for modifying images.