All images in a shop can be automatically scaled and cropped to any size (as long as it is not larger than the original image). This is achieved by adding a few parameters to the image URL.
You should almost always limit the file size - do not let your shop users download unnecessarily large images.
Starting early 2017, images will be converted to JPEG, unless they contain transparency or
if they are animated. Cached images will not be re-generated unless you change the parameters. The
bg parameter will enable images with transparency to be converted to JPEG as well.
Note that depending on the image source:
- The resolution might be lower than what you requested.
- The returned image might be converted from PNG or GIF to JPEG.
- The JPEG quality may be lower than what you requested.
||The maximum width of the returned image in pixels.|
||The maximum height of the returned image in pixels.|
||The resize method to use. The default value is
||From which side to scale if no hotspot is defined. Leaving this out defaults to
||The image quality.|
||The maximum file size in kB).|
|bg||hex code||Background to fill transparent images with|
max-width and max-height
Setting one or both of the
max-height properties will return an image scaled
proportionally to fit within those constraints. An image can be scaled down, but never scaled up.
Example: Fetch a proportionally scaled image with the maximum width of 300px:
If we requested
max-width=600 the delivered image would be 500px wide, since
that is the width of the original image.
Example: Fetch a proportionally scaled image with the maximum with of 300px and the maximum height of 300px:
resize value is
scale. To crop an image you must:
* Set both
* Set the
resize query parameter to
gravity can be used together with
resize=crop. It is only applied if the image does not have a
By default (if no gravity is specified), an image is cropped from the center. By setting
west, the image will be cropped from the top, bottom, right or left
quality it is possible to decrease (but never increase) the image quality for JPEG images.
If no quality parameter is passed it is set to
The value of
quality can be seen as a recommendation to the server. Under different circumstances
it can either be increased or decreased:
- Image quality will never exceed the quality of the original image.
- If a larger image is requested than what the server can deliver, the quality will be increased to compensate for the lack of pixels, but at the same time the file size will be kept at a reasonable level.
Example: Reduce the file size by setting a lower JPEG-quality:
max-size takes a value (in kB) and scales down the image to approximately this value.
In practice, this is useful as a complement to
max-height, especially when you
don't know if the returned image can be converted to JPEG or not.
Example: The result might be an animated GIF, in which case 1200x1200px is not reasonable. Limit the file size to approximately 4MB:
bg sets a background color to fill transparency in transparent images. This effectively means
that PNG will be converted to JPEG, reducing their file size.
Example: Set the background to white, so that we don't need transparency:
width and height (deprecated)
height are deprecated and are available for compatibility reasons only. Setting
height is analogous to setting
without the possibility of using
An image can have a defined "hotspot". This is the part of the image that is the most important to preserve when cropping. When someone requests a cropped version of an image, we zoom in on the hotspot. We try to include the whole hotspot in the cropped image, but in a few cases this is not possible, e.g. when someone requests a very narrow image and the hotspot is very wide.
The hotspot is a rectangle of any size. The coordinates are stored in the comment metadata of
the original image. The comment should be in the form
800x600+50+40). If such a comment is found inside an image it is used as the hotspot. Otherwise,
the whole image is taken as the hotspot (i.e. as little as possible is cropped away).
Original image: Let's say we have an original image of a necklace, with a hotspot area centered on the lower part of the image, here marked with a purple rectangle for clarity.
Cropping: Resizing the image to
300×200 results in cropping. We achieve an effect
of zooming in on the hotspot.
Cropping and scaling: Resizing the image to an even smaller size, here to
in both cropping and scaling, showing the whole hotspot part of the image but scaling it down to the