Image Transformation

The Image Transformation API allows you to transform images on-the-fly. You can resize, crop, rotate, and apply various filters to images. The API is designed to be simple and easy to use, and it is optimized for performance.

Basic Usage

To transform an image, you need to specify the URL of the image you want to transform and the transformation parameters. The URL of the image is specified using the url parameter, and the transformation parameters are specified using the transform parameter.

Here is an example of transforming an image:

<img src="https://files.markupgo.com/image-url?width=300&height=200"/>

In this example, the image is transformed to have a width of 300 pixels and a height of 200 pixels.

Transformation Parameters

The following transformation parameters are supported:

quality

Specifies quality for images in JPEG, WebP, and AVIF formats. The quality is in a 1-100 scale, but useful values are between 50 (low quality, small file size) and 90 (high quality, large file size). 85 is the default. When using the PNG format, an explicit quality setting allows use of PNG8 (palette) variant of the format.

quality=85

width

Specifies the width of the image in pixels.

width=300

height

Specifies the height of the image in pixels.

height=200

background

Specifies the background color of the image. The background color can be specified using a hex color code or a color name.

background=red

blur

Specifies the amount of blur to apply to the image. The blur is in a 1-250 scale, with 0 being no blur and 250 being maximum blur.

blur=10

brightness

Increase brightness by a factor. A value of 1.0 equals no change, a value of 0.5 equals half brightness, and a value of 2.0 equals twice as bright. 0 is ignored. Example:

brightness=1.5

compression

Slightly reduces latency on a cache miss by selecting a quickest-to-compress file format, at a cost of increased file size and lower image quality. It will usually override the format option and choose JPEG over WebP or AVIF. We do not recommend using this option, except in unusual circumstances like resizing uncacheable dynamically-generated images.

compression=fast

contrast

Increase contrast by a factor. A value of 1.0 equals no change, a value of 0.5 equals low contrast, and a value of 2.0 equals high contrast. 0 is ignored. Example:

contrast=1.5

dpr

Device Pixel Ratio. Default is 1. Multiplier for width/height that makes it easier to specify higher-DPI sizes in <img srcset>. Example:

dpr=2

fit

Affects interpretation of width and height. All resizing modes preserve aspect ratio. Available modes are:

• contain: Image will be resized (shrunk or enlarged) to be as large as possible within the given width or height while preserving the aspect ratio. If you only provide a single dimension (for example, only width), the image will be shrunk or enlarged to exactly match that dimension. Example:
• cover: Resizes (shrinks or enlarges) to fill the entire area of width and height. If the image has an aspect ratio different from the ratio of width and height, it will be cropped to fit. Example:
• crop: Image will be shrunk and cropped to fit within the area specified by width and height. The image will not be enlarged. For images smaller than the given dimensions, it is the same as scale-down. For images larger than the given dimensions, it is the same as cover. See also trim. Example:
• scale-down: Similar to contain, but the image is never enlarged. If the image is larger than given width or height, it will be resized. Otherwise its original size will be kept. Example:
• pad: Resizes to the maximum size that fits within the given width and height, and then fills the remaining area with a background color (white by default). This mode is not recommended, since you can achieve the same effect more efficiently with the contain mode and the CSS object-fit: contain property. Example:

fit=contain

gamma

Increase exposure by a factor. A value of 1.0 equals no change, a value of 0.5 darkens the image, and a value of 2.0 lightens the image. 0 is ignored. Example:

gamma=1.5

rotate

Number of degrees (90, 180, or 270) to rotate the image by. width and height options refer to axes after rotation. Example:

rotate=90

sharpen

Specifies strength of sharpening filter to apply to the image. The value is a floating-point number between 0 (no sharpening, default) and 10 (maximum). 1 is a recommended value for downscaled images. Example:

sharpen=1

trim

Specifies a number of pixels to cut off on each side. Allows removal of borders or cutting out a specific fragment of an image. Trimming is performed before resizing or rotation. Takes dpr into account. For image transformations, use as four numbers in pixels separated by a semicolon, in the form of top;right;bottom;left or via separate values trim.width,trim.height, trim.left,trim.top. Example:

trim=20;30;20;0
trim.width=678
trim.height=678
trim.left=30
trim.top=40