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

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")
JS:
cl.imageTag('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"}
  ]}).toHtml();
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"}
  ]})
React:
<Image publicId="yellow_tulip.jpg" >
  <Transformation width="220" height="140" crop="fill" />
  <Transformation overlay="brown_sheep" width="220" height="140" x="220" crop="fill" />
  <Transformation overlay="horses" width="220" height="140" y="140" x="-110" crop="fill" />
  <Transformation overlay="white_chicken" width="220" height="140" y="70" x="110" crop="fill" />
  <Transformation overlay="butterfly.png" height="200" x="-10" angle="10" />
  <Transformation width="400" height="260" radius="20" crop="crop" />
  <Transformation overlay="text:Parisienne_35_bold:Memories%20from%20our%20trip" color="#990C47" y="155" />
  <Transformation effect="shadow" />
</Image>
Angular:
<cl-image public-id="yellow_tulip.jpg" >
  <cl-transformation width="220" height="140" crop="fill">
  </cl-transformation>
  <cl-transformation overlay="brown_sheep" width="220" height="140" x="220" crop="fill">
  </cl-transformation>
  <cl-transformation overlay="horses" width="220" height="140" y="140" x="-110" crop="fill">
  </cl-transformation>
  <cl-transformation overlay="white_chicken" width="220" height="140" y="70" x="110" crop="fill">
  </cl-transformation>
  <cl-transformation overlay="butterfly.png" height="200" x="-10" angle="10">
  </cl-transformation>
  <cl-transformation width="400" height="260" radius="20" crop="crop">
  </cl-transformation>
  <cl-transformation overlay="text:Parisienne_35_bold:Memories%20from%20our%20trip" color="#990C47" y="155">
  </cl-transformation>
  <cl-transformation effect="shadow">
  </cl-transformation>
</cl-image>
.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")
Transformation example

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
widthwpixels, percents or stringThe required width of a transformed image or an overlay. Can be specified separately or together with the height value. To set the width of the image to the initial width of the original image use the value 'iw' ('ow' has been deprecated).
80Face_topResize width to 80 pixels while maintaining aspect ratio.
0.2Face_topResize image to 20% of its original size.
0.2Face_topResize 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).
autoResizes the image to the nearest rounding step of 100 pixels (by default), e.g., 345 is rounded up to 400.
auto:50Resizes 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:87Resizes 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:breakpointsResizes the image to nearest breakpoint (rounded up). The breakpoints are calculated using the default breakpoint request settings.
auto:breakpoints_200_1920_30_15Resizes 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]:jsonAllows client-side applications to access the calculated breakpoints as a JSON response.
auto:breakpoints_20_190_10_15:jsonReturns a JSON response with the calculated breakpoints for the following breakpoint request settings - `min_width=20`, `max_width=190`, `bytes_step=10`, `max_images=15`.
 
heighthpixels, percents or stringThe required height of a transformed image or an overlay. Can be specified separately or together with the width value. To set the height of the image to the initial height of the original image use the value 'ih' ('oh' has been deprecated).
40Face_topResize height to 40 pixels while maintaining aspect ratio.
0.3Face_topResize image to 30% of its original size.
 
cropcmodeA 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)Face_topChange 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.
fitFace_topThe 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.
limitFace_topSame 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.
mfitFace_topSame 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.
fillFace_topCreate 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).
lfillFace_topSame 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).
padFace_topResize 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.
lpadFace_topSame 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.
mpadFace_topSame 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.
cropFace_topUsed to extract a given width & height out of the original image. The original proportions are retained and so is the size of the graphics.
thumbFace_topGenerate a thumbnail using face detection in combination with the 'face' or 'faces' gravity.
imagga_cropFamily_benchCrop 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_scaleFamily_benchScale 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_ratioarratio or percentResize 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.5SampleCrop the image to an aspect ratio of 1.5
16:9SampleCrop the image to an aspect ratio of 16:9
 
gravitygdirectionDecides 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_westFatcatNorth west corner (top left).
northFatcatNorth center part (top center).
north_eastFatcatNorth east corner (top right).
westFatcatMiddle west part (left).
center(default)FatcatThe center of the image.
eastFatcatMiddle east part (right).
south_westFatcatSouth west corner (bottom left).
southFatcatSouth center part (bottom center).
south_eastFatcatSouth east corner (bottom right).
xy_centerFatcatSet the crop's center of gravity to the given x & y coordinates"
faceFace_topAutomatically 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:centerSame as the 'face' gravity, but defaults to 'center' gravity instead of 'north' if no face is detected.
face:autoSame as the 'face' gravity, but defaults to 'auto' gravity instead of 'north' if no face is detected.
facesCoupleAutomatically detect multiple faces in an image and aim to make them the center of the cropped image.
faces:centerSame as the 'faces' gravity, but defaults to 'center' gravity instead of 'north' if no faces are detected.
faces:autoSame as the 'faces' gravity, but defaults to 'auto' gravity instead of 'north' if no faces are detected.
bodyFace_topAutomatically 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.
body:faceFace_topAutomatically detect the largest body in an image and aim to make it the center of the cropped image. Defaults to the 'face' gravity if a full body was not detected.
ocr_textStop_signDetect all text elements in an image using the OCR Text Detection and Extraction add-on and use the detected bounding box coordinates as the basis of the transformation.
adv_faceYoung_coupleAutomatically detect the largest face in an image with the Advanced Facial Attribute Detection add-on and make it the focus of the transformation.
adv_facesYoung_coupleAutomatically detect all the faces in an image with the Advanced Facial Attribute Detection add-on and make them the focus of the transformation.
adv_eyesYoung_coupleAutomatically 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.
customFace_topUse 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:faceSame as the 'custom' gravity, but defaults to 'face' gravity if no custom coordinates are available.
custom:facesSame as the 'custom' gravity, but defaults to 'faces' gravity if no custom coordinates are available.
custom:adv_faceSame as the 'custom' gravity, but defaults to 'adv_face' gravity if no custom coordinates are available.
custom:adv_facesSame 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`).
autoFat_catAutomatically crop the image while giving higher priority to detected faces (same as `auto:faces`).
auto:adv_faceYoung_coupleAutomatically crop the image while giving higher priority to the largest face detected by the Advanced Facial Attribute Detection add-on.
auto:adv_facesYoung_coupleAutomatically crop the image while giving higher priority to faces detected by the Advanced Facial Attribute Detection add-on.
auto:adv_eyesYoung_coupleAutomatically crop the image while giving higher priority to eyes detected by the Advanced Facial Attribute Detection add-on.
auto:bodyCoupleAutomatically crop the image while giving higher priority to detected bodies.
auto:faceCoupleAutomatically crop the image while giving higher priority to the largest detected face.
auto:facesCoupleAutomatically crop the image while giving higher priority to detected faces (default value if no `focal_gravity` is specified).
auto:no_facesCoupleAutomatically crop the image without giving higher priority to any detected element.
auto:custom_no_overrideFace_topAutomatically crop the image while giving higher priority to custom coordinates (custom coordinates don't override the automatic cropping).
auto:noneCoupleAutomatically crop the image without giving higher priority to any detected element (custom coordinates don't override the automatic cropping).
auto:50Sunset_shoes(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.
 
zoomzpercentControl 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.2Woman_sampleCropped with face detection and zoom set to 120%.
0.75Woman_sampleThumbnail with face detection and zoom set to 75%
 
xxpixels or percentHorizontal position for custom-coordinates based cropping, overlay placement and certain region related effects.
130Face_topCrop image to an 80x80 square starting 130 pixels from the left.
0.1Face_topPlace an overlay that is horizontally offset from the south_west corner by 10%
 
yypixels or percentVertical position for custom-coordinates based cropping and overlay placement.
340Face_topCrop image to an 80x80 square starting 340 pixels from the top.
0.2Face_topPlace an overlay that is vertically offset from the south_west corner by 10%
 
format(file extension)formatDeliver 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
jpgSampleDeliver the 'sample' image in jpg format.
 
fetch_formatfformatForce 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.
autoSampleAutomatically convert delivered images to WebP and JPEG-XR on supported browsers to save bandwidth and optimize delivery time (see the Automatic format selection documentation).
pngJennifer_lawrence_at_the_83rd_academy_awardsConvert a remote JPG image to the PNG format.
 
qualityqpercentControl 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.
100Face_topGenerate a thumbnail using highest image quality (9.15KB)
20Face_topGenerate 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:420Face_topGenerate 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).
autoFace_topAutomatically calculate the optimal quality an image: the smallest file size without affecting its perceptual quality (1.9KB). Same as `auto:good`.
auto:bestFace_topAutomatically calculate the optimal quality for images using a less aggressive algorithm (2.2KB).
auto:goodFace_topAutomatically calculate the optimal quality for an image: the smallest file size without affecting its perceptual quality (1.9KB).
auto:ecoFace_topAutomatically calculate the optimal quality for images using a more aggressive algorithm (1.7KB).
auto:lowFace_topAutomatically calculate the optimal quality for images using the most aggressive algorithm (1.5KB).
jpegminiFace_topUse the JPEGmini Image Optimization add-on to automatically calculate the optimal compression for JPEG images without affecting their perceptual quality.
 
radiusrpixels or `max`Round the specified corners of an image by specifying 1-4 pixel values as follows:
1 value: All four corners are rounded equally according to the specified value.
2 values: 1st value => top-left & bottom-right. 2nd value => top-right & bottom-left.
3 values: 1st value => top-left. 2nd value => top-right & bottom-left. 3rd value => bottom-right.
4 values: Each corner specified separately, in clockwise order, starting with top-left.

Or specify max to make the image a perfect circle or oval (ellipse).
20White_chickenGenerate an image with rounded corners of 20 pixels radius.
20:0:40:40White_chickenGenerate an image with 3 rounded corners of varying radii.
maxWhite_chickenGenerate an image with a circular crop using the 'max' radius value.
 
angleadegrees or modeRotate 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.
90SheepRotate image by 90 degrees clockwise.
10SheepRotate image by 10 degrees clockwise.
-20SheepRotate image by 20 degrees counterclockwise.
auto_rightSheepRotate image 90 degrees clockwise only if the requested aspect ratio does not match the image's aspect ratio.
auto_leftSheepRotate image 90 degrees counterclockwise only if the requested aspect ratio does not match the image's aspect ratio.
ignoreSheepBy 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.
vflipSheepVertical mirror flip of the image.
hflipSheepHorizontal mirror flip of the image.
 
effectename and valueApply 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).
hueAdjust the image's hue (Range: -100 to 100, Default: 80).
hue:40HorsesAdjust the image's hue to 40.
redAdjust the image's red channel (Range: -100 to 100, Default: 0).
red:50HorsesAdjust the image's red channel to 50.
greenAdjust the image's green channel (Range: -100 to 100, Default: 0).
green:-30HorsesAdjust the image's green channel to -30.
blueAdjust the image's blue channel (Range: -100 to 100, Default: 0).
blue:90HorsesAdjust the image's blue channel to 90.
negateHorsesNegate image colors (negative).
brightnessAdjust image brightness (Range: -99 to 100, Default: 80)
brightness:60HorsesAdjust image brightness to 60.
auto_brightnessAutomatically adjust the brightness and blend the result with the original image, where 0 means only use the original and 100 means only use the adjusted brightness result. (Range: 0 to 100, Default: 100).
auto_brightness:70HorsesAutomatically adjust the brightness to an amount of 70.
brightness_hsbAdjust image brightness modulation in HSB to prevent artifacts in some images (Range: -99 to 100, Default: 80)
brightness_hsb:60HorsesAdjust image brightness in HSB modulation to 50.
sepiaChange the color scheme of the image to sepia (Range: 1 to 100, Default: 80).
sepia:50HorsesChange the color scheme of the image to sepia 50.
grayscaleHorsesConvert image to gray-scale (multiple shades of gray).
blackwhiteHorsesCovert image to black and white.
saturationAdjust the image's color saturation (Range: -100 to 100, Default: 80).
saturation:70HorsesAdjust the image's color saturation to 70.
colorizeColorizes 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:80HorsesColorizes the image in grey with a strength of 80.
replace_colorMaps an input color and those similar to the input color to corresponding shades of a specified output color, taking luminosity and chroma into account, in order to recolor an object in a natural way. More highly saturated input colors usually give the best results. It is recommended to avoid input colors approaching white, black, or gray.
Syntax: e_replace_color:to_color:[tolerance]:[from_color]
- to_color: The HTML name or RGB/A hex code of the target output color.
- tolerance: The tolerance threshhold (a radius in the LAB color space) from the input color, representing the span of colors that should be replaced with a correspondingly adjusted version of the target output color. Larger values result in replacing more colors within the image. The more saturated the original input color, the more a change in value will impact the result. (default: 50).
- from_color: The base input color to map. Default: the most prominant high-saturation color in the image.
replace_color:saddlebrownGreen_shirt_bhrxf4Recolor the prominent (green) color in the image to a saddlebrown color, using the default tolerance.
replace_color:2F4F4F:20PooltableRecolor the prominent (red) color in the image to the specified (greenish_gray) hex color, using a tolerance of 20.
replace_color:silver:50:89b8edBlue_gazeeboRecolor the the specified (royal blue) hex color in the image to a silver color, using a tolerance of 50.
tintBlend 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:blueHorsesTints the image using red and blue at a 50% intensity.
contrastAdjust image contrast (Range: -100 to 100, Default: 0).
contrast:-70HorsesAdjust image contrast to -70.
auto_contrastAutomatically adjust contrast and blend the result with the original image, where 0 means only use the original and 100 means only use the adjusted contrast result. (Range: 0 to 100, Default: 100).
auto_contrast:50HorsesAutomatically adjust contrast by an amount of 50.
vibranceApply a vibrance filter on the image (Range: -100 to 100, Default: 20).
vibrance:70HorsesApply a vibrance filter on the image with a strength of 70.
auto_colorAutomatically adjust the color balance and blend the result with the original image, where 0 means only use the original and 100 means only use the adjusted color result. (Range: 0 to 100, Default: 100).
auto_color:80HorsesAutomatically adjust the color to an amount of 80.
improveHorsesAutomatically adjust image colors, contrast and lightness.
fill_lightAutomatically adjust the fill light and blend the result with the original image, where 0 means only use the original and 100 means only use the adjusted fill light result. (Range: 0 to 100, Default: 100). You can also configure the bias applied to the fill light effect by adding another value separated by another colon (Range: -100 to 100, Default: 0).
fill_light:70:20HorsesAutomatically adjust the fill light to an amount of 70, with a bias of 20.
outlineAdd an outline effect to an image.
Syntax: e_outline:[mode]:[width]:[blur]
- mode: how to apply the outline effect: `inner`, `inner_fill`, `outer`, `fill`. (Default: `inner` and `outer`).
- width: the thickness of the outline. (Range: 1 to 100, Default: 5)
- blur: the level of blur applied to the outline. (Range: 0 to 200, Default: 0)
outline:outer:5:200BalloonAdd an outline effect to the outer border of the image, with a width of 10 pixels and a blur value of 200.
cartoonifyApply a cartoon effect to an image.
Syntax: e_cartoonify:[line_strength]:[color_reduction]
- line_strength: the thickness of the lines. (Range: 0 to 100, Default: 50)
- color_reduction: the decrease in the number of colors and corresponding saturation boost of the remaining colors. (Range: 0 to 100, Default: automatically adjusts according to the line_strength value). Higher reduction values result in a less realistic look. Set the color_reduction to 'bw' for a black and white cartoon effect.
cartoonify:20:60HorsesGenerate a cartoonified version of the image with thin lines and fairly high saturation, unrealistic colors.
cartoonify:30:bwHorsesGenerate a black and white cartoonified version of the image with medium line thickness.
style_transferTransfer the styles of a source artwork to a target photograph using the Neural Artwork Style Transfer add-on.
Syntax: e_style_transfer:[preserve_color]:[style_strength]
- preserve_color: Boolean. When true, style elements of the source artwork, such as brush style and texture, are transfered to the target photo, but the prominent colors from the source artwork are not transferred, so the result retains the original colors of the target photo.
- style_strength: The strength of the style transfer. Higher numbers result in an output that is more highly influenced by the source artwork style. (Range: 0 to 100, Default: 100)
style_transferBeach_2_kidsGenerate an image using the content of the beach photo with the styles of the lighthouse photo.
style_transfer:preserve_color:40Beach_2_kidsGenerate an image using the content of the beach photo with the styles of the lighthouse photo, using a style strenght of 40, and preserving the colors of the target photo.
art Apply the selected artistic filter. The following filters are available:
al_dente | athena | audrey | aurora | daguerre | eucalyptus | fes | frost | hairspray | hokusai | incognito | linen | peacock | primavera | quartz | red_rock | refresh | sizzle | sonnet | ukulele | zorro
(View these filters applied to a sample image)
art:incognitoHorsesApply the 'incognito' artistic filter.
viesus_correctHorsesAutomatically enhance an image to its best visual quality with the Viesus Automatic Image Enhancement add-on.
gammaAdjust the gamma level (Range: -50 to 150, Default: 0).
gamma:50HorsesAdjust the gamma level to 50.
screenHorsesAdd 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.
multiplyHorsesAdd 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.
overlayHorsesAdd 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_transparentFashion_gravityMake 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).
trimFashion_gravityDetect and remove image edges whose color is similar to corner pixels (color similarity tolerance range: 0 to 100, Default: 10).
shadowAdd 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:50HorsesAdd a green shadow with a strength of 50 and with an offset specified by x:-3 & y:3.
distortDistorts 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:55HorsesDistorts the image to a new shape with coordinates 5:34:70:10:70:75:5:55
shearSkews 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:0HorsesSkews the image on the x-axis by 20 degrees.
displaceHorsesThe 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_paintApply an oil painting effect (Range: 0 to 100, Default: 30).
oil_paint:40HorsesApply an oil painting effect with a strength of 40.
redeyeLadyAutomatically remove red eyes in an image.
adv_redeyeRedeyeAutomatically remove red eyes with the Advanced Facial Attribute Detection add-on.
vignetteApply a vignette effect (Range: 0 to 100, Default: 20).
vignette:30HorsesApply a vignette effect with a strength of 30.
gradient_fadeApply a gradient fade effect from one edge of the image (Strength range: 0 to 100, Default: 20). Use x or y to indicate from which edge to fade and how much of the image should be faded. Only one direction can be specified. Values of x and y can be specified as a percentage (range: 0.0 to 1.0), or in pixels (integer values). Positive values fade from the top (y) or left (x). Negative values fade from the bottom (y) or right (x). By default, the gradient is applied to the top 50% of the image (y_0.5). Using this effect, the fade can be from only one direction. To apply different amounts of fade to multiple edges, use chained fade effects. To fade symmetrically from multiple edges, use gradient_fade:symmetric.
gradient_fade:40,y_0.8HorsesApply a gradient fade effect from the top 80% of the image with a strength of 40.
gradient_fade:symmetricApply a symmetrical gradient fade effect from either two or four sides of the image (Strength range: 0 to 100, Default: 20). Use x to indicate a symmetrical fade from the left and right edges, and y to indicate a symmetrical fade from top and bottom edges. Values of x and y can be specified as a percentage (range: 0.0 to 1.0), or in pixels (integer values). You can specify both x and y or just one of these. By default, the gradient is applied to the top and bottom 50% of the image (y_0.5).
e_gradient_fade:symmetric:25,x_0.15,y_0.15HorsesApply a gradient fade effect to 15% of all four sides of the image with a strength of 25.
gradient_fade:symmetric_padApply a symmetrical gradient fade effect when adding padding so it blends into the edge of the image (Strength range: 0 to 100, Default: 20). Values for x and y can also be specified as a percentage (range: 0.0 to 1.0), or in pixels (integer values) to indicate how far into the image to apply the gradient. By default, the gradient is applied 30% into the image (x_0.3).
e_gradient_fade:symmetric_pad:50,x_0.2HorsesApply a gradient fade effect, with a strength of 50, between the added padding and 20% into the image.
pixelateApply a pixelation effect. The additional value determines the width in pixels of each pixelation square (Range: 1 to 200, Default: 5).
pixelate:3HorsesApply a pixelation effect with pixelation squares of 3 pixels wide.
pixelate_regionPixelate 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:20HorsesPixelate a region with pixelation squares of 20 pixels wide.
pixelate_facesAutomatically 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:7CoupleAutomatically pixelate all detected faces in the image with pixelation squares of 7 pixels wide.
blurApply a blurring filter on the image (Range: 1 to 2000, Default: 100).
blur:300HorsesApply a blurring filter on the image with a strength of 300.
blur_regionApply 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:200HorsesApply a blurring filter on a certain region of an image with a strength of 200.
blur_facesAutomatically blur all detected faces in the image (Range: 1 to 2000, Default: 500).
blur_faces:600CoupleAutomatically blur all detected faces in the image with a strength of 600.
sharpenApply a sharpening filter (Range: 1 to 2000, Default: 100).
sharpen:400HorsesApply a sharpening filter with a strength of 400.
unsharp_maskApply an unsharp mask filter (Range: 1 to 2000, Default: 100).
unsharp_mask:200HorsesApply an unsharp mask filter with a strength of 200.
ordered_ditherHorsesApply an ordered dither filter on the image. Possible levels described below (Default 0):
0 Threshold 1x1 (non-dither)
1 Checkerboard 2x1 (dither)
2 Ordered 2x2 (dispersed)
3 Ordered 3x3 (dispersed)
4 Ordered 4x4 (dispersed)
5 Ordered 8x8 (dispersed)
6 Halftone 4x4 (angled)
7 Halftone 6x6 (angled)
8 Halftone 8x8 (angled)
9 Halftone 4x4 (orthogonal)
10 Halftone 6x6 (orthogonal)
11 Halftone 8x8 (orthogonal)
12 Halftone 16x16 (orthogonal)
13 Circles 5x5 (black)
14 Circles 5x5 (white)
15 Circles 6x6 (black)
16 Circles 6x6 (white)
17 Circles 7x7 (black)
18 Circles 7x7 (white)
loopLimit the (0-based) number of loops that an animated GIF run. (By default, animated GIFs with resource_type image run in an infinite loop.)
loop:2Spiral_animatedLoop the animated GIF 3 times.
 
opacityopercentsAdjust the opacity of the image and make it semi-transparent. 100 means opaque, while 0 is completely transparent.
30Autumn_leavesReduce image opacity to 30%.
60Autumn_leavesAdd the 'badge' image as an overlay with an opacity of 60%.
 
borderbostyleAdd 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_blackAutumn_leavesAdd a 4 pixels wide black border to the image.
3px_solid_rgb:00390bAutumn_leavesAdd 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:00390b60Autumn_leavesAdd a 6 pixels wide border of a semi transparent RGB color. The last 2 digits are the hex value of the alpha channel.
 
backgroundbcolorDefines 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.
blueBadgeFill transparent background with blue.
rgb:9090ffBadgeFill transparent background with the opaque color #9090ff.
auto[:mode]Automatically sets the background color to the most prominant color in the image when applying one of the padding crop modes. 'mode' can be one of the following values: border, predominant, border_contrast, predominant_contrast. See the Content-aware padding documentation for more details.
auto:predominantTulipSet the background color to the most predominant color in the image.
 
overlaylidentifierAdd 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. For details on available style settings, see Adding text captions.
* l_text:<style settings>:<text string> to add a text overlay using the given style settings.
badgeFace_topAdd 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+WorldFace_topAdd a 'Hello World' text overlay using the 'default_style' text style that was predefined using our API.
text:Arial_50:Smile!Face_topAdd a 'Smile' text overlay using 50 pixel bold Arial font.
lut:iwltbap_aspen.3dlFace_topApply the iwltbap_aspen.3dl 3D LUT file to the image.
 
underlayuidentifierAdd 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.jpgSmartphoneAdd the underlay with the public ID 'site_bg' and 'jpg' format, while resizing the underlay to match the size of the base image.
 
default_imagedidentifierSpecify 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.pngNon_existing_idReturn 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.
 
delaydlintegerControls the time delay between the frames of an animated image, in milliseconds.
20Sets the delay between frames of an animated image to 20 milliseconds.
 
colorcocolorCustomize 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.
redFace_topApply a red colorize effect to the image.
rgb:20a020Face_topApply a colorize effect to the image while specifying the green color as an RGB hex triplet.
 
color_spacecspredefined valueControl the color space used for the delivered image. Possible values:
* srgb: Render the image in the sRGB color space.
* tinysrgb: Render the image using Facebook's truncated sRGB color space.
* no_cmyk: If the original image used the cmyk color space, convert it to sRGB.
* cs_icc:[public_id]: Render the image using the specified color space (icc) file. The icc file must be uploaded to your account as a raw, authenticated file. Specify the public ID of your icc file including the file extension.
srgbFace_topRender the image in the sRGB color space.
no_cmykFace_topIf the original image used the cmyk color space, convert it to sRGB.
 
dprdprnumberDeliver the image in the specified device pixel ratio. The parameter accepts any positive float value.
2.0Face_topDeliver the image with a dpr ratio of 2.0
autoDeliver 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)
 
pagepgnumberGiven a multi-page file (PDF, animated GIF, TIFF), generate an image of a single page using the given index.
2Multi_page_pdfGenerate a JPG thumbnail of the second page of a PDF.
 
densitydndpiControl the density to use while converting a PDF document to images. (range: 50-300, default: 150)
10Multi_page_pdfGenerate a JPG thumbnail using a density of 10.
 
flagsflname or namesSet one or more flags that alter the default transformation behavior. Separate multiple flags with a dot (`.`).
any_formatWhen used together with automatic quality (q_auto): allow switching to PNG8 encoding if the quality algorithm decides that it's more efficient.
attachmentDeliver 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.
apngWhen converting animated images to PNG format, generate an animated PNG from all the frames in the original animated file instead of only from the first still frame. Note that animated PNGs are not supported in all browsers and versions.
awebpWhen converting animated images to WebP format, generate an animated WebP from all the frames in the original animated file instead of only from the first still frame. Note that animated WebPs are not supported in all browsers and versions.
clipTrim pixels according to a clipping path included in the original image (e.g., manually created using PhotoShop).
clip_evenoddTrim pixels according to a clipping path included in the original image (e.g., manually created using PhotoShop) using an evenodd clipping rule.
cutterTrim 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_stripTells Cloudinary to clear all image meta-data (IPTC, Exif and XMP) while applying an incoming transformation.
ignore_aspect_ratioAllow specifying only either width or height so the value of the second axis remains as is, and is not recalculated to maintain the aspect ratio of the original image.
immutable_cacheSets the cache-control to immutable for the image, which tells the browser that the image does not have to be revalidated with the server when the page is refreshed, and can be loaded directly from the cache. Currently supported only by Firefox.
keep_attributionKeeps the copyright related fields when stripping meta-data. Without this flag, Cloudinary's default behavior is to strip all meta-data when generating new image transformations.
keep_iptcKeeps all meta-data. Without this flag, Cloudinary's default behavior is to strip all meta-data when generating new image transformations.
layer_applyApply 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.
lossyAutomatically 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.
no_overflowPrevents Cloudinary from extending the image canvas beyond the original dimensions when overlaying text and other images.
preserve_transparencyWhen used with automatic fetch_format (f_auto): ensures that images with a transparency channel will be delivered in PNG format.
png8Generate PNG images in the PNG8 format.
png24Generate PNG images in the PNG24 format.
png32Generate PNG images in the PNG32 format.
progressiveGenerate 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. The parameter also accepts a mode value to determine a specific progressive outcome as follows:
* progressive:semi - A smart optimization of the decoding time, compression level and progressive rendering (less iterations). This is the default mode when using q_auto.
* progressive:steep - Delivers a preview very quickly, and in a single later phase improves the image to the required resolution.
* progressive:none - Use this to deliver a non-progressive image. This is the default mode when setting a specific value for quality.
rasterizeReduces 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_relativeModify 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'.
relativeModify 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_profileTells Cloudinary to clear all ICC color profile data included with the image.
text_no_trimBy default, text overlays are trimmed tightly to the text with no excess padding. This flag adds a small amount of padding around the text overlay string.
tiff8_lwzGenerate TIFF images using LZW compression and in the TIFF8 format.
tiledTile the added overlay over the entire image.
 
transformationtnameApply 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_thumbSampleApply the named 'media_lib_thumb' transformation.
 
[arithmetic operators]operatorAdjust the value of numeric parameters or user-defined variables using arithmetic operators. For details, see Using arithmetic expressions.
w_div_20SampleAdd a shadow whose size is 5% of the image width (w_div_20).
 
ififconditionApply a transformation only if a specified condition is met. For details, see conditional transformations.
w_gt_300SampleApply an oil painting effect if the width is greater than 300 pixels.
 
variable$user-defined variableDefine and assign values to user defined variables, and then use the variables as values for other parameters. For details, see Using user-defined variables
$width_60/t_passport_photoWomanDefine a user-defined variable called $width and set it to 60 pixels. Then pass the value of the variable to the named transformation, passport_photo, which references the $width variable.


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.