Image Transformations With Adaptive Delivery

You can add additional Image Transformations within Adaptive Delivery to serve both optimized and enhanced images. There are two ways to add Image Transformations:

  • Inline a set of transformations in a single data-blink-ops attribute.
  • Add individual transformations via corresponding data attributes.

Here’s an example of using data-blink-ops with its syntax similar to inline CSS,

  data-blink-ops='filter: nerion; enhance: 15; mirror'

If you decide to go with individual data attributes, the above example can be rewritten in the following way,


Note, Adaptive Delivery JS SDK adds resize, format and quality automatically. We don’t recommend changing the behavior, since we calculate the transformation parameters based on the user context.

Image filtering

Automatic image enhancement

enhance: :strength

Provides automatic image enhancement by combining the following transformations: auto levels, auto contrast, and saturation sharpening. The :strength values should be set in the range from 0 to 100. The default value is 50.

Original image. 10.3Kb

enhance: 50 13.5Kb

enhance: 100 17Kb


sharp: :strength

Applies image sharpening, which is specifically useful for downscaled images. While Adaptive Delivery provides automatic image resizing, you can further tune your visuals with sharpening. :strength values can be in the range from 0 to 20; the default is 5.

Downscaled image. 16.1Kb

sharp: 10 21.4Kb

sharp: 20 25Kb


blur: :strength

Applies image blur guided by the :strength factor. Uploadcare implements Gaussian Blur with :strength acting as effect intensity in the range from 0 to 5000. The default value is 10. The transformation provides uniform performance in the full range of intensities.

Original image. 14Kb

blur: 10 7.6Kb

blur: 100 2.4Kb

Color adjustments

Adjust image color properties by controlling brightness, exposure, gamma, contrast, saturation, vibrance, and warmth.

brightness: :value
exposure: :value
gamma: :value
contrast: :value
saturation: :value
vibrance: :value
warmth: :value

The :value parameter controls the strength of any applied adjustment. Ranges of the :value parameter differ across image transformations. Setting the :value to “zero point” leaves images unchanged.

Operation:value rangeZero point
brightnessfrom -100 to 1000
exposurefrom -500 to 5000
gammafrom 0 to 1000100
contrastfrom -100 to 5000
saturationfrom -100 to 5000
vibrancefrom -100 to 5000
warmthfrom -100 to 1000

The first three adjustments: brightness, exposure, and gamma produce similar results with the following differences:

  • brightness adds :value to each color channel; out-of-range values are cut.
  • exposure and gamma compress color values distribution thus preserving the details.

brightness: -20

Original image.

brightness: 20

exposure: -100

Original image.

exposure: 80

gamma: 150

Original image.

gamma: 70

The next three operations adjust color diversity and dynamic range in images:

  • contrast affects both colors and dynamic range; on increase, images lose both bright and dark details.
  • saturation uniformly bumps up color intensity leaving the dynamic range unchanged.
  • vibrance cleverly increases the intensity of muted colors and leaves the well-saturated ones alone.

contrast: -25

Original image.

contrast: 25

saturation: -25

Original image.

saturation: 25

vibrance: -50

Original image.

vibrance: 50

In turn, warmth adjusts color temperature in images.

warmth: -50

Original image.

warmth: 50

You can combine any adjustments, and piping the operations won’t get you any performance or precision losses: all adjustments are applied in one pass.

Original image.

Old photo effect.
saturation: -80
contrast: 80
warmth: 50

Fresh view.
exposure: 50
saturation: 50
warmth: -30

Photo filters

You can apply photo filters to your images while keeping them optimized and respnsove with Adaptive Delivery.

filter: :name
filter-amount: :amount

The transformation applies one of predefined photo filters by its :name. Photo filters help streamline your content production through serving consistent visuals across your site pages or content pieces.

:name should be set to one of the following: adaris, briaril, calarel, carris, cynarel, cyren, elmet, elonni, enzana, erydark, fenralan, ferand, galen, gavin, gethriel, iorill, iothari, iselva, jadis, lavra, misiara, namala, nerion, nethari, pamaya, sarnar, sedis, sewen, sorahel, sorlen, tarian, thellassan, varriel, varven, vevera, virkas, yedis, yllara, zatvel, zevcen.

:amount can be set in the range from -100 to 200 and defaults to 100.

The :amount of:

  • 0 stands for no changes in the image, the output is equal to the original.
  • Values in the range from 0 to 100 gradually increase filter strength; 100 makes filters work as designed.
  • Values over 100 emphasizes filter effect: the strength of applied changes.
  • Any negative number would mean subtracting the difference between the filtered and original images from the original. That will produce a “negative filter” effect.

filter: vevera;
filter-amount: -100

Original image.

filter: vevera;
filter-amount: 100

filter: vevera;
filter-amount: 200

All filters provide predictable outputs with the :value ranging from 0 to 100. For some filter presets, setting the :amount value outside those bounds may produce weird results. For example, all filters producing grayscale outputs will result in a negative image when set to the :amount greater than 100. Set to negative values, those will saturate images.

Here’s how all of our filters look like:

filter: adaris

filter: briaril

filter: calarel

filter: carris

filter: cynarel

filter: cyren

filter: elmet

filter: elonni

filter: enzana

filter: erydark

filter: fenralan

filter: ferand

filter: galen

filter: gavin

filter: gethriel

filter: iorill

filter: iothari

filter: iselva

filter: jadis

filter: lavra

filter: misiara

filter: namala

filter: nerion

filter: nethari

filter: pamaya

filter: sarnar

filter: sedis

filter: sewen

filter: sorahel

filter: sorlen

filter: tarian

filter: thellassan

filter: varriel

filter: varven

filter: vevera

filter: virkas

filter: yedis

filter: yllara

filter: zatvel

filter: zevcen


You can desaturates images with the grayscale transformation. It has no additional parameters and simply produces a grayscale image output when applied.


Here’s an example,

Original image.



Invert images rendering a “negative” of your input,


An example of inverting an image follows,

Original image.


Image rotation


rotate: :angle

Right-angle image rotation, counterclockwise. The value of :angle must be a multiple of 90.

Original image.

rotate: 90

rotate: 180

rotate: 270



The transformation provides image flipping.

Original image.




The transformation allows mirroring images.

Original image.



The overlay transformation allows to layer images one over another.

overlay-uuid: :uuid
overlay-dimensions: :relative_dimensions
overlay-coordinates: :relative_coordinates
overlay-opacity: :opacity

One of the most common use cases here are watermarks: semi-transparent images layered over opaque ones to complicate their unauthorized usage, etc.

  • :uuid — UUID of an image to be layered over input. To be recognized by :uuid, that image should be related to any project of your account.
  • :relative_dimensions — linear dimensions of the overlay image. The aspect ratio of an overlay is preserved. What you set is a maximum linear size along one of the axes: -/overlay/:uuid/50%x50%/ means any linear dimension of the overlay can not exceed 50% in size. Default size setting is 100%.
  • :relative_coordinates — position of the overlay over your input. By default, an overlay is positioned in the top-left corner of an input. Coordinates represent an offset along each of the axes in either pixel or percent format. In general, the coordinate system is similar to the CSS background-position.
  • :opacity — controls the opacity of the overlay in percent format. Your overlay may either be initially semi-transparent or made to be so by tuning :opacity.

Since % is an escape char in URLs, it can’t be used as-is and should be replaced with either %25 escape sequence or the p char, which is a more readable and concise option.

Every overlay parameter is optional and can be omitted. However, the order of the parameters should be preserved.

overlay-uuid: b18b5179-b9f6-4fdc-9920-5539f938fc44;
overlay-dimensions: 50%25x50%25;
overlay-opacity: 20%25

Specifying size and opacity, positioning is omitted.

overlay-uuid: b18b5179-b9f6-4fdc-9920-5539f938fc44;
overlay-dimensions: 50%25x50%25;
overlay-coordinates: center

Specifying size and position, opacity is omitted.

Resizing and cropping


preview: :two_dimensions

Reduces an image proportionally for it to fit into the given dimensions in pixels. If dimensions are not specified, we use the default value of 2048x2048 pixels.


resize: :one_or_two_dimensions

Resizes an image to fit into the specified dimensions. With just a single linear dimension specified, preserves your original aspect ratio and resizes an image along one of its axes.


crop: :two_dimensions
crop-position: :two_coords

Crops an image using specified dimensions and offsets. If no offset values are passed into the operation, the top-left image corner is used by default.

Original image.

crop: 200x130; crop-position: center

crop: 200x130; crop-position: 200,70

Scale Crop

scale-crop: :two_dimensions
scale-crop-position: :type

When :type is not specified.

The transformation scales down an image until one of its dimensions gets equal to some of the specified ones; the rest is cropped. This proves useful when your want to fit as much of your image as possible into a box. Let us compare the two resizing methods:

resize: 1024x1024
Requested size.

preview: 1024x1024
Adjusted size.
No distortion.

scale-crop: 1024x1024
Requested size.
No distortion.

When smart :type is specified.

Switching the crop type to one of the smart modes enables the content-aware mechanic. Uploadcare applies AI-based algorithms to detect faces and other visually important objects or regions in images and crops the rest.


Smart cropping.

Content-aware mechanics of Smart Crop are based on the following methods of image analysis:

  • Face Detection, :type is set to smart_faces. Face detection identifies and locates human faces in digital images.
  • Object Detection, :type is set to smart_object. Object detection identifies and locates the most visually important regions in the image.
  • Corner Points Detection, :type is set to smart_points. This method analyses image pixels to find the high contrast corners in the image, useful for abstract, landscape, and art images. The corner points have much less semantic information than other methods and designed to be used as a fallback.

The methods you include separating by underscore are applied sequentially. The algorithm switches to the next method only if no regions were found by the previous one. For example smart_faces_objects_points applies face detection initially as the first step. Only when no faces are found on an image, the object detection will be used. Finally, when no objects are found, the corner points will be detected.

If specified methods were unable to find regions or points of interest, the :offset setting will be used to crop an image. When no :offsets are specified, images get center-cropped.

Centering on faces or objects
when no faces found.

Centering on objects or faces
when no objects found.

Centering on corner points.

Possible :type values:

smart (alias for smart_faces_objects_points), smart_faces_objects, smart_faces_points, smart_objects_faces_points, smart_objects_faces, smart_objects_points, smart_points, smart_objects, smart_faces.


stretch: :mode

Sets the resize behavior when a source image is smaller than the resulting dimensions. The following modes can apply:

  • on — stretches an image up, the default option.
  • off — forbids stretching an image along any dimension that exceeds image size along any of its axes.
  • fill — does not stretch an image, the color-filled frame is rendered around instead, the default fill color is used.

preview: 160x160
resize: 220x

preview: 160x160
stretch: off
resize: 220x

preview: 160x160
stretch: fill
resize: 220xsetfill: 8d8578

Compression and Performance


format: :format

Converts an image to one of the following formats:

  • jpeg — JPEG is a lossy image format (good compression, good for photos). JPEG doesn’t support an alpha channel, hence you can use the setfill operation that sets a background color. All browsers support JPEG.
  • png — PNG is a lossless format (good compression only for graphics) with alpha channel support. Supported by all browsers.
  • webp — WebP is a modern image format that supports alpha channel and lossy compression. The format is good for all kinds of images but supported by a limited number of browsers.
  • auto — the image format used for content delivery is set according to the presence of an alpha channel in your input and capabilities of a client.

Technically, the default behavior of auto is about always trying to deliver WebP images based on checking the Accept header.

png 135Kb

jpeg 8.8Kb

webp 11.5Kb
Transparent, size is equal
to the opaque one.


quality: :value

Sets the level of image quality that affects file sizes and hence loading speeds and volumes of generated traffic. quality works with JPEG and WebP images.

The following options can apply:

  • normal — the default setting, suits most cases.
  • better — can be used to render relatively small and detailed previews. ≈125% file size compared to normal.
  • best — useful for hi-res images, when you want to get perfect quality without paying much attention to file sizes. ≈170% file size.
  • lighter — useful when applied to relatively large images to save traffic without significant losses in quality. ≈80% file size.
  • lightest — useful for retina resolutions, when you don’t have to worry about the quality of each pixel. ≈50% file size.
  • smart — automatically adjusts image compression and format settings to preserve visual quality while minimizing the file size. The mode is content-aware. Image formats will not be adjusted if you define format explicitly.

best 32Kb

lighter 18.6Kb

lightest 12.3Kb

smart 13.8Kb, WebP

Progressive JPEG

progressive: yes
progressive: no

Returns a progressive image. The operation does not affect non-JPEG images, and won’t force the output image format to JPEG.