/v4/dims Endpoint

/v4/dims/<clientId>/<signature>/<timestamp>/<commands>.../?url=<image>

The dims endpoint lets you crop, resize, and apply other transformations to images.

An image manipulation request is made up of one or more commands that will transform an image, such as resize/100x100. These commands will be applied on the image provided in the url parameter. They are applied in the order they appear in the URL.

Let's break down the example we used in the Getting Started section:

/v4/dims/default/6d3dcb6/2147483647/resize/100x100/?url=https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg

Breaking the request down into its parts we get the following:

URL:

Query String:

Error Handling

This endpoint will always return an image. When a command fails dims will return an auto-generated image using the background color defined in the DIMS_ERROR_BACKGROUND environment variable.

The auto-generated error image will be resized and/or cropped to match the requested image so it'll fit nicely in the space where the original image would have been.

Signing

All requests to this endpoint must be signed. Signing requests ensures that the image request has not been changed.

The signature is a MD5-56 hash of:

• timestamp
• signingKey
• imageCommands
• imageUrl.

Those values should be concatenated together without any spaces or other characters between them, and then hashed.

Note:

• imageCommands should not have a preceding slash but should include a trailing slash if included in the URL. (/).

  • ✅️resize/100x100/crop/10x10+25+25

  • ✅️resize/100x100/crop/10x10+25+25/

  • ❌️/resize/100x100/crop/10x10+25+25/

  • ❌️/resize/100x100/crop/10x10+25+25

• imageUrl should not be url encoded.

  • ✅️https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg

  • ❌️https%3A%2F%2Fimages.pexels.com%2Fphotos%2F1539116%2Fpexels-photo-1539116.jpeg

• timestamp is a unix timestamp (seconds since epoch).

Bringing that all together, here is an example of how to sign a request using the example from above:

❯ echo -n "2147483647mysecretresize/100x100https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg" | md5 | cut -b 1-7
6d3dcb6

We've wrapped this up into a command to make signing and validating requests easier.

Use the sign command to sign a request by passing in a URL to sign, and setting the signing key in the DIMS_SIGNING_KEY environment variable.

The signature part of your URL does not need to be valid but must be 7 characters long. The sign command will replace it with a valid signature and output the result.

❯ docker run -e DIMS_SIGNING_KEY=mysecret ghcr.io/beetlebugorg/go-dims sign 'https://myhost.com/v4/dims/default/1234567/2147483647/resize/100x100/?url=https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg' --dev
Image to be transformed:

https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg

Transformation commands found:

resize('100x100')

http://localhost:8080/v4/dims/default/6d3dcb6/2147483647/resize/100x100/?url=https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg

Commands

Commands are used to transform your origin image. Each command takes a single argument, and performs a single manipulation such as resizing or cropping the origin image.

Commands can be combined to perform more complex manipulations. They are processed in the order they appear in the url.

Resize

This command will resize an image to the size specified in the image geometry.

The resize image geometry format is <width>x<height> which will resize an image while preserving its aspect ratio. Since the aspect ratio is preserved the resulting image may be smaller than requested.

If you need an exact size you can add the ! symbol to your request, such as 100x100!. This will not preserve aspect ratios and may cause your image to compress or stretch. Listing 1 shows how the image can be stretched, Listing 2 shows it without the !.

Listing 1 - /v4/.../resize/100x100!/?url=... results in a 100x100 image

Listing 2 - /v4/.../resize/100x100/?url=... results in a 80x100 image

Some geometry formats use symbols that need to be escaped so make sure to always escape command arguments.

An example would be resizing by percentage. We're can't have % in the url so it needs to be escaped. For example, in resize/15%25, the %25 is the url encoding for %.

Crop

This command will crop an image to the size, and at the location, specified in the image geometry.

The crop image geometry format is <width>x<height>+{x}+{y} which will crop an image to the size specified width and height offset by x and y.

The width plus x offset must be less than the width of the image.

The height plus y offset must be less than the height of the image.

The +{x}+{y} is optional, they will both default to 0.

Thumbnail

This command is the same as resize/<width>x<height>^/strip/true.

This command is deprecated and will be removed in a future release.

Legacy Thumbnail

This command is similar to thumbnail and resize but it will crop the image to the width and height from the center of the image.

This command is the equivalent to running gravity/center/resize/<width>x<height>^/crop/<width>x<height>+0+0.

Format

This command will convert the origin image into the format provided by format_ext.

The formats available for conversion are:

• webp
• png
• jpg
• gif

Quality

This command adjusts the amount of compression for JPG, PNG, and TIFF images. It's named quality because it can directly affect the quality of the resulting image.

It accepts a value between:

• 1 - lowest quality, highest compression
• 100 - highest quality, lowest compression

Rotate

This command will rotate an image.

This should be a value between 0 and 360. You can provide decimal places, like 25.75, but for web use cases I can't imagine anyone is going to notice.

The default rotation is clockwise. Use negative numbers to rotate counter-clockwise.

Sepia

Sharpen

Brightness

Grayscale

This command will set the image colorspace to grayscale when true.

Strip

This command will remove ICC, and Exif profiles.

Use this command to reduce the size of your images. This especially helps when generating thumbnail images as this profile data can become a large percent of the final image once it's been reduced to a thumbnail.

By default dims will strip metadata anyway so this call is a no-op.

However, there are use cases such as DAM solutions where you may not want to strip this data by default. In those cases disable DIMS_STRIP_METADATA globally and call this command when needed.

Invert

This command inverts the colors of an image.