Docs
General
Image Service

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 do not have to install anything in your application to use our Image Service.

Documentation

After uploading an image to Storyblok you can use the image service to optimize, resize and crop them for your needs by modifing the image URL. To enable our image service you will have to replace //a.storyblok.com with //img2.storyblok.com in your asset urls followed by different filters and parameters. Every image will be transformed on our server for you, after resizing it once it will automatically be shipped through our CDN so you can load it as fast as possible.

Hint: SVG (Scalable Vector Graphics) are paths that can’t be cropped, resized or optimized since they already scale automatically.

We will use the following image as our example image:

Flower Demo Image

Resizing

Type	Base	Param	Resource
Original	https://a.storyblok.com		/f/39898/3310x2192/e4ec08624e/demo-image.jpeg
Resized - Static	https://img2.storyblok.com	/500x500	/f/39898/3310x2192/e4ec08624e/demo-image.jpeg
Proportional to Width	https://img2.storyblok.com	/200x0	/f/39898/3310x2192/e4ec08624e/demo-image.jpeg
Proportional to Height	https://img2.storyblok.com	/0x200	/f/39898/3310x2192/e4ec08624e/demo-image.jpeg

Resizing: Static

Resized - Static

Resizing: Proportional to Width

Proportional to Width

Resizing: Proportional to Height

Proportional to Height

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). If you want to fill your image with transparence pixels you can use filter:fill(transparent) combined with :format(png). Your image will be transformed into an png and filled with transparence pixels even tho the file extention is still the .jpeg of the original source.

Type	Base	Param	Resource
Original	https://a.storyblok.com		/f/39898/3310x2192/e4ec08624e/demo-image.jpeg
Fit-In with CCCCCC background	https://img2.storyblok.com	/fit-in/200x200/filters:fill(CCCCCC)	/f/39898/3310x2192/e4ec08624e/demo-image.jpeg
Fit-In with transparent background	https://img2.storyblok.com	/fit-in/200x200/filters:fill(transparent):format(png)	/f/39898/3310x2192/e4ec08624e/demo-image.jpeg

Fit-In with CCCCCC background

Fit-In with transparent background

Fit-In with CCCCCC background

Changing the format

To change the image format you can use the format filter. Supported formats are “webp”, “jpeg” and “png”.

Example:

https://img2.storyblok.com/200x0/filters:format(png)/f/39898/3310x2192/e4ec08624e/demo-image.jpeg

png

Quality optimization

You can change the compression rate of your images using the quality filter. The value can be 0-100.

Type	Base	Param	Resource
Original	https://a.storyblok.com		/f/39898/3310x2192/e4ec08624e/demo-image.jpeg
10% Quality	https://img2.storyblok.com	/filters:quality(10)	/f/39898/3310x2192/e4ec08624e/demo-image.jpeg
Resized and 10% Quality	https://img2.storyblok.com	/200x0/filters:quality(10)	/f/39898/3310x2192/e4ec08624e/demo-image.jpeg

Resized and 10% Quality

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. Since flowers do not have a face we will use a different demo image.

Type	Base	Param	Resource
Original	https://a.storyblok.com		/f/39898/2250x1500/c15735a73c/demo-image-human.jpeg
Resized without Smart Crop	https://img2.storyblok.com	/600x130	/f/39898/2250x1500/c15735a73c/demo-image-human.jpeg
Resized with Smart Crop	https://img2.storyblok.com	/600x130/smart	/f/39898/2250x1500/cad7bf2a0d/demo-image-human.jpeg

Resized without Smart Crop

Resized with Smart Crop

Custom focal point

In case you want use a custom focal point to define the center of the image you can add a filter to the url like following:

filters:focal(<left>x<top>:<right>x<bottom>)

Examples:

Focus on the bottom of the image:

https://img2.storyblok.com/600x130/filters:focal(450x500:550x600)/f/39898/1000x600/d962430746/demo-image-human.jpeg

Resized custom focal point

Focus on the top of the image:

https://img2.storyblok.com/600x130/filters:focal(450x0:550x100)/f/39898/1000x600/d962430746/demo-image-human.jpeg

Resized custom focal point

Code Examples

function transformImage(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(transformImage(example, '500x500'))
// Will give you //img2.storyblok.com/500x500/f/39898/1000x664/ab64dad3bc/flowers.jpg

<?php

function transfromImage($image, $param) {
  $imageService = '//img2.storyblok.com/';
  $resource = str_replace('//a.storyblok.com', '', $image);
  return $imageService . $param . $resource;
}

$example = '//a.storyblok.com/f/39898/3310x2192/e4ec08624e/demo-image.jpeg';

echo transfromImage($example, '500x500');
// Will give you //img2.storyblok.com/500x500/f/39898/3310x2192/e4ec08624e/demo-image.jpeg

// In your main.js you can register a custom filter
// https://vuejs.org/v2/guide/filters.html
Vue.filter('transformImage', function (image, option) {
  if (!image) return ''
  if (!option) return ''

  let imageService = '//img2.storyblok.com/'
  let path = image.replace('//a.storyblok.com', '')
  return imageService + option + path
})

// Useage: 
{{ image | transformImage('100x0') }}

def transform_image(image, param)
   image_service = '//img2.storyblok.com/';
   resource = image.sub! '//a.storyblok.com', ''
   return image_service << param << resource 
end

example = '//a.storyblok.com/f/39898/3310x2192/e4ec08624e/demo-image.jpeg'
puts transform_image(example, '500x500')
# Will give you //img2.storyblok.com/500x500/f/39898/3310x2192/e4ec08624e/demo-image.jpeg

def transform_image(image, param):
  image_service = '//img2.storyblok.com/';
  resource = image.replace('//a.storyblok.com', '')
  return image_service + str(param) + resource

example = '//a.storyblok.com/f/39898/3310x2192/e4ec08624e/demo-image.jpeg'
transform_image(example, '500x500')
# Will give you //img2.storyblok.com/500x500/f/39898/3310x2192/e4ec08624e/demo-image.jpeg