Size

width (w)

This parameter sets the width of the output image. w is an alias for this parameter.

If this parameter is omitted and the height parameter is set, the output width is set automatically such that the aspect ratio is preserved. If both height and width parameters are set, the output image dimensions are set as per the mode parameter.

If none of the height and width parameters are set, the original aspect ratio is preserved, and output dimensions depend on parameters like scale if provided.

The maximum value is 8192, and any output that exceeds this width will be scaled down to this value.

height (h)

This parameter sets the height of the output image. h is an alias for this parameter.

If this parameter is omitted, and the width parameter is set, the output height is set automatically such that aspect ratio is preserved. If both height and width parameters are set, the output image dimensions are set as per mode setting.

If none of the height and width parameters are set, the original aspect ratio is preserved, and output dimensions depend on parameters like scale if provided.

Maximum value for this is 8192, and any output which has more than this height will be scaled down to this value.

dpr

Specifies device pixel ratio. Valid values are between 1.0 and 3.0 and floating point numbers are valid parameters. This acts as a multiplier to both width and height. width=200&height=300&dpr=2 is equivalent to width=400&height=600.

This makes it easy to specify an image with the correct resolution when using srcset attribute of <img> tag.

enlarge

This boolean parameter specifies whether the output image should be enlarged if input image dimensions are smaller than required dimensions.

For example, if input image width is 800px wide and width=1000 is specified, the output image will still remain 800px. If enlarge=true is set, then only the output image will have 1000px width.

Default value of this parameter is false if mode is crop or stretch and true otherwise. You can't override the default false if mode is set to crop or stretch

mode

Specifies the resize behavior when width or height parameters are provided.

• fit: Resize to fit within boundaries specified by width and height parameters. If the ratio given differs from the original aspect ratio, only one dimension will be set as per the given value, and the other dimension will be smaller such that the original aspect ratio is maintained.

• crop: The entire defined area is filled, maintaining aspect ratio, but it might crop part of the image. The type of cropping is determined by the crop parameter.

• stretch: Resize to fill the area defined by height and width. It might not preserve aspect ratio, and the image might be distorted.

• min: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to the width and height specified.

• max: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to the width and height specified.

• fill: Preserving aspect ratio, resize the image to the maximum width or height specified, then embed on a background of the exact width and height as the original image. You can fill excess space with fill parameter.

• fillmax: Resize the image by preserving the aspect ratio and without stretching the original image. If the requested width or height exceeds the original, it will fill the space with a solid color or blurred version of the image, based on fill parameter value.

Default mode is fit.

fill

This parameter specifies how to fill the extra space created by mode=fill.

• solid Fills excess space with solid color specified by parameter fill-color. If fill-color is not specified, then the excess space will be filled with white.

• blur Fills excess space with the blurred original image.

• background Fills excess space with the top-left corner color.

Default value of this parameter is solid.

fill=blur options

With fill=blur, you can adjust the blur intensity. The value ranges from 1 to 100.

crop

Allows you to define crop position when using crop as mode parameter.

Valid values are entropy, smart, top, topleft, left, bottomleft, bottom, bottomright, right, topright , faces, center and focalpoint.

While other modes are self-explanatory, let us first describe some special crop modes.

• faces: detects all faces in an image and tries to keep them centered in the cropped image.

• entropy: focuses on the region with the highest Shanon entropy.

• smart: focus on the region with the highest luminance frequency and skin tones. Gumlet automatically finds a person or other objects in the image and keeps them in the center while cropping.

• focalpoint: focus on the point given by you. It allows you to define the point of focus by fp-x and fp-y. You can also define zoom using fp-z. fp-x and fp-y must be a float value between 0.0 to 1.0 and the default value will be 0.5. fp-z can be in the range of 1 to 10 and the default value is 1.

Default mode if no parameter is provided is center.

mask

It masks the image as per the given input. Current supported mask shapes are ellipse and corners.

• ellipse: Mask image into ellipse shape. When the masked image is output as a PNG, the masked area will be transparent; otherwise, it will be the default background. To get the circle shape with mask, the output image must have the same width and height; otherwise, it will be oval.
• corners: Mask corners of the image are rounded. One can control it using therpixelsparameter by providing a pixel value that needs to be rounded.

extract (rect)

Extract a region from the image. rect is an alias for this parameter. This operation is always applied before resize operation. Please give the parameters according to the original image.

The value should be provided as a comma-separated list left,top,width,height.

• left is a zero-indexed offset from the left edge
• top is a zero-indexed offset from the top edge
• width of the extracted image
• height of extracted image

aspect ratio (ar)

Resize and crop the image to the given aspect ratio. This parameter will work only with mode=crop. ar is proportional representation between width and height.

E.g. ar=3:4&mode=crop will crop the image in an aspect ratio of 3:4. You can add one dimension (height or width) along with ar , and the other dimension will be automatically calculated based on the aspect ratio. height=400&ar=3:4&mode=crop Here, width 300 will be automatically calculated.

pad

Pads/Extends the edges of the image with the color provided by the background parameter. The value should either be an integer, which adds padding of the same number of pixels to all edges, or it should be a comma-separated list of 4 integers as top,right,bottom,left.

E.g. pad=40,20,40,30 will add 40px padding on top, 20px on right, 40px on bottom and 30px on left. If you want to add the same padding to all sides, you can provide just one number like pad=40 and it will add 40px on all sides.

Please note this operation will add additional pixels and hence increase height and width of image. This operation is applied after resize. Please provide padding parameters accordingly.

trim

Trim "boring" pixels from all edges that contain values within a percentage similarity of the top-left pixel. The value of this parameter is number between 1 to 99 representing the percentage similarity.

This operation is applied after resize.

If you want to match a custom color and not use the top-left pixel, you can pass a hex color code by using trim-color parameter. For example trim=10&trim-color=fafafa.

dpi

Dots per inch (DPI) specifies how we should convert SVG or PDF files, which are vector images, to raster images like JPEG. The higher the parameter, the bigger the default output sizes will be.

Default value is 72.

Image Size Parameters Summary