API documentation for developers

The basics

URLs

All URLs used to request images from this service take the form

https://dimens.io/ns/:source/:options/:image

You can also use protocol-relative URLs, which start with //....

For example, the URL of the logo at the top left of this page is https://dimens.io/ns/dimensio/120s/logo.png where dimensio is the source, 120s provides the options (120 pixels wide, prefer smoothness) and logo.png is the input image from the dimensio source.

Try the demo

Input image formats

This service can handle JPEG, WebP, PNG and TIFF format image files as input.

For the best results, use non-progressive JPEG at the largest dimensions you think you'll need (up to 10k x 10k pixels) and at a quality setting of at least 90%.

Embed ICC profiles in device-dependent RGB and CMYK input images for automatic conversion to device-independent sRGB.

:source

The source selects the source of input images to be used. This concept is sometimes referred to as "origin" or "upstream" by CDN providers.

An input image source could be an existing website or an Amazon S3 bucket.

Sources are defined in your account, with each consisting of an ID and base URL.

The source ID is specified in the URL path, e.g.:

https://dimens.io/ns/source-id/...

Using Amazon S3 as an input image source

An Amazon S3 bucket can map onto a dimens.io source.

The "bucket policy" (or permissions for individual files) must grant "Open/Download" (a.k.a. "s3:GetObject") to "Everyone".

:options

Options are specified in the request URL after the source.

https://dimens.io/ns/source-id/:options/...

Resize image to an exact width, auto-scaling the height

Provide a width in pixels.

https://dimens.io/ns/source-id/300/... 300 pixels wide.

Resize image to an exact height, auto-scaling the width

Provide a height, in pixels.

https://dimens.io/ns/source-id/x200/... 200 pixels high.

Resize and crop image to fit an exact width and height

Provide both a width and height. Crops the image, keeping the most central part.

https://dimens.io/ns/source-id/300x200/... 300 pixels wide by 200 pixels high.

Resize and crop, keeping the most interesting part of an image

Requires Agency or Prime plan

Add the a modifier to use automated art detection.

https://dimens.io/ns/source-id/300x200a/...

Resize image to a maximum of a given width and height

Provide both a width and height and add the m modifier.

https://dimens.io/ns/source-id/300x200m/... maximum of 300 pixels wide and 200 pixels high.

CSS pixel ratio (density)

Add @2x, @3x or @4x modifiers to the options.

https://dimens.io/ns/source-id/300@2x/... 600 pixels wide.

No need to multiply dimensions - this will be done for you.

Prefer smoothness

This option is suitable for images containing text, line art and diagrams.

Add the s modifier to the options.

https://dimens.io/ns/source-id/300s/... uses a smoother re-sampling technique.

Generate very high quality images

Requires Prime plan

Applies techniques such as gamma correction to produce the very best colour reproduction at a slight performance cost.

Add the q modifier to the options.

https://dimens.io/ns/source-id/300q/... produces a very high quality but larger image.

Output image format

This service can generate JPEG, WebP and PNG format images.

If the input format is also a supported output format, the same format will be used.

The output format can be forced to JPEG, WebP or PNG by adding one of the j, w or p modifiers respectively to the options.

https://dimens.io/ns/source-id/300w/... produces an image in the WebP format.

Progressive/interlace output

Requires Prime plan

This option can be used to generate a progressive JPEG or interlaced PNG image.

Add the i modifier to the options.

https://dimens.io/ns/source-id/300i/... produces an interlaced image.

:image

This is the variable part of the URL from your source.

For example, if your original image is stored in an Amazon S3 bucket with an origin URL of https://example-bucket.s3-eu-west-1.amazonaws.com/images/test.jpg then the image part of that URL is images/test.jpg.

https://dimens.io/ns/source-id/300/images/test.jpg resizes images/test.jpg to 300 pixels wide.

Examples

The recommended approach to support multiple image dimensions and device pixel ratios is to use the srcset attribute of the HTML5 <img> element with the Picturefill polyfill for older browsers.

Using width descriptors:

<img alt="Test" src="https://dimens.io/ns/source-id/300/images/test.jpg"
    srcset="https://dimens.io/ns/source-id/300/images/test.jpg 300w,
      https://dimens.io/ns/source-id/600/images/test.jpg 600w,
      https://dimens.io/ns/source-id/900/images/test.jpg 900w">

Using pixel density descriptors:

<img alt="Test" src="https://dimens.io/ns/source-id/300/images/test.jpg"
    srcset="https://dimens.io/ns/source-id/300/images/test.jpg,
      https://dimens.io/ns/source-id/300@2x/images/test.jpg 2x,
      https://dimens.io/ns/source-id/300@3x/images/test.jpg 3x">

Providing both WebP and JPEG formats via the HTML5 <picture> element:

<picture>
  <source type="image/webp" srcset="https://dimens.io/ns/source-id/300w/images/test.jpg,
    https://dimens.io/ns/source-id/300@2xw/images/test.jpg 2x,
    https://dimens.io/ns/source-id/300@3xw/images/test.jpg 3x">
  <source srcset="https://dimens.io/ns/source-id/300/images/test.jpg,
    https://dimens.io/ns/source-id/300@2x/images/test.jpg 2x,
    https://dimens.io/ns/source-id/300@3x/images/test.jpg 3x">
  <img alt="Test" src="https://dimens.io/ns/source-id/300/images/test.jpg">
</picture>