Image transformations

Image Transformations can help you enhance images, optimize them, implement responsive images or art direction.

Original image

Sharpen -/sharp/15/

Enhance -/enhance/100/

In any of the listed cases, you will either go with modifying original images or making several versions of an original. All that can be done on-the-fly by including the respective URL directives in CDN URLs related to images in your Uploadcare project. For example,

For better understanding image transformations, learn how our CDN works.

We support many input image formats, while the processed outputs will always be set to one of these three: PNG, JPEG or WebP.

List of image transformations

Resize and Crop

Uploadcare Image Transformations allow you to adjust image size and crop options on the fly, adjust resizing behavior, and set a background fill color when cropping images.



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




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.


Change resize behavior


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.






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.



If given dimensions are greater than the ones of the original image, the image is rendered inside a color-filled box. The color of that box can be changed via the setfill operation.

Scale crop


When :type is not specified.

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:

Requested size.

Adjusted size.
No distortion.

Requested size.
No distortion.
  • :offsetsstring, format: M%,N%, where M and N are the optional offsets along one or both of the axes in percentages; other possible values include:
  • center, a keyword responsible for centering the crop focus.

Smart crop

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 the 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 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.

Set fill color


Sets the fill color used with crop, stretch or when converting an alpha channel enabled image to JPEG. The operation uses hexadecimal notation to define colors.





Optimizing images means making them load faster at a minimum visual quality loss. This mainly includes manipulating image format and quality. A right balance of those helps improving conversions and bounce rates; it positively affects your SEO ranking.



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. We do it if a client supports the image/webp MIME-type and you are running the default Uploadcare setup with our storage and the default CDN domain,

400x301 png 116Kb

400x301 jpeg 16Kb

400x301 webp 15Kb
Transparent, size is equal
to the opaque one.

Beside using -/format/auto/, there is another way to control which image format is delivered to a client. In HTML 5, you can force the browser to automatically choose a WebP image version over others. This is done by using <picture>. Simply, wrap your <img> element with <picture> and add <source> having its type set to type="image/webp". Compatible browsers will then automatically load the WebP image version; others will take either JPEG or PNG.

  <source srcset="//" type="image/webp"/>
  <img src="//"/>



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.

When your input and output are both JPEGs and no destructive operations are applied, your output image quality is limited to the initial input quality: when you upload a highly compressed image, you can use the normal setting or go even higher, but it will not affect neither your compression settings nor file size.

  • 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.

1x best 16Kb
Blurry on retina.

1.5x lighter 16Kb
Fits all screens.

2x lightest 16Kb
Perfect for retina.

1x smart 14Kb

Progressive JPEG


Returns a progressive image. In progressive images, data are compressed in multiple passes of progressively higher detail. This is ideal for large images that will be displayed while downloading over a slow connection allowing a reasonable preview after receiving only a portion of the data. The operation does not affect non-JPEG images; does not force image formats to JPEG.

Baseline loading.

Progressive loading.

GIF to Video

Uploadcare Image Transformations features GIF to Video conversion that provides better loading times thus reducing your bounce rate. The feature is available on paid plans only.

GIF to Video workflow is the same as with other image transformations. The only difference is the gif2video URL directive should be included after the / separator, not /-/.


gif2video converts GIF files to video on the fly. Video files are much smaller than GIFs, without any quality loss. Their delivery to end users is much faster. In case your source file is not an animated GIF or the conversion feature is disabled for your project, you’ll get an HTTP 400 error.

Please note, even though you don’t use /-/ after :uuid with the gif2video directive, the separator is used with specific operations designed for the GIF to Video workflow: format and quality. We use such approach for our parser to tell the format and quality operations related to GIF to Video from their general versions.

Set Output Video Format, format


Converts an animated GIF to one of the following formats:

  • mp4 — H.264 video format. The format is supported by all major browsers. When no format is specified, mp4 is used by default.
  • webm — WebM video format. Supported in Google Chrome, Firefox, and Opera.

When embedding videos, the best practice is to specify both formats and let clients choose a more suitable one,

<video width="384" height="216" autoplay loop muted webkit-playsinline playsinline>
  <source src="" type="video/webm"/>
  <source src="" type="video/mp4"/>

Original GIF: 6.5MB, MP4: 251KB, WebM: 202KB

Set Output Video Quality, quality


Sets both quality and compression ratio for the output video. There are five :value levels: from better compression to better quality:
lightest, lighter, normal, better, best.

When quality is not explicitly specified, normal is used by default.


Color adjustment


Uploadcare features a set of operations for adjusting color properties of an image.

The :value parameter controls the strength of any applied adjustment. Ranges of the :value parameter differ between operations. There also is a zero point for each operation — the value producing outputs equal to original images.

Operation:value rangeZero point
/brightness/from -100 to 1000
/exposure/from -500 to 5000
/gamma/from 0 to 1000100
/contrast/from -100 to 5000
/saturation/from -100 to 5000
/vibrance/from -100 to 5000
/warmth/from -100 to 1000

The first three operations: brightness, exposure, and gamma are very similar. Unlike exposure and gamma, brightness works in a straightforward manner: the :value gets added to each color channel; out-of-range values are cut. Thus, when increasing brightness, brighter image features can be lost. Same works for darker features on brightness decrease. Conversely, exposure and gamma compress color values distribution in either lighter or darker areas depending on the provided :value, thus preserving details.


Original image.



Original image.



Original image.


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. The operation produces more realistic results when applied to typical photos.


Original image.



Original image.



Original image.


Last but not least, the warmth operation adjusts color temperature in images.


Original image.


You can combine any adjustments to achieve the needed outputs. Piping the operations won't get you any performance or precision losses since all adjustments are applied in one pass.

Original image.

Old photo effect.

Fresh view.



Auto-enhances an image by performing the following operations: auto levels, auto contrast, and saturation sharpening. :strength values should be in the range from 0 to 100. The default value is 50.

Original image. 24Kb

/enhance/50/ 28Kb

/enhance/100/ 32Kb


Desaturates images. The operation has no additional parameters and simply produces a grayscale image output when applied.

Original image.



Inverts images rendering a 'negative' of the input.

Original image.




Applies one of predefined photo filters by its :name. The way your images look affects their engagement rates. You apply filters thus providing beautiful images consistent across content pieces you publish.

The :name should be 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.


Original image.



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 an image.

Here's how all of our filters look like:









































Color Profile Management

This section covers Image Transformations (or CDN API methods) that provide color profile management and configure Uploadcare’s CDN behavior depending on the size of ICC profiles embedded in images.

Color Models and ICC Profiles

Digital images can be stored in different color models depending on how we use them: whether it is displaying, printing, or something else. The most common model for images intended for viewing is RGB, while CMYK is widely used for printing.

While CMYK images are common, some browsers support them poorly. But more importantly, CMYK support is inconsistent across different browsers. This means that if you happen to serve CMYK images on your site, the colors will vary.

To eliminate the inconsistency, by default, we convert all CMYK images to sRGB. Another drawback of rendering CMYK images on a page is the large size of CMYK ICC profiles (those weight more than a regular 1920x1080 JPEG image). This negatively affects your page performance metrics such as First Meaningful Paint (FMP) and Time to Interactive (TTI).

/srgb/fast/, 33Kb
CMYK image converted to sRGB.

/srgb/icc/, 33Kb
CMYK image converted to sRGB using ICC profile.

/srgb/keep_profile/, 617Kb
CMYK image with the original ICC profile. Colors depend on a browser.

In turn, an ICC profile defines how we interpret colors for the given color model. ICC profiles are binary files, which can be either embedded in an image or distributed as is.

With RGB images, embedding a profile is optional. If there is no embed, sRGB is assumed as default color space. Since most of the images on the internet are in sRGB, they commonly don’t include any profile embeds. For CMYK images, an embedded ICC profile is mandatory, while still can be absent. In the last case, we assume that the image is in the “Web Coated (SWOP) v2” color space.

Conversion to sRGB


The operation sets how Uploadcare behaves depending on different color profiles of uploaded images. See the table below to learn more about the possible outcomes. We also provide an option to omit the conversion for the cases where you explicitly want CMYK outputs.

The operation defaults to the fast value. However, we plan to optimize our image processing infrastructure to make icc faster and make it default. Both operations ensure consistently displaying images across different browsers.

Depending on the input color model, the parameter you include in the operation, and threshold you set with max_icc_size, one of the four possible outcomes will occur: profile embedding, profile discarding, color conversion, and fast color conversion.

Input Imagefasticckeep_profile
RGB, small profileembeddingembeddingembedding
RGB, large profilediscardingconversionembedding
CMYK imagefast conversionconversionembedding*

“small profile” and “large profile” stand for profile sizes below and above the max_icc_size setting respectively.

Here is the definition for every possible outcome:

  • Profile embedding: no changes in image model or colors. ICC profile, if present in the source image, stays embedded.
  • Profile discarding: no changes in image model or colors. ICC profile, if present, gets stripped off an image.
  • Color conversion: an image will be converted to sRGB using a full-featured color management system.
  • Fast color conversion is performed using a simple formula which doesn’t consider any color profile and thus provides a result different from a color-managed version.

* While we try to preserve the color model and profile for CMYK images with the -/srgb/keep_profile/ setting, this is not always possible. Certain Image Transformations require RGB color model, and thus we automatically convert the subjected images to sRGB using the icc mode. The list of operations incompatible with CMYK includes: setfill, overlay, enhance, filter, and Color Adjustments.

ICC Profile Size Threshold


The operation defines which RGB color profile sizes will be considered “small” and “large” when using srgb in fast or icc modes. The :number stands for the ICC profile size in kilobytes.

The default value is 10 (10240 bytes). Most of the common RGB profile sizes (sRGB, Display P3, ProPhoto, Adobe RGB, Apple RGB) are below the threshold.

Image with the original
Display P3 color profile. 25Kb.

No ICC profile, small color shift. 24.5Kb.

Image modifications


Uploadcare Image Transformations allow rotating images manually and according to EXIF, flip and mirror images. Image Rotation follows the general image transformation workflow.

Automatic Rotation, EXIF-based


The default behavior goes with parsing EXIF tags of original images and rotating them according to the “Orientation” tag. This is what we call autorotation. -/autorotate/no/ allows turning off the default behavior.

Technically, the default behavior of auto is about always trying to deliver WebP images based on checking the Accept header. We do it if a client supports the image/webp MIME-type and you are running the default Uploadcare setup with our storage and the default CDN domain,



Manual Right-Angle Rotation


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

Original image.





Flips images.

Original image.



Mirrors images.

Original image.



The overlay operation allows to layer images one over another.


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 parameter URL directives should be preserved.

Specifying size and opacity, positioning is omitted.

Specifying size and position, opacity is omitted.

Adding multiple overlays with varied positions.

Blur & Sharpen



Blurs images by the :strength factor. The filtering mode is Gaussian Blur, where :strength parameter sets the blur radius — effect intensity. Technically, :strength controls the Gaussian Blur standard deviation multiplied by ten. The value of :strength might come up to 5000, while the default value is 10. Note, different :strength values do not affect the operation performance.

Original image. 17Kb

/blur/20/ 10Kb

/blur/100/ 6Kb

Blur Region

-/blur-region/:two_dimensions/:two_coords/ -/blur-region/:two_dimensions/:two_coords/:strength/

Blurs the specified region of the image by the :strength factor. The filtering mode is Gaussian Blur, where :strength parameter sets the blur radius — effect intensity. Technically, :strength controls the Gaussian Blur standard deviation multiplied by ten. The value of :strength might come up to 5000, while the default value is determined automatically based on the size of the region. Note, larger :strength values do not affect the operation performance.

Original image.



Blur Faces


When faces is specified the regions are selected automatically by utilizing face detection.

Original image.

default strength

stength 250

Unsharp Masking


There is no specific operation for unsharp masking. Instead, you can adjust the :amount of the blur applied. :amount can be set in the range from –200 to 100 and defaults to 100.

Where the :amount of:

  • 100 stands for the opaque blur image.
  • 0 stands for no changes in the image, the output is equal to the original.
  • Any negative number would mean subtracting the difference between the blurred and original images from the original. That is the unsharp masking behavior.

You can implement unsharp masking with a large blur :strength (100;300) and a small negative :amount (–50;–10) to increase local contrast. Fine-tuned local contrast gives a “pop” to an image and mimics the look created by camera lenses. Local contrast enhancements let you minimize the effects of haze, lens flare, and “dull look.”

When implemented with a small :strength, unsharp masking increases image sharpness. For instance, the /blur/10/-200/ transformation is the full equivalent of /sharp/20/ with the exception that sharp operates much faster.

You can combine unsharp masking with the sharp operation to increase both local contrast and sharpness.

Original image. 16Kb

/blur/100/-50/ 19Kb

/blur/100/-120/ 22Kb

/sharp/20/ 20Kb

/blur/10/-200/ 20Kb

/sharp/10/-/blur/90/-50/ 21Kb



Sharpens an image, might be especially useful with images that were subjected to downscaling. :strength can be in the range from 0 to 20 and defaults to the value of 5.

Downscaled image. 15Kb

/sharp/10/ 17Kb

/sharp/20/ 19Kb


This section describes the limits to consider when implementing Uploadcare Image Transformations.

Core Operations

When applying image transformations, add at least one of the following operations via their respective URL directives:

Output Image Dimensions

The dimensions you specify for the last operation should not exceed 3000x3000 pixels. You can increase that limit to 5000x5000 pixels by explicitly setting your image format to JPEG, /format/jpeg/.

File Size

We don’t provide on-the-fly image transformations for images greater than 75 Mpx in resolution: those can only be delivered via CDN as-is.

Simple Rotation

When the only image transformation you want is rotating, consider using the preview control without any arguments. When you use any of the transformations, we automatically rotate images according to their EXIF orientation.

Animated Images

Animated images are treated as static by the transformations engine, consider checking out our GIF to Video workflow optimized for animated images delivery.