Specify an aspect ratio to follow when resizing the image.
Aspect ratio must be used in addition to crop, contain, face, or force resize modes. If none of the above resize modes is set, the final image will keep its original aspect ratio, ignoring the value of the aspect-ratio parameter.
Optionally it is also possible to use width or height together with aspect-ratio parameter, restricting the final image size.
Using aspect-ratio with width or height parameters is particularly useful when you want one of the image dimensions automatically calculated and generate an image with a specific aspect ratio.
Notice that is also possible to use aspect-ratio, width, and height parameters at the same time, resulting in a final image with the expected aspect ratio but restricted to the specified size values.
Values
This parameter expects two numbers greater than zero separated by a colon in the form w:h where w is the width and h is the height.
Some examples of valid aspect-ratio values are 1:1 (square), 3:2, or 16:9 (widescreen). Floating point numbers are accepted so values such as 1.85:1 or 2.76:1 are also valid.
Examples
For this example we set a width of 800 pixels with width=800, an aspect ratio of 1:1 (square) with aspect-ratio=1:1 and cropping with mode=crop, generating an output image of 800x800 pixels:
GET
https://assets.imglab-cdn.net/flowers.jpeg?width=800&aspect-ratio=1%3A1&mode=crop
We set a width of 800 pixels with width=800, an aspect-ratio of 16:9 with aspect-ratio=16:9 and cropping with mode=crop resulting in an image of 800x450 pixels:
GET
https://assets.imglab-cdn.net/flowers.jpeg?width=800&aspect-ratio=16%3A9&mode=crop
For this example we will use the same parameters as for the previous one but using mode=contain instead of mode=crop. Notice how the final image has an aspect ratio of 16:9 but the contained original image aspect ratio is preserved. We have additionally set contain=blur to use a blurred version of the image for the excess space. This image also has a final size of 800x450 pixels:
GET
https://assets.imglab-cdn.net/flowers.jpeg?width=800&aspect-ratio=16%3A9&mode=contain&contain=blur