Docs

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.

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

draw

You can draw additional images on top of a generated image, with transparency and blending effects. This enables adding of watermarks, logos, signatures, vignettes, and other effects to resized images.

Draw options

The draw property is an array. Overlays are drawn in the order they appear in the array (the last array entry is the topmost layer). Each item in the draw array is an object, which can have the following properties:

  • url

Absolute URL of the image file to use for the drawing. It can be any of the supported file formats. For drawing watermarks or non-rectangular overlays, We recommend that you use PNG or WebP images.

  • width and height

Maximum size of the overlay image, in pixels. It must be an integer.

  • fit and gravity

Affects interpretation of width and height. Same as for the main image. Default is contain.

  • opacity

Floating-point number between 0 (transparent) and 1 (opaque). For example, opacity: 0.5 makes overlay semitransparent.

  • repeat

If set to true, the overlay image will be tiled to cover the entire area. This is useful for stock-photo-like watermarks.
If set to "x", the overlay image will be tiled horizontally only (form a line).
If set to "y", the overlay image will be tiled vertically only (form a line).

  • top, left, bottom, right

Position of the overlay image relative to a given edge. Each property is an offset in pixels. 0 aligns exactly to the edge. For example, left: 10 positions left side of the overlay 10 pixels from the left edge of the image it is drawn over. bottom: 0 aligns bottom of the overlay with bottom of the background image.

Setting both left and right, or both top and bottom is an error.

If no position is specified, the image will be centered.

  • background

Background color to add underneath the overlay image. Same as for the main image.

  • rotate

Number of degrees to rotate the overlay image by. Same as for the main image.

Drawing examples

  • All URLs in the draw array must be absolute URLs. Relative URLs are not supported.
  • The draw values should be URL-encoded. The example URLs in this section are not URL-encoded for readability.

Photo Watermark

https://files.markupgo.com/{image-url}
?draw[0][url]=https://example.com/watermark.png
&draw[0][repeat]=true 
&draw[0][opacity]=0.2

Signature

https://files.markupgo.com/{image-url}
?draw[0][url]=https://example.com/signature.png
&draw[0][bottom]=5
&draw[0][right]=5

Centered Play Button

https://files.markupgo.com/{image-url}
?draw[0][url]=https://example.com/play-button.png

Combined

https://files.markupgo.com/{image-url}
?draw[0][url]=https://example.com/watermark.png
&draw[0][repeat]=true
&draw[0][opacity]=0.2
&draw[1][url]=https://example.com/play-button.png
&draw[2][url]=https://example.com/signature.png
&draw[2][bottom]=5
&draw[2][right]=5