Image transformation reference
The table below lists all transformation parameters currently supported by Cloudinary. For each parameter you can see the short name that you can use for manually building transformation URLs and the longer name that is accepted by the relevant methods of all our client libraries.
The following image showcases a complex example of image transformations that includes resizing, cropping, multiple image overlays, dynamic text overlay, image rotation and moregreece_landscape
Ruby:
cl_image_tag("yellow_tulip.jpg", :transformation=>[ {:width=>220, :height=>140, :crop=>"fill"}, {:overlay=>"brown_sheep", :width=>220, :height=>140, :x=>220, :crop=>"fill"}, {:overlay=>"horses", :width=>220, :height=>140, :y=>140, :x=>-110, :crop=>"fill"}, {:overlay=>"white_chicken", :width=>220, :height=>140, :y=>70, :x=>110, :crop=>"fill"}, {:overlay=>"butterfly.png", :height=>200, :x=>-10, :angle=>10}, {:width=>400, :height=>260, :radius=>20, :crop=>"crop"}, {:overlay=>"text:Parisienne_35_bold:Memories%20from%20our%20trip", :color=>"#990C47", :y=>155}, {:effect=>"shadow"} ])
PHP:
cl_image_tag("yellow_tulip.jpg", array("transformation"=>array( array("width"=>220, "height"=>140, "crop"=>"fill"), array("overlay"=>"brown_sheep", "width"=>220, "height"=>140, "x"=>220, "crop"=>"fill"), array("overlay"=>"horses", "width"=>220, "height"=>140, "y"=>140, "x"=>-110, "crop"=>"fill"), array("overlay"=>"white_chicken", "width"=>220, "height"=>140, "y"=>70, "x"=>110, "crop"=>"fill"), array("overlay"=>"butterfly.png", "height"=>200, "x"=>-10, "angle"=>10), array("width"=>400, "height"=>260, "radius"=>20, "crop"=>"crop"), array("overlay"=>"text:Parisienne_35_bold:Memories%20from%20our%20trip", "color"=>"#990C47", "y"=>155), array("effect"=>"shadow") )))
Python:
CloudinaryImage("yellow_tulip.jpg").image(transformation=[ {"width": 220, "height": 140, "crop": "fill"}, {"overlay": "brown_sheep", "width": 220, "height": 140, "x": 220, "crop": "fill"}, {"overlay": "horses", "width": 220, "height": 140, "y": 140, "x": -110, "crop": "fill"}, {"overlay": "white_chicken", "width": 220, "height": 140, "y": 70, "x": 110, "crop": "fill"}, {"overlay": "butterfly.png", "height": 200, "x": -10, "angle": 10}, {"width": 400, "height": 260, "radius": 20, "crop": "crop"}, {"overlay": "text:Parisienne_35_bold:Memories%20from%20our%20trip", "color": "#990C47", "y": 155}, {"effect": "shadow"} ])
Node.js:
cloudinary.image("yellow_tulip.jpg", {transformation: [ {width: 220, height: 140, crop: "fill"}, {overlay: "brown_sheep", width: 220, height: 140, x: 220, crop: "fill"}, {overlay: "horses", width: 220, height: 140, y: 140, x: -110, crop: "fill"}, {overlay: "white_chicken", width: 220, height: 140, y: 70, x: 110, crop: "fill"}, {overlay: "butterfly.png", height: 200, x: -10, angle: 10}, {width: 400, height: 260, radius: 20, crop: "crop"}, {overlay: "text:Parisienne_35_bold:Memories%20from%20our%20trip", color: "#990C47", y: 155}, {effect: "shadow"} ]})
Java:
cloudinary.url().transformation(new Transformation() .width(220).height(140).crop("fill").chain() .overlay("brown_sheep").width(220).height(140).x(220).crop("fill").chain() .overlay("horses").width(220).height(140).y(140).x(-110).crop("fill").chain() .overlay("white_chicken").width(220).height(140).y(70).x(110).crop("fill").chain() .overlay("butterfly.png").height(200).x(-10).angle(10).chain() .width(400).height(260).radius(20).crop("crop").chain() .overlay("text:Parisienne_35_bold:Memories%20from%20our%20trip").color("#990C47").y(155).chain() .effect("shadow")).imageTag("yellow_tulip.jpg")
jQuery:
$.cloudinary.image("yellow_tulip.jpg", {transformation: [ {width: 220, height: 140, crop: "fill"}, {overlay: "brown_sheep", width: 220, height: 140, x: 220, crop: "fill"}, {overlay: "horses", width: 220, height: 140, y: 140, x: -110, crop: "fill"}, {overlay: "white_chicken", width: 220, height: 140, y: 70, x: 110, crop: "fill"}, {overlay: "butterfly.png", height: 200, x: -10, angle: 10}, {width: 400, height: 260, radius: 20, crop: "crop"}, {overlay: "text:Parisienne_35_bold:Memories%20from%20our%20trip", color: "#990C47", y: 155}, {effect: "shadow"} ]})
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
.Width(220).Height(140).Crop("fill").Chain()
.Overlay("brown_sheep").Width(220).Height(140).X(220).Crop("fill").Chain()
.Overlay("horses").Width(220).Height(140).Y(140).X(-110).Crop("fill").Chain()
.Overlay("white_chicken").Width(220).Height(140).Y(70).X(110).Crop("fill").Chain()
.Overlay("butterfly.png").Height(200).X(-10).Angle(10).Chain()
.Width(400).Height(260).Radius(20).Crop("crop").Chain()
.Overlay("text:Parisienne_35_bold:Memories%20from%20our%20trip").Color("#990C47").Y(155).Chain()
.Effect("shadow")).BuildImageTag("yellow_tulip.jpg")
The reference table below lists the transformation parameters that are the building blocks for creating a multitude of manipulated images. You can see the possible values for each parameter and a usage example with a sample image for illustration. You can create a wide range of effects and transformations by chaining together any combination of the parameters listed below.
See also:
- For more in-depth information on transforming images see the image transformations documentation.
- For more inspiration on using the various transformations, see the Cloudinary Cookbook which is a collection of examples showing how to do complex transformations with images, by combining different image manipulations, or tweaking a specific manipulation to achieve a certain result. The cookbook is made from recipes that include sample images, code in all development frameworks, tips and guidelines and links to additional resources.
| Library Parameter | URL Param | Value | Example | Description | ||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| width | w | pixels or percents | The required width of a transformed image or an overlay. Can be specified separately or together with the height value. | |||||||||||||||||||||||||||||||||||||||
| 80 |  | Resize width to 80 pixels while maintaining aspect ratio. | ||||||||||||||||||||||||||||||||||||||||
| 0.2 |  | Resize image to 20% of its original size. | ||||||||||||||||||||||||||||||||||||||||
| auto[:rounding step] | (Note: For customers with a custom domain name: Contact us to setup this feature).
Automatically resize the image to match the width available for the image in the responsive layout. The width is also rounded up to the nearest rounding step which is set by the optional parameter, or in steps of 100 pixels by default. Only works for certain browsers and when Client-Hints are enabled (see the Automatic image width documentation). | |||||||||||||||||||||||||||||||||||||||||
| auto | Resizes the image to the nearest rounding step of 100 pixels (by default), e.g., 345 is rounded up to 400. | |||||||||||||||||||||||||||||||||||||||||
| auto:50 | Resizes the image to the nearest rounding step of 50 pixels (as specified by the additional value), e.g., 345 is rounded up to 350. | |||||||||||||||||||||||||||||||||||||||||
| auto[:rounding step][:width] | The same as w_auto[:rounding step], with the additional option of specifying the image width instead of having the value retrieved from the client header. | |||||||||||||||||||||||||||||||||||||||||
| auto:50:87 | Resizes the image to the nearest rounding step of 50 pixels (as specified by the additional value), and specifies a width of 87 pixels for the image. Therefore, in this example, an image with a width of 100 pixels would be delivered. | |||||||||||||||||||||||||||||||||||||||||
| auto:breakpoints[_settings] | (Note: This feature is not enabled by default: Contact us to set it up).
Automatically resize the image to match the width available for the image in the responsive layout. The width is rounded up to the nearest breakpoint, where the optimal breakpoints are calculated using either the default breakpoint request settings or using the given settings (see the Automatic image width using optimal responsive breakpoints documentation). | |||||||||||||||||||||||||||||||||||||||||
| auto:breakpoints | Resizes the image to nearest breakpoint (rounded up). The breakpoints are calculated using the default breakpoint request settings. | |||||||||||||||||||||||||||||||||||||||||
| auto:breakpoints_200_1920_30_15 | Resizes the image to nearest breakpoint (rounded up). The breakpoints are calculated using the following breakpoint request settings - `min_width=200`, `max_width=1920`, `bytes_step=30`, `max_images=15`. | |||||||||||||||||||||||||||||||||||||||||
| auto:breakpoints[_settings][:width] | The same as w_auto:breakpoints[_settings], with the additional option of specifying the image width instead of having the value retrieved from the client header. | |||||||||||||||||||||||||||||||||||||||||
| auto:breakpoints[_settings]:json | Allows client-side applications to access the calculated breakpoints as a JSON response. | |||||||||||||||||||||||||||||||||||||||||
| auto:breakpoints_20_190_10_15:json | Returns a JSON responce with the calculated breakpoints for the following breakpoint request settings - `min_width=20`, `max_width=190`, `bytes_step=10`, `max_images=15`. | |||||||||||||||||||||||||||||||||||||||||
| height | h | pixels or percents | The required height of a transformed image or an overlay. Can be specified separately or together with the width value. | |||||||||||||||||||||||||||||||||||||||
| 40 |  | Resize height to 40 pixels while maintaining aspect ratio. | ||||||||||||||||||||||||||||||||||||||||
| 0.3 |  | Resize image to 30% of its original size. | ||||||||||||||||||||||||||||||||||||||||
| crop | c | mode | A crop mode that determines how to transform the image for fitting into the desired width & height dimensions. Defaults to the 'scale' mode for dynamic URLs only - there is no default value when using the Cloudinary SDKs, and a cropping mode must be explicitly selected. | |||||||||||||||||||||||||||||||||||||||
| scale(default) |  | Change the size of the image exactly to the given width and height without necessarily retaining the original aspect ratio: all original image parts are visible but might be stretched or shrunk. | ||||||||||||||||||||||||||||||||||||||||
| fit |  | The image is resized so that it takes up as much space as possible within a bounding box defined by the given width and height parameters. The original aspect ratio is retained and all of the original image is visible. | ||||||||||||||||||||||||||||||||||||||||
| limit |  | Same as the 'fit' mode but only if the original image is larger than the given limit (width and height), in which case the image is scaled down so that it takes up as much space as possible within a bounding box defined by the given width and height parameters. The original aspect ratio is retained and all of the original image is visible. | ||||||||||||||||||||||||||||||||||||||||
| mfit |  | Same as the 'fit' mode but only if the original image is smaller than the given minimum (width and height), in which case the image is scaled up so that it takes up as much space as possible within a bounding box defined by the given width and height parameters. The original aspect ratio is retained and all of the original image is visible. | ||||||||||||||||||||||||||||||||||||||||
| fill |  | Create an image with the exact given width and height while retaining the original aspect ratio, using only part of the image that fills the given dimensions if necessary (only part of the original image might be visible if the requested aspect ratio is different from the original aspect ratio). | ||||||||||||||||||||||||||||||||||||||||
| lfill |  | Same as the 'fill' mode but only if the original image is larger than the given limit (width and height), in which case the image is scaled down to fill the given width and height while retaining the original aspect ratio, using only part of the image that fills the given dimensions if necessary (only part of the original image might be visible if the requested aspect ratio is different from the original aspect ratio). | ||||||||||||||||||||||||||||||||||||||||
| pad |  | Resize the image to fill the given width and height while retaining the original aspect ratio. If the proportions of the original image do not match the given width and height, padding is added to the image to reach the required size. | ||||||||||||||||||||||||||||||||||||||||
| lpad |  | Same as the 'pad' mode but only if the original image is larger than the given limit (width and height), in which case the image is scaled down to fill the given width and height while retaining the original aspect ratio. If the proportions of the original image do not match the given width and height, padding is added to the image to reach the required size. | ||||||||||||||||||||||||||||||||||||||||
| mpad |  | Same as the 'pad' mode but only if the original image is smaller than the given minimum (width and height), in which case the image is scaled up to fill the given width and height while retaining the original aspect ratio. If the proportions of the original image do not match the given width and height, padding is added to the image to reach the required size. | ||||||||||||||||||||||||||||||||||||||||
| crop |  | Used to extract a given width & height out of the original image. The original proportions are retained and so is the size of the graphics. | ||||||||||||||||||||||||||||||||||||||||
| thumb |  | Generate a thumbnail using face detection in combination with the 'face' or 'faces' gravity. | ||||||||||||||||||||||||||||||||||||||||
| imagga_crop |  | Crop your image based on automatically calculated areas of interest within each specific photo. See the Imagga Crop and Scale add-on documentation for more information. | ||||||||||||||||||||||||||||||||||||||||
| imagga_scale |  | Scale your image based on automatically calculated areas of interest within each specific photo. See the Imagga Crop and Scale add-on documentation for more information. | ||||||||||||||||||||||||||||||||||||||||
| aspect_ratio | ar | ratio or percent | Resize or crop the image to a new aspect ratio. This parameter is used together with a specified crop mode that determines how the image is adjusted to the new dimensions. | |||||||||||||||||||||||||||||||||||||||
| 1.5 |  | Crop the image to an aspect ratio of 1.5 | ||||||||||||||||||||||||||||||||||||||||
| 16:9 |  | Crop the image to an aspect ratio of 16:9 | ||||||||||||||||||||||||||||||||||||||||
| gravity | g | direction | Decides which part of the image to keep while the 'crop', 'pad', 'thumb' and 'fill' crop modes are used. For overlays, this decides where to place the overlay. | |||||||||||||||||||||||||||||||||||||||
| north_west |  | North west corner (top left). | ||||||||||||||||||||||||||||||||||||||||
| north |  | North center part (top center). | ||||||||||||||||||||||||||||||||||||||||
| north_east |  | North east corner (top right). | ||||||||||||||||||||||||||||||||||||||||
| west |  | Middle west part (left). | ||||||||||||||||||||||||||||||||||||||||
| center(default) |  | The center of the image. | ||||||||||||||||||||||||||||||||||||||||
| east |  | Middle east part (right). | ||||||||||||||||||||||||||||||||||||||||
| south_west |  | South west corner (bottom left). | ||||||||||||||||||||||||||||||||||||||||
| south |  | South center part (bottom center). | ||||||||||||||||||||||||||||||||||||||||
| south_east |  | South east corner (bottom right). | ||||||||||||||||||||||||||||||||||||||||
| xy_center |  | Set the crop's center of gravity to the given x & y coordinates" | ||||||||||||||||||||||||||||||||||||||||
| face |  | Automatically detect the largest face in an image and aim to make it the center of the cropped image. Alternatively, use face coordinates specified by API if available. Defaults to the 'north' gravity if no face was detected. | ||||||||||||||||||||||||||||||||||||||||
| face:center | Same as the 'face' gravity, but defaults to 'center' gravity instead of 'north' if no face is detected. | |||||||||||||||||||||||||||||||||||||||||
| faces |  | Automatically detect multiple faces in an image and aim to make them the center of the cropped image. | ||||||||||||||||||||||||||||||||||||||||
| faces:center | Same as the 'faces' gravity, but defaults to 'center' gravity instead of 'north' if no faces are detected. | |||||||||||||||||||||||||||||||||||||||||
| body |  | Automatically detect the largest body in an image and aim to make it the center of the cropped image. Defaults to the 'north' gravity if no body was detected. | ||||||||||||||||||||||||||||||||||||||||
| adv_face |  | Automatically detect the largest face in an image with the Advanced Facial Attribute Detection add-on and make it the focus of the transformation. | ||||||||||||||||||||||||||||||||||||||||
| adv_faces |  | Automatically detect all the faces in an image with the Advanced Facial Attribute Detection add-on and make them the focus of the transformation. | ||||||||||||||||||||||||||||||||||||||||
| adv_eyes |  | Automatically detect the largest pair of eyes in an image with the Advanced Facial Attribute Detection add-on and make them the focus of the transformation. | ||||||||||||||||||||||||||||||||||||||||
| custom |  | Use custom coordinates that were specified by the upload or admin API and aim to make it the center of the cropped image. Defaults to 'center' gravity if no custom coordinates are available. | ||||||||||||||||||||||||||||||||||||||||
| custom:face | Same as the 'custom' gravity, but defaults to 'face' gravity if no custom coordinates are available. | |||||||||||||||||||||||||||||||||||||||||
| custom:faces | Same as the 'custom' gravity, but defaults to 'faces' gravity if no custom coordinates are available. | |||||||||||||||||||||||||||||||||||||||||
| custom:adv_face | Same as the 'custom' gravity, but defaults to 'adv_face' gravity if no custom coordinates are available. | |||||||||||||||||||||||||||||||||||||||||
| custom:adv_faces | Same as the 'custom' gravity, but defaults to 'adv_faces' gravity if no custom coordinates are available. | |||||||||||||||||||||||||||||||||||||||||
| auto[:focal_gravity] | Automatically crop the image to include the most interesting regions. The parameter value accepts an optional `focal_gravity` value to change which elements (faces by default) are given higher priority for inclusion by the cropping algorithm (see the Automatic cropping documentation). Note that any custom coordinates defined will override the automatic cropping and use the custom coordinates as is (except for `custom_no_override` and `none`). | |||||||||||||||||||||||||||||||||||||||||
| auto |  | Automatically crop the image while giving higher priority to detected faces (same as `auto:faces`). | ||||||||||||||||||||||||||||||||||||||||
| auto:adv_face |  | Automatically crop the image while giving higher priority to the largest face detected by the Advanced Facial Attribute Detection add-on. | ||||||||||||||||||||||||||||||||||||||||
| auto:adv_faces |  | Automatically crop the image while giving higher priority to faces detected by the Advanced Facial Attribute Detection add-on. | ||||||||||||||||||||||||||||||||||||||||
| auto:adv_eyes |  | Automatically crop the image while giving higher priority to eyes detected by the Advanced Facial Attribute Detection add-on. | ||||||||||||||||||||||||||||||||||||||||
| auto:body |  | Automatically crop the image while giving higher priority to detected bodies. | ||||||||||||||||||||||||||||||||||||||||
| auto:face |  | Automatically crop the image while giving higher priority to the largest detected face. | ||||||||||||||||||||||||||||||||||||||||
| auto:faces |  | Automatically crop the image while giving higher priority to detected faces (default value if no `focal_gravity` is specified). | ||||||||||||||||||||||||||||||||||||||||
| auto:no_faces |  | Automatically crop the image without giving higher priority to any detected element. | ||||||||||||||||||||||||||||||||||||||||
| auto:custom_no_override |  | Automatically crop the image while giving higher priority to custom coordinates (custom coordinates don't override the automatic cropping). | ||||||||||||||||||||||||||||||||||||||||
| auto:none |  | Automatically crop the image without giving higher priority to any detected element (custom coordinates don't override the automatic cropping). | ||||||||||||||||||||||||||||||||||||||||
| auto:50 |  | (Only relevant when used with the 'thumb' crop mode). Automatically crop the image to include the most interesting regions while setting the level of aggressiveness of the cropping algorithm between 0 and 100 (set to 50 in this example), where 100 tries to keep more of the original image, and 0 crops more aggressively and then zooms in. | ||||||||||||||||||||||||||||||||||||||||
| zoom | z | percent | Control how much of the original image surrounding the face to keep when using either the 'crop' or 'thumb' cropping modes with face detection (Default: 1.0). | |||||||||||||||||||||||||||||||||||||||
| 1.2 |  | Cropped with face detection and zoom set to 120%. | ||||||||||||||||||||||||||||||||||||||||
| 0.75 |  | Thumbnail with face detection and zoom set to 75% | ||||||||||||||||||||||||||||||||||||||||
| x | x | pixels or percent | Horizontal position for custom-coordinates based cropping, overlay placement and certain region related effects. | |||||||||||||||||||||||||||||||||||||||
| 130 |  | Crop image to an 80x80 square starting 130 pixels from the left. | ||||||||||||||||||||||||||||||||||||||||
| 0.1 |  | Place an overlay that is horizontally offset from the south_west corner by 10% | ||||||||||||||||||||||||||||||||||||||||
| y | y | pixels or percent | Vertical position for custom-coordinates based cropping and overlay placement. | |||||||||||||||||||||||||||||||||||||||
| 340 |  | Crop image to an 80x80 square starting 340 pixels from the top. | ||||||||||||||||||||||||||||||||||||||||
| 0.2 |  | Place an overlay that is vertically offset from the south_west corner by 10% | ||||||||||||||||||||||||||||||||||||||||
| format | (file extension) | format | Deliver the file in the requested format by adding the required format as the file extension. The 'format' parameter itself is optional for use with Cloudinary's SDKs. Supported formats: jpg, jpe, jpeg, jpc, jp2, j2k, wdp, jxr, hdp, png, gif, webp, bmp, tif, tiff, ico, pdf, ps, ept, eps, eps3, psd, svg, ai, djvu, flif | |||||||||||||||||||||||||||||||||||||||
| jpg |  | Deliver the 'sample' image in jpg format. | ||||||||||||||||||||||||||||||||||||||||
| fetch_format | f | format | Force format conversion to the given image format for remote 'fetch' URLs and auto uploaded images that already have a different format as part of their URLs. | |||||||||||||||||||||||||||||||||||||||
| auto |  | Automatically convert delivered images to WebP and JPEG-XR on supported browsers to save bandwidth and optimize delivery time (see the Automatic format selection documentation). | ||||||||||||||||||||||||||||||||||||||||
| png |  | Convert a remote JPG image to the PNG format. | ||||||||||||||||||||||||||||||||||||||||
| quality | q | percent | Control the JPEG, WebP, GIF, JPEG XR and JPEG 2000 compression quality. 1 is the lowest quality and 100 is the highest. Reducing the quality is a tradeoff between visual quality and file size. | |||||||||||||||||||||||||||||||||||||||
| 100 |  | Generate a thumbnail using highest image quality (9.15KB) | ||||||||||||||||||||||||||||||||||||||||
| 20 |  | Generate a thumbnail using a low 20% quality (1.48KB) | ||||||||||||||||||||||||||||||||||||||||
| percent[:chroma_subsampling] | Add an optional parameter to control chroma subsampling. A value of 420 forces subsampling and a value of 444 prevents subsampling (see the Toggling chroma subsampling documentation). | |||||||||||||||||||||||||||||||||||||||||
| 60:420 | | Generate a thumbnail using a 60% quality while forcing chroma subsampling (1.2KB). | ||||||||||||||||||||||||||||||||||||||||
| auto[:quality_level] | (Note: For customers with a custom domain name: Contact us to setup this feature).
Automatically calculate the optimal quality for images: the smallest file size without affecting their perceptual quality. The parameter value accepts an optional `quality_level` value to select the level of quality (`good` by default) for the quality algorithm (see the Automatic quality documentation). | |||||||||||||||||||||||||||||||||||||||||
| auto |  | Automatically calculate the optimal quality an image: the smallest file size without affecting its perceptual quality (1.9KB). Same as `auto:good`. | ||||||||||||||||||||||||||||||||||||||||
| auto:best |  | Automatically calculate the optimal quality for images using a less aggressive algorithm (2.2KB). | ||||||||||||||||||||||||||||||||||||||||
| auto:good |  | Automatically calculate the optimal quality for an image: the smallest file size without affecting its perceptual quality (1.9KB). | ||||||||||||||||||||||||||||||||||||||||
| auto:eco |  | Automatically calculate the optimal quality for images using a more aggressive algorithm (1.7KB). | ||||||||||||||||||||||||||||||||||||||||
| auto:low |  | Automatically calculate the optimal quality for images using the most aggressive algorithm (1.5KB). | ||||||||||||||||||||||||||||||||||||||||
| jpegmini |  | Use the JPEGmini Image Optimization add-on to automatically calculate the optimal compression for JPEG images without affecting their perceptual quality. | ||||||||||||||||||||||||||||||||||||||||
| radius | r | pixels or max | Round the corners of an image or make it completely circular or oval (ellipse). | |||||||||||||||||||||||||||||||||||||||
| 20 |  | Generate a small image with rounded corners of 20 pixels radius. | ||||||||||||||||||||||||||||||||||||||||
| max |  | Generate an image with a circular crop using the 'max' radius value. | ||||||||||||||||||||||||||||||||||||||||
| angle | a | degrees or mode | Rotate or flip an image by the given degrees or automatically according to its orientation or available meta-data. Multiple modes can be applied by concatenating their names with a dot. | |||||||||||||||||||||||||||||||||||||||
| 90 |  | Rotate image by 90 degrees clockwise. | ||||||||||||||||||||||||||||||||||||||||
| 10 |  | Rotate image by 10 degrees clockwise. | ||||||||||||||||||||||||||||||||||||||||
| -20 |  | Rotate image by 20 degrees counterclockwise. | ||||||||||||||||||||||||||||||||||||||||
| auto_right |  | Rotate image 90 degrees clockwise only if the requested aspect ratio does not match the image's aspect ratio. | ||||||||||||||||||||||||||||||||||||||||
| auto_left |  | Rotate image 90 degrees counterclockwise only if the requested aspect ratio does not match the image's aspect ratio. | ||||||||||||||||||||||||||||||||||||||||
| ignore |  | By default, the image is automatically rotated according to the EXIF data stored by the camera when the image was taken. Set the angle to 'ignore' if you do not want the image to be automatically rotated. | ||||||||||||||||||||||||||||||||||||||||
| vflip |  | Vertical mirror flip of the image. | ||||||||||||||||||||||||||||||||||||||||
| hflip |  | Horizontal mirror flip of the image. | ||||||||||||||||||||||||||||||||||||||||
| effect | e | name and value | Apply a filter or an effect on an image. The value includes the name of the effect and an additional parameter that controls the behavior of the specific effect (the range and default value are given where this parameter is relevant). | |||||||||||||||||||||||||||||||||||||||
| hue | Adjust the image's hue (Range: -100 to 100, Default: 80). | |||||||||||||||||||||||||||||||||||||||||
| hue:40 |  | Adjust the image's hue to 40. | ||||||||||||||||||||||||||||||||||||||||
| red | Adjust the image's red channel (Range: -100 to 100, Default: 0). | |||||||||||||||||||||||||||||||||||||||||
| red:50 |  | Adjust the image's red channel to 50. | ||||||||||||||||||||||||||||||||||||||||
| green | Adjust the image's green channel (Range: -100 to 100, Default: 0). | |||||||||||||||||||||||||||||||||||||||||
| green:-30 |  | Adjust the image's green channel to -30. | ||||||||||||||||||||||||||||||||||||||||
| blue | Adjust the image's blue channel (Range: -100 to 100, Default: 0). | |||||||||||||||||||||||||||||||||||||||||
| blue:90 |  | Adjust the image's blue channel to 90. | ||||||||||||||||||||||||||||||||||||||||
| negate |  | Negate image colors (negative). | ||||||||||||||||||||||||||||||||||||||||
| brightness | Adjust image brightness (Range: -99 to 100, Default: 80) | |||||||||||||||||||||||||||||||||||||||||
| brightness:60 |  | Adjust image brightness to 60. | ||||||||||||||||||||||||||||||||||||||||
| brightness_hsb | Adjust image brightness modulation in HSB to prevent artifacts in some images (Range: -99 to 100, Default: 80) | |||||||||||||||||||||||||||||||||||||||||
| brightness_hsb:60 |  | Adjust image brightness in HSB modulation to 50. | ||||||||||||||||||||||||||||||||||||||||
| sepia | Change the color scheme of the image to sepia (Range: 1 to 100, Default: 80). | |||||||||||||||||||||||||||||||||||||||||
| sepia:50 |  | Change the color scheme of the image to sepia 50. | ||||||||||||||||||||||||||||||||||||||||
| grayscale |  | Convert image to gray-scale (multiple shades of gray). | ||||||||||||||||||||||||||||||||||||||||
| blackwhite |  | Covert image to black and white. | ||||||||||||||||||||||||||||||||||||||||
| saturation | Adjust the image's color saturation (Range: -100 to 100, Default: 80). | |||||||||||||||||||||||||||||||||||||||||
| saturation:70 |  | Adjust the image's color saturation to 70. | ||||||||||||||||||||||||||||||||||||||||
| colorize | Colorizes the image in grey by default (a different color can be specified by the color parameter). The extra value determines how strongly to apply the color (Range: 0 to 100, Default: 100). | |||||||||||||||||||||||||||||||||||||||||
| colorize:80 |  | Colorizes the image in grey with a strength of 80. | ||||||||||||||||||||||||||||||||||||||||
| tint | Blend your images with one or more tint colors and specify the intensity of the tinting. Optional - equalize colors before tinting, specify gradient blend positioning per color. Syntax: e_tint:[equalize]:[amount]:[color1]:[color1_position]:[color2]:[color2_position]:.....[color10]:[color10_position] | |||||||||||||||||||||||||||||||||||||||||
| tint:50:red:blue |  | Tints the image using red and blue at a 50% intensity. | ||||||||||||||||||||||||||||||||||||||||
| contrast | Adjust image contrast (Range: -100 to 100, Default: 0). | |||||||||||||||||||||||||||||||||||||||||
| contrast:-70 |  | Adjust image contrast to -70. | ||||||||||||||||||||||||||||||||||||||||
| auto_contrast |  | Automatically adjust contrast. | ||||||||||||||||||||||||||||||||||||||||
| vibrance | Apply a vibrance filter on the image (Range: -100 to 100, Default: 20). | |||||||||||||||||||||||||||||||||||||||||
| vibrance:70 |  | Apply a vibrance filter on the image with a strength of 70. | ||||||||||||||||||||||||||||||||||||||||
| auto_color |  | Automatically adjust color balance. | ||||||||||||||||||||||||||||||||||||||||
| improve |  | Automatically adjust image colors, contrast and lightness. | ||||||||||||||||||||||||||||||||||||||||
| auto_brightness |  | Automatically adjust brightness. | ||||||||||||||||||||||||||||||||||||||||
| fill_light | Adjust the fill light of an image (Range: -100 to 100, Default: 0). | |||||||||||||||||||||||||||||||||||||||||
| fill_light:50 |  | Adjust the fill light of an image to 50. | ||||||||||||||||||||||||||||||||||||||||
| art |
Apply the selected artistic filter. The following filters are available:
incognito | audrey | frost | linen | red_rock | primavera | eucalyptus | hokusai | |||||||||||||||||||||||||||||||||||||||||
| art:incognito |  | Apply the 'incognito' artistic filter. | ||||||||||||||||||||||||||||||||||||||||
| viesus_correct |  | Automatically enhance an image to its best visual quality with the Viesus Automatic Image Enhancement add-on. | ||||||||||||||||||||||||||||||||||||||||
| gamma | Adjust the gamma level (Range: -50 to 150, Default: 0). | |||||||||||||||||||||||||||||||||||||||||
| gamma:50 |  | Adjust the gamma level to 50. | ||||||||||||||||||||||||||||||||||||||||
| screen |  | Add an overlay image blended using the 'screen' blend mode. In this mode, each pixel of the image is made brighter according to the pixel value of the overlayed image. | ||||||||||||||||||||||||||||||||||||||||
| multiply |  | Add an overlay image blended using the 'multiply' blend mode. In this mode, each pixel of the image is made darker according to the pixel value of the overlayed image. | ||||||||||||||||||||||||||||||||||||||||
| overlay |  | Add an overlay image blended using the 'overlay' blend mode. In this mode, each pixel of the image is made darker or brighter according to the pixel value of the overlayed image. | ||||||||||||||||||||||||||||||||||||||||
| make_transparent |  | Make the background of the image transparent (or solid white for JPGs). The background is determined as all pixels that resemble the pixels on the edges of the image (Range: 0 to 100, Default: 10). | ||||||||||||||||||||||||||||||||||||||||
| trim |  | Detect and remove image edges whose color is similar to corner pixels (color similarity tolerance range: 0 to 100, Default: 10). | ||||||||||||||||||||||||||||||||||||||||
| shadow | Add a bottom right gray shadow. The shadow can be customized with the color, x and y parameters. (Strength range: 0 to 100, Default: 40) | |||||||||||||||||||||||||||||||||||||||||
| shadow:50 |  | Add a green shadow with a strength of 50 and with an offset specified by x:-3 & y:3. | ||||||||||||||||||||||||||||||||||||||||
| distort | Distorts the image to a new shape according to 8 values separated by colons (:), representing the new coordinates for each of the image's 4 corners, in clockwise order from the top-left corner. | |||||||||||||||||||||||||||||||||||||||||
| distort:5:34:70:10:70:75:5:55 |  | Distorts the image to a new shape with coordinates 5:34:70:10:70:75:5:55 | ||||||||||||||||||||||||||||||||||||||||
| shear | Skews the image according to two specified values in degrees separated by a colon (:), representing how much to skew the image on the x-axis and y-axis respectively. Negative values skew the image in the opposite direction. | |||||||||||||||||||||||||||||||||||||||||
| shear:20:0 |  | Skews the image on the x-axis by 20 degrees. | ||||||||||||||||||||||||||||||||||||||||
| displace |  | The pixels in the image are displaced according to the intensity of the pixels in another specified image (a gradient map specified with the overlay parameter). The stronger the intensity of each pixel in the gradient map, the bigger the displacement of the corresponding pixel in the base image. The amount of displacement in the horizontal and vertical directions is controlled by using the 'x' and 'y' parameters respectively. | ||||||||||||||||||||||||||||||||||||||||
| oil_paint | Apply an oil painting effect (Range: 0 to 100, Default: 30). | |||||||||||||||||||||||||||||||||||||||||
| oil_paint:40 |  | Apply an oil painting effect with a strength of 40. | ||||||||||||||||||||||||||||||||||||||||
| redeye |  | Automatically remove red eyes in an image. | ||||||||||||||||||||||||||||||||||||||||
| adv_redeye |  | Automatically remove red eyes with the Advanced Facial Attribute Detection add-on. | ||||||||||||||||||||||||||||||||||||||||
| vignette | Apply a vignette effect (Range: 0 to 100, Default: 20). | |||||||||||||||||||||||||||||||||||||||||
| vignette:30 |  | Apply a vignette effect with a strength of 30. | ||||||||||||||||||||||||||||||||||||||||
| gradient_fade | Apply a gradient fade effect on the image (Range: 0 to 100, Default: 20). | |||||||||||||||||||||||||||||||||||||||||
| gradient_fade:40 |  | Apply a gradient fade effect with a strength of 40. | ||||||||||||||||||||||||||||||||||||||||
| pixelate | Apply a pixelation effect. The additional value determines the width in pixels of each pixelation square (Range: 1 to 200, Default: 5). | |||||||||||||||||||||||||||||||||||||||||
| pixelate:3 |  | Apply a pixelation effect with pixelation squares of 3 pixels wide. | ||||||||||||||||||||||||||||||||||||||||
| pixelate_region | Pixelate only a certain region of the image based on the given x, y, width and height. The additional value determines the width in pixels of each pixelation square (Range: 1 to 200, Default: 5). | |||||||||||||||||||||||||||||||||||||||||
| pixelate_region:20 |  | Pixelate a region with pixelation squares of 20 pixels wide. | ||||||||||||||||||||||||||||||||||||||||
| pixelate_faces | Automatically pixelate all detected faces in the image. The additional value determines the width in pixels of each pixelation square (Range: 1 to 200, Default: 5). | |||||||||||||||||||||||||||||||||||||||||
| pixelate_faces:7 |  | Automatically pixelate all detected faces in the image with pixelation squares of 7 pixels wide. | ||||||||||||||||||||||||||||||||||||||||
| blur | Apply a blurring filter on the image (Range: 1 to 2000, Default: 100). | |||||||||||||||||||||||||||||||||||||||||
| blur:300 |  | Apply a blurring filter on the image with a strength of 300. | ||||||||||||||||||||||||||||||||||||||||
| blur_region | Apply a blurring filter on a certain region of an image, specified by x, y, width and height (Range: 1 to 2000, Default: 100). | |||||||||||||||||||||||||||||||||||||||||
| blur_region:200 |  | Apply a blurring filter on a certain region of an image with a strength of 200. | ||||||||||||||||||||||||||||||||||||||||
| blur_faces | Automatically blur all detected faces in the image (Range: 1 to 2000, Default: 500). | |||||||||||||||||||||||||||||||||||||||||
| blur_faces:600 |  | Automatically blur all detected faces in the image with a strength of 600. | ||||||||||||||||||||||||||||||||||||||||
| sharpen | Apply a sharpening filter (Range: 1 to 2000, Default: 100). | |||||||||||||||||||||||||||||||||||||||||
| sharpen:400 |  | Apply a sharpening filter with a strength of 400. | ||||||||||||||||||||||||||||||||||||||||
| unsharp_mask | Apply an unsharp mask filter (Range: 1 to 2000, Default: 100). | |||||||||||||||||||||||||||||||||||||||||
| unsharp_mask:200 |  | Apply an unsharp mask filter with a strength of 200. | ||||||||||||||||||||||||||||||||||||||||
| ordered_dither |  | Apply an ordered dither filter on the image. Possible levels described below (Default 0):
| ||||||||||||||||||||||||||||||||||||||||
| opacity | o | percents | Adjust the opacity of the image and make it semi-transparent. 100 means opaque, while 0 is completely transparent. | |||||||||||||||||||||||||||||||||||||||
| 30 |  | Reduce image opacity to 30%. | ||||||||||||||||||||||||||||||||||||||||
| 60 |  | Add the 'badge' image as an overlay with an opacity of 60%. | ||||||||||||||||||||||||||||||||||||||||
| border | bo | style | Add a solid border around the image. The value has a CSS-like format: width_style_color. When using Cloudinary's client integration libraries, you can set the border values programmatically (e.g., :border => { :width => 4, :color => 'black' }). Currently, only `solid` is supported for style. Colors can be set as an RGB or RGBA hex triplet or quadruplet, a 3- or 4-digit RGB/RGBA hex, or a named color. | |||||||||||||||||||||||||||||||||||||||
| 4px_solid_black |  | Add a 4 pixels wide black border to the image. | ||||||||||||||||||||||||||||||||||||||||
| 3px_solid_rgb:00390b |  | Add a 3 pixels wide border of the color #00390b. When using the client libraries you can set the color parameter to '#00390b' instead of adding 'rgb:00390b'. | ||||||||||||||||||||||||||||||||||||||||
| 6px_solid_rgb:00390b60 |  | Add a 6 pixels wide border of a semi transparent RGB color. The last 2 digits are the hex value of the alpha channel. | ||||||||||||||||||||||||||||||||||||||||
| background | b | color | Defines the background color to use instead of transparent background areas when converting to JPG format or using the pad crop mode. The background color can be set as an RGB or RGBA hex triplet or quadruplet, a 3- or 4-digit RGB/RGBA hex, or a named color. | |||||||||||||||||||||||||||||||||||||||
| blue |  | Fill transparent background with blue. | ||||||||||||||||||||||||||||||||||||||||
| rgb:9090ff |  | Fill transparent background with the opaque color #9090ff. | ||||||||||||||||||||||||||||||||||||||||
| overlay | l | identifier | Add an overlay over the base image. You can control the dimension and position of the overlay using the width, height, x, y and gravity parameters. The overlay can take one of the following forms:
identifier can be a public ID of an uploaded image or a specific image kind, public ID and settings.
* l_<public ID of image> to add an overlay of an image. * l_text:<public ID of text image>:<text string> to add a text overlay with styling based on the public ID of an existing text image. * l_text:<style settings>:<text string> to add a text overlay using the given style settings. | |||||||||||||||||||||||||||||||||||||||
| badge |  | Add the overlay with the public ID 'badge' 10, 20 pixels from the south east corner of the base image while resizing the overlay to have a width of 30 pixels. | ||||||||||||||||||||||||||||||||||||||||
| text:default_style:Hello+World |  | Add a 'Hello World' text overlay using the 'default_style' text style that was predefined using our API. | ||||||||||||||||||||||||||||||||||||||||
| text:Arial_50:Smile! |  | Add a 'Smile' text overlay using 50 pixel bold Arial font. | ||||||||||||||||||||||||||||||||||||||||
| lut:iwltbap_aspen.3dl |  | Apply the iwltbap_aspen.3dl 3D LUT file to the image. | ||||||||||||||||||||||||||||||||||||||||
| underlay | u | identifier | Add an underlay image below a base partially-transparent image. You can control the dimensions and position of the underlay using the width, height, x, y and gravity parameters. The identifier can be a public ID of an uploaded image or a specific image kind, public ID and settings. The underlay parameter shares the same features as the overlay parameter. | |||||||||||||||||||||||||||||||||||||||
| site_bg.jpg |  | Add the underlay with the public ID 'site_bg' and 'jpg' format, while resizing the underlay to match the size of the base image. | ||||||||||||||||||||||||||||||||||||||||
| default_image | d | identifier | Specify the public ID of a placeholder image to use if the requested image or social network picture does not exist. The name of the placeholder image must include the file extension. | |||||||||||||||||||||||||||||||||||||||
| avatar.png |  | Return the image with the 'avatar' public ID if an image with the ID of 'non_existing_id' does not exist. The requested transformations are applied on the placeholder image as well. | ||||||||||||||||||||||||||||||||||||||||
| delay | dl | integer | Controls the time delay between the frames of an animated image, in milliseconds. | |||||||||||||||||||||||||||||||||||||||
| 20 | Sets the delay between frames of an animated image to 20 milliseconds. | |||||||||||||||||||||||||||||||||||||||||
| color | co | color | Customize the color to use together with: text captions, the shadow effect and the colorize effect. The color can be set as an RGB or RGBA hex triplet or quadruplet, a 3- or 4-digit RGB/RGBA hex, or a named color. | |||||||||||||||||||||||||||||||||||||||
| red |  | Apply a red colorize effect to the image. | ||||||||||||||||||||||||||||||||||||||||
| rgb:20a020 |  | Apply a colorize effect to the image while specifying the green color as an RGB hex triplet. | ||||||||||||||||||||||||||||||||||||||||
| dpr | dpr | number | Deliver the image in the specified device pixel ratio. The parameter accepts any positive float value. | |||||||||||||||||||||||||||||||||||||||
| 2.0 |  | Deliver the image with a dpr ratio of 2.0 | ||||||||||||||||||||||||||||||||||||||||
| auto |  | Deliver the image in a resolution that automatically matches the DPR (Device Pixel Ratio) setting of the user's device, rounded up to the nearest integer. Only works for certain browsers and when Client-Hints are enabled (see the Automatic DPR documentation) | ||||||||||||||||||||||||||||||||||||||||
| page | pg | number | Given a multi-page file (PDF, animated GIF, TIFF), generate an image of a single page using the given index. | |||||||||||||||||||||||||||||||||||||||
| 2 |  | Generate a JPG thumbnail of the second page of a PDF. | ||||||||||||||||||||||||||||||||||||||||
| density | dn | dpi | Control the density to use while converting a PDF document to images. (range: 50-300, default: 150) | |||||||||||||||||||||||||||||||||||||||
| 10 |  | Generate a JPG thumbnail using a density of 10. | ||||||||||||||||||||||||||||||||||||||||
| flags | fl | name or names | Set one or more flags that alter the default transformation behavior. Separate multiple flags with a dot (`.`). | |||||||||||||||||||||||||||||||||||||||
| any_format | When used together with automatic quality (q_auto): allow switching to PNG8 encoding if the quality algorithm decides that it's more efficient. | |||||||||||||||||||||||||||||||||||||||||
| attachment | Deliver the image as an attachment. When the image's URL is accessed, tells the browser to save the image instead of embedding it in a page. The original image’s filename will be used as the file name (rather than the public_id) unless the “discard_original_filename” was set during the file upload. | |||||||||||||||||||||||||||||||||||||||||
| awebp | When converting animated GIF images to the WebP format, generate an Animated WebP from all the frames in the animated GIF file instead of only from the first still frame of the GIF. | |||||||||||||||||||||||||||||||||||||||||
| clip | Trim pixels according to a clipping path included in the original image (e.g., manually created using PhotoShop). | |||||||||||||||||||||||||||||||||||||||||
| cutter | Trim pixels according to the transparency levels of a given overlay image. Whenever the overlay image is opaque, the original is shown, and wherever the overlay is transparent, the result will be transparent as well. | |||||||||||||||||||||||||||||||||||||||||
| force_strip | Tells Cloudinary to clear all image meta-data (IPTC, Exif and XMP) while applying an incoming transformation. | |||||||||||||||||||||||||||||||||||||||||
| ignore_aspect_ratio | Allow specifying only either width or height so the value of the second axis remains as is and is not calculated to maintain aspect ratio of the original image. | |||||||||||||||||||||||||||||||||||||||||
| keep_iptc | Without this flag, Cloudinary's default behavior is to strip all meta-data when generating new image transformations. | |||||||||||||||||||||||||||||||||||||||||
| layer_apply | Apply all chained transformations, until a transformation component that includes this flag, on the last added overlay or underlay instead of applying on the containing image. | |||||||||||||||||||||||||||||||||||||||||
| lossy | Automatically use lossy compression when delivering animated GIF files. This flag can also be used as a conditional flag for delivering PNG files: it tells Cloudinary to deliver the image in PNG format (as requested) unless there is no transparency channel - in which case deliver in JPEG format. | |||||||||||||||||||||||||||||||||||||||||
| preserve_transparency | When used with automatic fetch_format (f_auto): ensures that images with a transparency channel will be delivered in PNG format. | |||||||||||||||||||||||||||||||||||||||||
| png8 | Generate PNG images in the PNG8 format instead of the default PNG24 format. | |||||||||||||||||||||||||||||||||||||||||
| progressive | Generate a JPG image using the progressive (interlaced) JPG format. This format allows the browser to quickly show a low-quality rendering of the image until the full-quality image is loaded. | |||||||||||||||||||||||||||||||||||||||||
| rasterize | Reduces the image to one flat pixelated layer (as opposed to the default vector based graphic) in order to enable PDF resizing and overlay manipulations. | |||||||||||||||||||||||||||||||||||||||||
| region_relative | Modify percentage-based width & height parameters of overlays and underlays (e.g., 1.0) to be relative to the overlaid region. Currently regions are only defined when using gravity 'face', 'faces' or 'custom'. | |||||||||||||||||||||||||||||||||||||||||
| relative | Modify percentage-based width & height parameters of overlays and underlays (e.g., 1.0) to be relative to the containing image instead of the added layer. | |||||||||||||||||||||||||||||||||||||||||
| strip_profile | Tells Cloudinary to clear all ICC color profile data included with the image. | |||||||||||||||||||||||||||||||||||||||||
| text_no_trim | Tells Cloudinary not to automatically trim the excess space from around a dynamic text string. | |||||||||||||||||||||||||||||||||||||||||
| no_overflow | Prevents Cloudinary from extending the image canvas beyond the original dimensions when overlaying text and other images. | |||||||||||||||||||||||||||||||||||||||||
| tiled | Tile the added overlay over the entire image. | |||||||||||||||||||||||||||||||||||||||||
| if | if | condition | Apply a transformation only if a specified condition is met (see the conditional transformations documentation). | |||||||||||||||||||||||||||||||||||||||
| w_gt_300 |  | Apply an oil painting effect if the width is greater than 300 pixels. | ||||||||||||||||||||||||||||||||||||||||
| transformation | t | name | Apply a pre-defined named transformation of the given name. When using Cloudinary's client integration libraries, the 'transformation' parameter accepts an array of transformation parameters to be chained together. | |||||||||||||||||||||||||||||||||||||||
| media_lib_thumb |  | Apply the named 'media_lib_thumb' transformation. | ||||||||||||||||||||||||||||||||||||||||
The reference table above is a summary of the available transformation and delivery parameters. For in-depth information with lots of examples on transforming images, see the image transformations documentation.