Image Optimization API

Parameter Reference

Learn how each query parameter affects your image.


NameDescriptionParameterAccepted valuesExample
BrightnessAdjusts the image brightness.briNumbers between -100 and +100, where 0 represents no change.bri=35
ContrastAdjusts the image contrast.conNumbers between -100 and +100, where 0 represents no change.con=25
GammaAdjusts the image gamma.gamNumbers between 0.1 and 9.99.gam=0.5
SharpenSharpen the image.sharpNumbers between 0 and


NameDescriptionParameterAccepted valuesExample
BackgroundSets the background colour of the image.bg3 digit RGBbg=222
4 digit ARGB (alpha)bg=5DDD
6 digit RGBbg=E0FC4A
8 digit ARGB (alpha)bg=55E0FC4A
Any of the 140 colour names supported by all modern


NameDescriptionParameterAccepted valuesExample
BorderAdd a border to the image.borderMust use the format width,color,methodborder=15,00d6b4,shrink


Sets the border width in pixels, or using relative dimensions.

Relative dimensions allow you to specify a width or height value as a percentage of the main image.

To use a relative dimension, simply provide a percentage as a number (between 0 and 100), followed by a w (width) or h (height). For example, 5w represents 5% of the width of the main image.


Sets the border colour - see the background parameter for accepted values.


Sets how the border will be displayed. Available options:

  • overlay: Place border on top of image (default).
  • shrink: Shrink image within border (canvas does not change).
  • expand: Expands canvas to accommodate border.


Cropping is mostly done with the fit parameter, but you can also do a lot more with it than just cropping. Read more about the fit parameter here.

NameDescriptionParameterAccepted valuesExample
Fitted CropCrops the image based on what w or h values you set.fitcropfit=crop&h=250&w=250
PositionYou can also set where the image is cropped by adding a crop position.fitOne of:

Default is crop-center, and is the same as crop.
Focal PointBe specific about the exact crop position using a focal point.fitUse two offset percentages:
ZoomZoom into your focal point by providing a third value: a float between 1 and 100.

Each full step is the equivalent of a 100% zoom. (eg. x%-y%-2 is the equivalent of viewing the image at 200%).
fitThe suggested range is 1-10 e.g.
CropCrops the image to specific dimensions prior to any other resize operations.cropRequired format: width,height,x,ycrop=900,1400,3000,1600


The device pixel ratio is used to easily convert between CSS pixels and device pixels.

This makes it possible to display images at the correct pixel density on a variety of devices such as Apple devices with Retina Displays and Android devices.

You must specify either a width, a height, or both for this parameter to work.

NameDescriptionParameterAccepted valuesExample
DPRDisplay images at the correct pixel density.dprNumbers between 1 and 8.

Default is 1.


NameDescriptionParameterAccepted valuesExample
BlurAdds a blur effect to the image.blurNumbers between 0 and 100blur=15
PixelateApplies a pixelation effect to the image.pixelNumbers between 0 and 1000.pixel=25
FilterApplies a filter effect to the image.filtgreyscale or sepiafilt=sepia


NameDescriptionParameterAccepted valuesExample
QualityDefines the quality of the image.qNumbers between 0 and 100.

Defaults to 90.

Only relevant if the format is set to jpg, pjpg, webp or avif.
FormatEncodes the image to a specific format.fmAccepts jpg, pjpg (progressive jpeg), png, gif, webp or avif.

Defaults to jpg.


The fit parameter sets how the image is fitted to its target dimensions.

The accepted values for fit are as follows:

containThis is the default.

Resizes the image to fit within the width and height boundaries without cropping, distorting or altering the aspect ratio.
maxResizes the image to fit within the width and height boundaries without cropping, distorting or altering the aspect ratio, and will also not increase the size of the image if it is smaller than the output
fillResizes the image to fit within the width and height boundaries without cropping or distorting the image, and the remaining space is filled with the background color.

The resulting image will match the constraining dimensions.
fill-maxResizes the image to fit within the width and height boundaries without cropping but upscaling the image if it's smaller.

The finished image will have remaining space on either width or height (except if the aspect ratio of the new image is the same as the old image).

The remaining space will be filled with the background color and the resulting image will match the constraining dimensions.
stretchStretches the image to fit the constraining dimensions exactly.

The resulting image will fill the dimensions, and will not maintain the aspect ratio of the input image.
cropResizes the image to fill the width and height boundaries and crops any excess image data.

The resulting image will match the width and height constraints without distorting the image.

See the crop section for more information.

Flip & Rotate

NameDescriptionParameterAccepted valuesExample
FlipFlips the image.flipAccepts v, h and both.flip=v
OrientationRotates the image.orAccepts auto, 0, 90, 180 or 270.

Default is auto.

The auto option uses Exif data to automatically orient images correctly.


NameDescriptionParameterAccepted valuesExample
WidthSets the width of the image in pixels.wAny number.w=250
HeightSets the height of the image in pixels.hAny number.h=250