Image Service

Resize images on the fly! With Storyblok’s out-of-the-box image service, you can give your customers a high-quality, compelling brand experience at a speed they wouldn’t expect, no matter what device or platform they’re using.

Installation / Requirements

You won’t have to install anything to use our Image Service — there are no system requirements either.

How to use it

After uploading an image to Storyblok you can use the image service to optimize, resize and crop them for your needs.

URL Structure: img2.storyblok.com/NEW_SIZE(/FILTERS/…)/YOUR_IMAGE_PATH

If you use the Storyblok rendering service you can also call the resize helper:

{{ blok.image | resize:'300x300' }}

# Example using lazyloaded responsive images with lazysizes.
# https://afarkas.github.io/lazysizes/
<img
  src="{{ blok.image | resize:'100x0' }}"
  data-sizes="auto"
  data-src="{{ blok.image | resize:'300x0' }}"
  data-srcset="{{ blok.image | resize:'300x0' }} 300w,
  {{ blok.image | resize:'600x0' }} 600w,
  {{ blok.image | resize:'900x0' }} 900w" class="lazyload img-responsive" />

For self hosted or client-side projects, it would be easier to write a helper function like the following Javascript or PHP examples:

Example in Javascript

function resize(image, option) {
  var imageService = '//img2.storyblok.com/'
  var path = image.replace('//a.storyblok.com', '')
  return imageService + option + path
}

var example = '//a.storyblok.com/f/39898/1000x664/ab64dad3bc/flowers.jpg'
console.log(resize(example, '500x500'))
// Will give you //img2.storyblok.com/500x500/f/39898/1000x664/ab64dad3bc/flowers.jpg

Example in PHP

<?php

function resize($image, $option) {
  $imageService = '//img2.storyblok.com/';
  $path = str_replace('//a.storyblok.com', '', $image);
  return $imageService . $option . $path;
}

$example = '//a.storyblok.com/f/39898/1000x664/ab64dad3bc/flowers.jpg';

echo resize($example, '500x500');
// Will give you //img2.storyblok.com/500x500/f/39898/1000x664/ab64dad3bc/flowers.jpg

Functions

Resizing

Go to your browser and enter the URL:

img2.storyblok.com/500x500/f/39898/1000x664/ab64dad3bc/flowers.jpg

You should see the image with 500px of width and 500px of height. But if you adjust the dimensions in the URL, you’ll see the image automatically adjust to the dimensions you define.

If you just want it to be proportional to the width, enter a height of 0, like so:

img2.storyblok.com/500x0/f/39898/1000x664/ab64dad3bc/flowers.jpg

Fit-In

The fit-in argument specifies that the image should not be auto-cropped but auto-resized (shrunk) to fit inside an imaginary box of width and height, instead. To fill out the box with a color you can use the fill filter filters:fill(CCCCCC) with a hexadecimal RGB expression (without the “#” character).

Example 1

img2.storyblok.com/fit-in/200x200/filters:fill(CCCCCC)/f/39898/1000x664/ab64dad3bc/flowers.jpg

The output with a grey fill color filters:fill(CCCCCC):

Example 2

img2.storyblok.com/fit-in/200x200/filters:fill(transparent):format(png)/f/39898/1000x664/ab64dad3bc/flowers.jpg

The output with a transparent fill color filters:fill(transparent) and transformed to a png:

---

Quality optimization

You can also change the compression rate of the jpg image using the quality filter. The value can be 0-100.

Example

img2.storyblok.com/200x150/filters:quality(10)/f/39898/1000x664/ab64dad3bc/flowers.jpg

Here’s an example of a jpg picture with a compression rate of 10:

---

Changing the format

You can change the output format of the image, too. Possible options are “webp”, “jpeg”, “gif” or “png”.

Example

img2.storyblok.com/fit-in/200x200/filters:format(gif)/f/39898/1000x664/ab64dad3bc/flowers.jpg

Here’s an example of a jpg picture transformed into a gif:

---

Facial detection and smart cropping

When cropping an image, you can define a smart filter that crops around the focal point, which is determined by a smart algorithm. Just insert the keyword ‘smart’ after the size definition.

Example

//img2.storyblok.com/300x90/smart/f/39898/2247x1500/5e42d053a5/kitchen.jpeg

The output without the smart filter:

The output with the smart filter: