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.
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:
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
Resizing: Proportional to Width
Resizing: 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 transparent 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 extension 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
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
Quality optimization
You can change the compression rate of your JPEG 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
Focus on the top of the image:
https://img2.storyblok.com/600x130/filters:focal(450x0:550x100)/f/39898/1000x600/d962430746/demo-image-human.jpeg