Skip to main content

On-demand Image Transformations - Overview

FileSpin provides two ways to transform and display images on-the-fly:-

  • Using Standard Image Conversion - Standard Image Conversion is a default image conversion generated for all images. FileSpin uses this Standard Image Conversion as source image to provide the transformed output image. These dynamically transformed images do not use any storage quota. For example, when you request a 300x300 resize of an image asset via a URL such as https://cdn.filespin.io/api/v1/assets//conversions?resize=300,300 , the resize transformation is generated on-demand and delivered instantly.
  • Using Custom Image Conversion - Custom Image Conversions are pre-generated and stored according to the image settings in User account. These Custom Image Conversions can be used for Dynamic image transformations.
info

Make sure to use {user.CDN_HOST} as host so we can deliver on-demand images efficiently for users around the world. If you have custom FileSpin Enterprise CDN, use that CDN host.

On-demand Image (ODI)​

On-demand Image (ODI) provides efficient and high-performance delivery of various image sizes to Web and mobile devices. These are images that are optimised for bandwidth and delivery speed. Ideal use cases are:-

  • to display thumbnails and previews
  • display downsized images when original is a very large image - either in pixel size or file size
  • use the global CDN to deliver these resized images on-demand

To request an ODI, use the Asset ID and request a image transformation like below:-

https://cdn.filespin.io/api/v1/assets/{ASSET_ID}/conversions?resize=200,200

Where resize=200,200 requests a resized image of width 200px and height 200px.

info

FileSpin On-demand images will always be of 72 PPI and preserve aspect ratio. You can specify a maximum width of 2048 and maximum height of 1536. If larger size is specified in options it will default to 2048x1536

AVIF, WebP Support​

By default, the returned images will be avif or webp format for supported browsers. AVIF takes precedence over WebP when both are supported by the browser (as indicated by Accept HTTP request header). When Accept header is not specified or does not specify support for avif or webp, jpg is used fallback format with the exception of PNG images. If original image is a PNG, fallback on-demand image will be avif, webp or png in order to support transparency.

info

Why AVIF

AVIF has better compression than WebP, JPEG, PNG and GIF and is designed to supersede them. AVIF is now supported by all modern browsers. For more information, please see AVIF at Mozilla Developer Docs and AVIF info at caniuse.com

The default on-demand image content type can be overridden using the format option.

Here is a sample on-demand image request URL used in a img tag:-

<img
  src="https://cdn.filespin.io/api/v1/assets/0c3c6d026858460abc4de1dcb4de15ac/conversions?resize=200,200"
/>

The following sections describe all the image transformations supported.

ODI Limitations​

  • On-demand image (ODI) is available for assets after they are processed. Availability of ODI for an asset is indicated with the ON_DEMAND_IMAGE key in addons_info. See Asset Data Format for more info.
  • For large images and cloud files, FileSpin would return a low-resolution thumbnail image if ODI is requested immediately after upload. A short expiration time will be returned in HTTP response header in this case. The ODI URL will be updated with the normal ODI image after the file is processed, usually under 2 seconds.
  • Note that ODI image has a maximum resolution of 2048x1536 and 72 PPI. If the original image has a larger resolution and higher PPI, ODI will be of lower quality than the original. Hence, ODI should not be used for purposes where original image quality is required.