How to integrate Cloudinary in your app

Set Up Account Configure SDK Upload Media Transform & Deliver Next Steps

Cloudinary enables you to programmatically add image and video upload, manipulation, optimization, and delivery capabilities to your applications via easy-to-use REST APIs. Furthermore, Cloudinary offers a variety of SDK libraries that wrap Cloudinary's REST APIs, enabling you to seamlessly integrate Cloudinary functionality with your existing application code.

This page offers a high-level overview on the steps required to integrate Cloudinary within your application, with links to more detailed documentation. This page is by no means an extensive coverage of all Cloudinary has to offer, but is meant as a way to familiarize yourself with the major areas of integration and the various options available where applicable, before you start to integrate Cloudinary within your application.

Each step of the process involves making some decisions based on your existing code, your programming preferences, and your application requirements. Some of these questions are highlighted at the beginning of each step below.

Tip
In addition to this page, don't miss the Service overview, which provides an overview of Cloudinary's service architecture, asset storage, security, available add-ons, and other details about how the service works at a high-level.

1. Create and set up your account

Questions you'll answer in this section

  • What should my account cloud name be?
  • What account settings should I set before I get started?

Creating and setting up your account takes only a few minutes.

Create and tour your account

If you don't have a Cloudinary account yet, you can sign up for a free account now.

The signup form includes an option to select the cloud name for your account. That cloud name will appear in the URL of every asset you deliver from Cloudinary, so you should pick a cloud name that's a good representation of your organization, application or website. If you don't choose one, a randomly generated cloud name will be assigned.

If you already have an account and you want to change your cloud name, you can still do that as described below.

Tip
After you signup, don't forget to look for the Cloudinary - Email verification email and click the link inside to set your account as active.

Get started tour

Right after you register and log in to your new account, a short Get Started tour pops up, which gives you a quick overview of Cloudinary capabilities and helps direct you to useful information in the console and documentation (if you don't complete the tour on sign-up you can still access it later through the Welcome link on the main toolbar of the Cloudinary console).

Get familiar with the Cloudinary console

When you finish registering and close the Get Started Tour window, you will be in the Cloudinary console. At this stage, the most important areas of the console to become familiar with are the Account Details section at the top of the Dashboard page, the Media Library, and your account Settings.

Account Details

The account details section on the Dashboard page shows your cloud name identifier, as well as your API key and secret, which you will need in order to configure your SDK or to directly run API requests.

The Environment variable combines all three of these values and can be copied for quick configuration of your SDK and other server-side integrations.

Cloudinary account details

Important

  • Your cloud name and API key are used for enabling or configuring a variety of Cloudinary features. And as mentioned above, your cloud name is also a part of every media asset URL you deliver from Cloudinary. There's no problem to include these two values in client-side code.
  • Your API secret is used for authentication and should never be exposed in client-side code or in any other way outside your organization.

Media Library

The Media Library page of your Cloudinary console provides a comprehensive UI for managing all the digital assets in your account, including navigating folders, performing advanced searches, compiling assets into ad-hoc collections, collaborating on assets with other Cloudinary users by commenting on assets, drag-and-drop upload of new assets, and more.

Media Library

When you create a new account, a set of sample assets are provided in the Media Library. You can experiment with the Media Library features using these assets.

For more details, see the Digital Asset Management guide.

Optional. Update cloud name and other account settings

You can get started using Cloudinary with the default settings, but there are a few initial settings you may want to consider modifying from the start.

Click the Settings icon at the top-right of the console to view your account settings.

Account settings

View or update your cloud name

At the bottom of the Account settings, you can see the Cloudinary cloud name that you set (or was automatically assigned) during registration. If you have not yet uploaded more than 50 new assets to your account, you can change your cloud name now.

Note
The sample assets that are provided when you create a new account are not counted against this 50 asset limit for changing your cloud name, nor are they counted against your account storage quota.

If you need to change your cloud name and your account already has more than 50 assets, you need to submit a support request. Note that changing your cloud name will invalidate all cached URLs and all previously derived transformations, as well as invalidate your current session to the console, so you will need to log out and then log in to your new cloud account.

Check other initial settings

You may want to check or modify the following settings in the Upload page of the settings.

  • Automatic backup: When enabled, every uploaded file is also copied to a secondary write-protected location with multiple revisions per file. This means you can easily revert to an older version if needed. The default backup is to a Cloudinary storage location, meaning that your overall Cloudinary storage usage increases when you overwrite existing assets. Customers on a paid plan can alternatively back up to their own S3 or Google Cloud storage location.

    If you activate this option, then after you click Save at the bottom of the page, you can return to this option and select to Perform initial backup if you want to already backup any file currently in your account.

  • Default image quality: When you deliver any image with Cloudinary that includes one or more transformations, Cloudinary also automatically applies a quality adjustment to help optimize the the delivered image (unless you apply a specific quality setting when delivering a particular image). In new accounts, the default quality setting is 80.

    In most cases, you can improve the optimization and visual quality of your delivered images by changing this setting to Automatic - good quality (also known as q_auto). This option applies an intelligent quality and encoding algorithm to determine the best quality compression level and optimal encoding settings for each image based on the image content, so that you deliver all images with good visual quality while minimizing file size.

For more details, see Automatic quality and encoding settings.


2. Configure your SDK

Questions you'll answer in this section

  • Which SDK(s) should I use?
  • Which configuration options should I set globally for my SDK?

Cloudinary offers a vast array of open-source SDKs for easier implementation of Cloudinary functionality in both your server-side and client-side code. The SDK libraries wrap Cloudinary's REST APIs, enabling you to implement comprehensive image and video upload, manipulation, optimization, and delivery capabilities in your application, using code that integrates seamlessly with your existing application code.

Select the SDK(s) you want to use

We have a wide variety of SDKs to integrate with your code, for server-side, client-side and mobile development.

Server-side SDKs Client-side SDKs Mobile SDKs
   Ruby on Rails    React    iOS (Swift/ObjectiveC)
   PHP v2 Beta    ❘   PHP v1    Angular   Android
   Django/Python    JavaScript  
   Node.js    jQuery  
   Java    Vue.js  
   .NET    Svelte  

Install the SDK and include it in your application code

You can use the examples below as one way to install an SDK using the relevant package manager. For more detailed instructions and additional options, click an SDK above and review the Installation and setup section of the SDK guide.

Ruby:
Copy to clipboard
gem install cloudinary
PHP:
Copy to clipboard
//Add to composer.json
{
  "require": {
    "cloudinary/cloudinary_php": "dev-master"
  }
}
//Then run:
php composer.phar install
Python:
Copy to clipboard
pip install cloudinary
Node.js:
Copy to clipboard
npm install cloudinary
Java:
Copy to clipboard
//For Gradle, add to dependencies section of build.gradle
compile group: 'com.cloudinary', name: 'cloudinary-http44', version: '[Cloudinary API version, e.g. 1.1.3]'
JS:
Copy to clipboard
npm install cloudinary-core --save
jQuery:
Copy to clipboard
# For NPM:   
npm install jquery --save
npm install blueimp-file-upload --save
npm install cloudinary-jquery-file-upload --save

# For Bower: 
bower install cloudinary-jquery --save
React:
Copy to clipboard
npm install cloudinary-react --save
Vue.js:
Copy to clipboard
npm install cloudinary-vue
Angular:
Copy to clipboard
bower install cloudinary_ng#1.x --save
.Net:
Copy to clipboard
//Add CloudinaryDotNet using Nuget Package Manager or if using Package Manager Console: 
Install-Package CloudinaryDotNet
Android:
Copy to clipboard
//For Gradle, add to dependencies section of build.gradle
compile group: 'com.cloudinary', name: 'cloudinary-android', version: '1.24.0'
iOS:
Copy to clipboard
pod 'Cloudinary', '~> 2.0'

Set global configuration options

For all SDKs, you'll need to configure at least your cloud name.
For server-side SDKs, you'll also need to configure your api_key and api_secret.
Here are some examples of how you would set common global configuration options in our SDKs:

Ruby:
Copy to clipboard
development: 
  cloud_name: "demo"
  api_key: YOUR_KEY
  api_secret: YOUR_SECRET
  secure: true

production:
  cloud_name: "demo"
  api_key: YOUR_KEY
  api_secret: YOUR_SECRET
  secure:true
PHP:
Copy to clipboard
\Cloudinary::config(array( 
  "cloud_name" => "my_cloud_name", 
  "api_key" => "my_key", 
  "api_secret" => "my_secret", 
  "secure" => true
));
Python:
Copy to clipboard
cloudinary.config( 
  cloud_name = "sample", 
  api_key = "874837483274837", 
  api_secret = "a676b67565c6767a6767d6767f676fe1" 
)
Node.js:
Copy to clipboard
cloudinary.config({ 
  cloud_name: 'sample', 
  api_key: '874837483274837', 
  api_secret: 'a676b67565c6767a6767d6767f676fe1' 
});
Java:
Copy to clipboard
import com.cloudinary.*;
...
Cloudinary cloudinary = new Cloudinary(ObjectUtils.asMap(
  "cloud_name", "my_cloud_name",
  "api_key", "my_api_key",
  "api_secret", "my_api_secret"));
JS:
Copy to clipboard
var cl = new cloudinary.Cloudinary({cloud_name: "demo", secure: true});
jQuery:
Copy to clipboard
$.cloudinary.config({ cloud_name: 'sample', secure: true});
React:
Copy to clipboard
<CloudinaryContext cloudName="demo">
  <div>
    <Image publicId="sample" width="50" />
  </div>
  <Image publicId="sample" width="0.5" />
</CloudinaryContext>
Vue.js:
Copy to clipboard
import Cloudinary from 'cloudinary-vue';
Vue.use(Cloudinary, {
  configuration: {
    cloudName: "demo"
  }
});
Angular:
Copy to clipboard
yourApp.config(['cloudinaryProvider', function (cloudinaryProvider) {
  cloudinaryProvider
      .set("cloud_name", "mycompany")
      .set("secure", true)
      .set("upload_preset", "my_preset");
}]);
.Net:
Copy to clipboard
Account account = new Account(
  "my_cloud_name",
  "my_api_key",
  "my_api_secret");

Cloudinary cloudinary = new Cloudinary(account);
Android:
Copy to clipboard
Map config = new HashMap();
config.put("cloud_name", "myCloudName");
MediaManager.init(this, config);
iOS:
Copy to clipboard
let config = CLDConfiguration(cloudName: "CLOUD_NAME", secure: "true")
let cloudinary = CLDCloudinary(configuration: config)

There are also a variety of optional configurations you can set at a global level to control the default behavior of Cloudinary operations.

You can find more information on where and how to specify Cloudinary configuration options for your SDK in the Configuration section of the relevant SDK guide.


3. Add upload capabilities

Questions you'll answer in this section

  • Which upload method(s) are most appropriate for my needs?
  • Which types of upload options will be useful for my app?
  • If migrating existing assets to Cloudinary, which migration option is best for me?

Cloudinary offers a variety of options for programmatically uploading assets to your account from your application.

  • Upload API - Implement your own upload functionality with the upload method of the Upload API. This method can be called directly from within your own custom code or by using one of Cloudinary's SDKs that wrap the REST API and greatly simplify the implementation. You also have the option to upload the resources directly to Cloudinary (bypassing your servers) with unsigned uploads.

    The following simple example shows the single line of code needed to upload an image from the remote URL https://www.example.com/mysample.jpg, and set its public_id (identifier) as sample_woman using any of our server-side SDKs or the REST API:

    Ruby:
    Copy to clipboard
    Cloudinary::Uploader.upload("https://www.example.com/mysample.jpg",
      :public_id => "sample_woman")
    PHP:
    Copy to clipboard
    \Cloudinary\Uploader::upload("https://www.example.com/mysample.jpg", 
      array("public_id" => "sample_woman"));
    Python:
    Copy to clipboard
    cloudinary.uploader.upload("https://www.example.com/mysample.jpg", 
      public_id = "sample_woman")
    Node.js:
    Copy to clipboard
    cloudinary.v2.uploader.upload("https://www.example.com/mysample.jpg",
      { public_id: "sample_woman" }, 
      function(error, result) {console.log(result); });
    Java:
    Copy to clipboard
    cloudinary.uploader().upload(new File("https://www.example.com/mysample.jpg"),
      ObjectUtils.asMap("public_id", "sample_woman"));
    .Net:
    Copy to clipboard
    var uploadParams = new ImageUploadParams(){
      File = new FileDescription(@"https://www.example.com/mysample.jpg"),
      PublicId = "sample_woman"};
    var uploadResult = cloudinary.Upload(uploadParams);
    cURL:
    Copy to clipboard
    curl https://api.cloudinary.com/v1_1/demo/image/upload -X POST --data 'file=https://www.example.com/mysample.jpg&public_id=sample_woman&timestamp=12345678&api_key=98765432&signature=a123456f987664af'
  • Upload widget - Enable your users to upload images, videos or other files from their device or from their social media or media storage accounts via a self-contained, interactive user interface that can be easily embedded within your web application. The widget requires just a couple lines of javascript code to integrate into your app and can be optionally implemented with unsigned upload, enabling you to offer it as an exclusively front-end upload solution and eliminates the need to develop in-house interactive media upload capabilities.


    Upload widget

  • Auto Upload - Lazily migrate your existing assets to your Cloudinary account based on dynamic URL mapping. Your assets are dynamically retrieved the first time the URL is accessed and stored in your Cloudinary account.

Tip
If you just want to upload assets to your account manually so that they are available for delivery, you can also drag-and-drop from your file system to the relevant folder in the Media Library, or open the Media Library Upload widget to upload media files from any source. For details, see Media Library upload options.

Upload preferences

You can specify a wide range of parameters for customizing how a file will be uploaded including:

  • Whether asset names will match the uploaded filename or include random characters
  • What resource data should be extracted/stored/tagged with the asset
  • Analysis or manipulations to perform on the uploaded asset
  • Incoming or on-demand transformations to perform as part of the upload
  • Whether to send status updates to a notification URL

    And much more...

Check out the full list of available upload parameters.

You can set these preferences either by specifying them as parameters directly in your upload command or by specifying a pre-defined upload preset.

Upload presets enable you to centrally define a set of upload preferences instead of specifying them in each upload call. You can define multiple upload presets and then apply different presets in different upload scenarios. You can also assign the presets that should be used by default for API or Media Library uploads.

You can create and manage upload presets as well as set your account's default upload presets from the Upload page of the Cloudinary console. You can also create and manage upload presets programmatically using the upload_presets method of the Admin API. New accounts come with a default Media Library upload preset already configured.

For more information on upload presets, see Upload presets.

Migration

Cloudinary offers various methods for migrating your existing resources to your Cloudinary account:

  • Explicit migration: A one time migration based on the upload method of the Upload API for migrating all existing resources in one phase.
  • Lazy migration: Migrate resources on demand from a remote location using Auto Upload, where migration is carried out only when the resource is requested by a visitor.
  • Bulk migration code (Rails only): Complete, automatic and exhaustive migration of images from your production environment to your Cloudinary account with the Cloudinary migration tool.

4. Transform and deliver assets

Questions you'll answer in this section

  • What kinds of automatic effects and adjustments might you want to apply to your delivered media?
  • Which advanced transformation options might be relevant for the features I need?
  • Should I apply optimization functionality to all my delivered assets?
  • How does Cloudinary help me automate responsive image delivery?
  • How can I improve SEO via my media assets?

Upload an original image or video once and use Cloudinary to generate different versions from the original, on-the-fly or in advance, enabling you to deliver optimized and responsive media via leading CDNs that perfectly fits your graphic design across every device and resolution.

Image and video transformations

By adding transformation parameters to an image or video URL (usually via SDK functions), you can apply a huge variety of automatic adjustments and effects to your delivered media.

Learn how to apply image transformations

For example, after uploading the following 'sample_woman' image:

Original woman (scaled down)

Using on-the-fly transformation parameters directly in the image URL, you could deliver the image with the following changes automatically applied:

  • Generate a 200x200px square thumbnail of the largest face in the image (w_200,h_200,c_thumb,g_face).
  • Round the corners with a radius of 20 pixels (r_20).
  • Add a 5 pixel wide black border (bo_5px_solid_black).
  • Add the cloudinary_icon image as an overlay, scaled to 25% of the width of the main image, placed 10 pixels away (vertically and horizontally) from the northeast corner, and with 50% opacity (l_cloudinary_icon,o_50,w_0.25,fl_relative,g_north_east,y_10,x_10).
  • Deliver as a PNG to enable transparency around the rounded corners.

Transformed image

And this is what the URL and corresponding SDK delivery code looks like for those transformations:

Ruby:
Copy to clipboard
cl_image_tag("sample_woman.png", :transformation=>[
  {:width=>200, :height=>200, :gravity=>"face", :crop=>"thumb"},
  {:radius=>20, :border=>"5px_solid_black"},
  {:overlay=>"cloudinary_icon", :opacity=>50, :width=>0.25, :flags=>"relative", :gravity=>"north_east", :y=>10, :x=>10}
  ])
PHP:
Copy to clipboard
cl_image_tag("sample_woman.png", array("transformation"=>array(
  array("width"=>200, "height"=>200, "gravity"=>"face", "crop"=>"thumb"),
  array("radius"=>20, "border"=>"5px_solid_black"),
  array("overlay"=>"cloudinary_icon", "opacity"=>50, "width"=>"0.25", "flags"=>"relative", "gravity"=>"north_east", "y"=>10, "x"=>10)
  )))
Python:
Copy to clipboard
CloudinaryImage("sample_woman.png").image(transformation=[
  {'width': 200, 'height': 200, 'gravity': "face", 'crop': "thumb"},
  {'radius': 20, 'border': "5px_solid_black"},
  {'overlay': "cloudinary_icon", 'opacity': 50, 'width': "0.25", 'flags': "relative", 'gravity': "north_east", 'y': 10, 'x': 10}
  ])
Node.js:
Copy to clipboard
cloudinary.image("sample_woman.png", {transformation: [
  {width: 200, height: 200, gravity: "face", crop: "thumb"},
  {radius: 20, border: "5px_solid_black"},
  {overlay: "cloudinary_icon", opacity: 50, width: "0.25", flags: "relative", gravity: "north_east", y: 10, x: 10}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(200).height(200).gravity("face").crop("thumb").chain()
  .radius(20).border("5px_solid_black").chain()
  .overlay(new Layer().publicId("cloudinary_icon")).opacity(50).width(0.25).flags("relative").gravity("north_east").y(10).x(10)).imageTag("sample_woman.png");
JS:
Copy to clipboard
cloudinary.imageTag('sample_woman.png', {transformation: [
  {width: 200, height: 200, gravity: "face", crop: "thumb"},
  {radius: 20, border: "5px_solid_black"},
  {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), opacity: 50, width: "0.25", flags: "relative", gravity: "north_east", y: 10, x: 10}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("sample_woman.png", {transformation: [
  {width: 200, height: 200, gravity: "face", crop: "thumb"},
  {radius: 20, border: "5px_solid_black"},
  {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), opacity: 50, width: "0.25", flags: "relative", gravity: "north_east", y: 10, x: 10}
  ]})
React:
Copy to clipboard
<Image publicId="sample_woman.png" >
  <Transformation width="200" height="200" gravity="face" crop="thumb" />
  <Transformation radius="20" border="5px_solid_black" />
  <Transformation overlay="cloudinary_icon" opacity="50" width="0.25" flags="relative" gravity="north_east" y="10" x="10" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="sample_woman.png" >
  <cld-transformation width="200" height="200" gravity="face" crop="thumb" />
  <cld-transformation radius="20" border="5px_solid_black" />
  <cld-transformation overlay="cloudinary_icon" opacity="50" width="0.25" flags="relative" gravity="north_east" y="10" x="10" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="sample_woman.png" >
  <cl-transformation width="200" height="200" gravity="face" crop="thumb">
  </cl-transformation>
  <cl-transformation radius="20" border="5px_solid_black">
  </cl-transformation>
  <cl-transformation overlay="cloudinary_icon" opacity="50" width="0.25" flags="relative" gravity="north_east" y="10" x="10">
  </cl-transformation>
</cl-image>
.Net:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(200).Height(200).Gravity("face").Crop("thumb").Chain()
  .Radius(20).Border("5px_solid_black").Chain()
  .Overlay(new Layer().PublicId("cloudinary_icon")).Opacity(50).Width(0.25).Flags("relative").Gravity("north_east").Y(10).X(10)).BuildImageTag("sample_woman.png")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(200).height(200).gravity("face").crop("thumb").chain()
  .radius(20).border("5px_solid_black").chain()
  .overlay(new Layer().publicId("cloudinary_icon")).opacity(50).width(0.25).flags("relative").gravity("north_east").y(10).x(10)).generate("sample_woman.png");
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(200).setHeight(200).setGravity("face").setCrop("thumb").chain()
  .setRadius(20).setBorder("5px_solid_black").chain()
  .setOverlay("cloudinary_icon").setOpacity(50).setWidth(0.25).setFlags("relative").setGravity("north_east").setY(10).setX(10)).generate("sample_woman.png")!, cloudinary: cloudinary)

One of the great things about these transformations, is that once you've chosen the transformation combination that answers your needs, you can reliably apply and deliver any image with the same transformations. For example, here's the same automatically generated face thumbnail for an image of a business man (who was posing in front of the capitol building in the originally uploaded photo):

Ruby:
Copy to clipboard
cl_image_tag("business_man.png", :transformation=>[
  {:width=>200, :height=>200, :gravity=>"face", :crop=>"thumb"},
  {:radius=>20, :border=>"5px_solid_black"},
  {:overlay=>"cloudinary_icon", :opacity=>50, :width=>0.25, :flags=>"relative", :gravity=>"north_east", :y=>10, :x=>10}
  ])
PHP:
Copy to clipboard
cl_image_tag("business_man.png", array("transformation"=>array(
  array("width"=>200, "height"=>200, "gravity"=>"face", "crop"=>"thumb"),
  array("radius"=>20, "border"=>"5px_solid_black"),
  array("overlay"=>"cloudinary_icon", "opacity"=>50, "width"=>"0.25", "flags"=>"relative", "gravity"=>"north_east", "y"=>10, "x"=>10)
  )))
Python:
Copy to clipboard
CloudinaryImage("business_man.png").image(transformation=[
  {'width': 200, 'height': 200, 'gravity': "face", 'crop': "thumb"},
  {'radius': 20, 'border': "5px_solid_black"},
  {'overlay': "cloudinary_icon", 'opacity': 50, 'width': "0.25", 'flags': "relative", 'gravity': "north_east", 'y': 10, 'x': 10}
  ])
Node.js:
Copy to clipboard
cloudinary.image("business_man.png", {transformation: [
  {width: 200, height: 200, gravity: "face", crop: "thumb"},
  {radius: 20, border: "5px_solid_black"},
  {overlay: "cloudinary_icon", opacity: 50, width: "0.25", flags: "relative", gravity: "north_east", y: 10, x: 10}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .width(200).height(200).gravity("face").crop("thumb").chain()
  .radius(20).border("5px_solid_black").chain()
  .overlay(new Layer().publicId("cloudinary_icon")).opacity(50).width(0.25).flags("relative").gravity("north_east").y(10).x(10)).imageTag("business_man.png");
JS:
Copy to clipboard
cloudinary.imageTag('business_man.png', {transformation: [
  {width: 200, height: 200, gravity: "face", crop: "thumb"},
  {radius: 20, border: "5px_solid_black"},
  {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), opacity: 50, width: "0.25", flags: "relative", gravity: "north_east", y: 10, x: 10}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.image("business_man.png", {transformation: [
  {width: 200, height: 200, gravity: "face", crop: "thumb"},
  {radius: 20, border: "5px_solid_black"},
  {overlay: new cloudinary.Layer().publicId("cloudinary_icon"), opacity: 50, width: "0.25", flags: "relative", gravity: "north_east", y: 10, x: 10}
  ]})
React:
Copy to clipboard
<Image publicId="business_man.png" >
  <Transformation width="200" height="200" gravity="face" crop="thumb" />
  <Transformation radius="20" border="5px_solid_black" />
  <Transformation overlay="cloudinary_icon" opacity="50" width="0.25" flags="relative" gravity="north_east" y="10" x="10" />
</Image>
Vue.js:
Copy to clipboard
<cld-image publicId="business_man.png" >
  <cld-transformation width="200" height="200" gravity="face" crop="thumb" />
  <cld-transformation radius="20" border="5px_solid_black" />
  <cld-transformation overlay="cloudinary_icon" opacity="50" width="0.25" flags="relative" gravity="north_east" y="10" x="10" />
</cld-image>
Angular:
Copy to clipboard
<cl-image public-id="business_man.png" >
  <cl-transformation width="200" height="200" gravity="face" crop="thumb">
  </cl-transformation>
  <cl-transformation radius="20" border="5px_solid_black">
  </cl-transformation>
  <cl-transformation overlay="cloudinary_icon" opacity="50" width="0.25" flags="relative" gravity="north_east" y="10" x="10">
  </cl-transformation>
</cl-image>
.Net:
Copy to clipboard
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(200).Height(200).Gravity("face").Crop("thumb").Chain()
  .Radius(20).Border("5px_solid_black").Chain()
  .Overlay(new Layer().PublicId("cloudinary_icon")).Opacity(50).Width(0.25).Flags("relative").Gravity("north_east").Y(10).X(10)).BuildImageTag("business_man.png")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .width(200).height(200).gravity("face").crop("thumb").chain()
  .radius(20).border("5px_solid_black").chain()
  .overlay(new Layer().publicId("cloudinary_icon")).opacity(50).width(0.25).flags("relative").gravity("north_east").y(10).x(10)).generate("business_man.png");
iOS:
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(200).setHeight(200).setGravity("face").setCrop("thumb").chain()
  .setRadius(20).setBorder("5px_solid_black").chain()
  .setOverlay("cloudinary_icon").setOpacity(50).setWidth(0.25).setFlags("relative").setGravity("north_east").setY(10).setX(10)).generate("business_man.png")!, cloudinary: cloudinary)
Transformed image with the same transformations

Learn how to apply video transformations

The same concepts apply for video transformations. This time we'll:

  • Scale the portrait video to a height of 320 pixels (h_320,c_scale).
  • Pad the video with a blurred version of the same video to generate a 480 * 320 landscape video (c_pad,h_320,w_480,b_blurred:400:15).
  • Remove the audio from (mutes) the video (e_volume:mute).
  • Double the video speed (e_accelerate:100).

Ruby:
Copy to clipboard
cl_video_tag("cld_rubiks_guy", :transformation=>[
  {:height=>320, :crop=>"scale"},
  {:height=>320, :width=>480, :background=>"blurred:400:15", :crop=>"pad"},
  {:effect=>"volume:mute"},
  {:effect=>"accelerate:100"}
  ])
PHP:
Copy to clipboard
cl_video_tag("cld_rubiks_guy", array("transformation"=>array(
  array("height"=>320, "crop"=>"scale"),
  array("height"=>320, "width"=>480, "background"=>"blurred:400:15", "crop"=>"pad"),
  array("effect"=>"volume:mute"),
  array("effect"=>"accelerate:100")
  )))
Python:
Copy to clipboard
CloudinaryVideo("cld_rubiks_guy").video(transformation=[
  {'height': 320, 'crop': "scale"},
  {'height': 320, 'width': 480, 'background': "blurred:400:15", 'crop': "pad"},
  {'effect': "volume:mute"},
  {'effect': "accelerate:100"}
  ])
Node.js:
Copy to clipboard
cloudinary.video("cld_rubiks_guy", {transformation: [
  {height: 320, crop: "scale"},
  {height: 320, width: 480, background: "blurred:400:15", crop: "pad"},
  {effect: "volume:mute"},
  {effect: "accelerate:100"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .height(320).crop("scale").chain()
  .height(320).width(480).background("blurred:400:15").crop("pad").chain()
  .effect("volume:mute").chain()
  .effect("accelerate:100")).videoTag("cld_rubiks_guy");
JS:
Copy to clipboard
cloudinary.videoTag('cld_rubiks_guy', {transformation: [
  {height: 320, crop: "scale"},
  {height: 320, width: 480, background: "blurred:400:15", crop: "pad"},
  {effect: "volume:mute"},
  {effect: "accelerate:100"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.video("cld_rubiks_guy", {transformation: [
  {height: 320, crop: "scale"},
  {height: 320, width: 480, background: "blurred:400:15", crop: "pad"},
  {effect: "volume:mute"},
  {effect: "accelerate:100"}
  ]})
React:
Copy to clipboard
<Video publicId="cld_rubiks_guy" >
  <Transformation height="320" crop="scale" />
  <Transformation height="320" width="480" background="blurred:400:15" crop="pad" />
  <Transformation effect="volume:mute" />
  <Transformation effect="accelerate:100" />
</Video>
Vue.js:
Copy to clipboard
<cld-video publicId="cld_rubiks_guy" >
  <cld-transformation height="320" crop="scale" />
  <cld-transformation height="320" width="480" background="blurred:400:15" crop="pad" />
  <cld-transformation effect="volume:mute" />
  <cld-transformation effect="accelerate:100" />
</cld-video>
Angular:
Copy to clipboard
<cl-video public-id="cld_rubiks_guy" >
  <cl-transformation height="320" crop="scale">
  </cl-transformation>
  <cl-transformation height="320" width="480" background="blurred:400:15" crop="pad">
  </cl-transformation>
  <cl-transformation effect="volume:mute">
  </cl-transformation>
  <cl-transformation effect="accelerate:100">
  </cl-transformation>
</cl-video>
.Net:
Copy to clipboard
cloudinary.Api.UrlVideoUp.Transform(new Transformation()
  .Height(320).Crop("scale").Chain()
  .Height(320).Width(480).Background("blurred:400:15").Crop("pad").Chain()
  .Effect("volume:mute").Chain()
  .Effect("accelerate:100")).BuildVideoTag("cld_rubiks_guy")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .height(320).crop("scale").chain()
  .height(320).width(480).background("blurred:400:15").crop("pad").chain()
  .effect("volume:mute").chain()
  .effect("accelerate:100")).resourceType("video").generate("cld_rubiks_guy.mp4");
iOS:
Copy to clipboard
cloudinary.createUrl().setResourceType("video").setTransformation(CLDTransformation()
  .setHeight(320).setCrop("scale").chain()
  .setHeight(320).setWidth(480).setBackground("blurred:400:15").setCrop("pad").chain()
  .setEffect("volume:mute").chain()
  .setEffect("accelerate:100")).generate("cld_rubiks_guy.mp4")


For the complete list of transformations parameters available, see:

Note
Your account's pricing plan is in part dependent on the total number of "transformations" performed during a billing cycle. For details on how transformations are counted, see Transformation counts.

Optimization and delivery

Cloudinary leverages multiple CDNs, including Akamai, the leading CDN provider, with thousands of global delivery servers. Together with Cloudinary's advanced caching techniques and dynamic URL-based asset delivery, your media assets are efficiently delivered to your users all around the world.

Image and video optimizations

Deliver your assets with the smallest possible file size while maintaining visual quality, saving bandwidth and improving performance for your website. For images, Cloudinary automatically implements certain image optimizations by default. Additionally, for both images and videos, Cloudinary offers many other features for optimizing the resources you deliver to your users, for example:

  • Automatic gravity (g_auto) for images or videos instructs Cloudinary to resize and adjust your asset to fill the required dimensions while including the main subject.
  • Automatic format selection (f_auto) for images or videos instructs Cloudinary to deliver your asset to each user in the optimal format for the requesting browser.
  • Automatic quality selection (q_auto) for images or videos instructs Cloudinary's intelligent quality and encoding algorithm to apply the optimal quality compression level and encoding settings based on the specific content, format, and the requesting browser, in order to generate and deliver the asset with good visual quality while minimizing the file size.

The example shown on the left below applies all 3 of the above optimizations when delivering a cropped portrait video. The original (landscape orientation) 'frisbee_dog' video is shown on the right for comparison.

Ruby:
Copy to clipboard
cl_video_tag("frisbee_dog", :transformation=>[
  {:height=>250, :width=>150, :gravity=>"auto", :crop=>"fill"},
  {:quality=>"auto"}
  ])
PHP:
Copy to clipboard
cl_video_tag("frisbee_dog", array("transformation"=>array(
  array("height"=>250, "width"=>150, "gravity"=>"auto", "crop"=>"fill"),
  array("quality"=>"auto")
  )))
Python:
Copy to clipboard
CloudinaryVideo("frisbee_dog").video(transformation=[
  {'height': 250, 'width': 150, 'gravity': "auto", 'crop': "fill"},
  {'quality': "auto"}
  ])
Node.js:
Copy to clipboard
cloudinary.video("frisbee_dog", {transformation: [
  {height: 250, width: 150, gravity: "auto", crop: "fill"},
  {quality: "auto"}
  ]})
Java:
Copy to clipboard
cloudinary.url().transformation(new Transformation()
  .height(250).width(150).gravity("auto").crop("fill").chain()
  .quality("auto")).videoTag("frisbee_dog");
JS:
Copy to clipboard
cloudinary.videoTag('frisbee_dog', {transformation: [
  {height: 250, width: 150, gravity: "auto", crop: "fill"},
  {quality: "auto"}
  ]}).toHtml();
jQuery:
Copy to clipboard
$.cloudinary.video("frisbee_dog", {transformation: [
  {height: 250, width: 150, gravity: "auto", crop: "fill"},
  {quality: "auto"}
  ]})
React:
Copy to clipboard
<Video publicId="frisbee_dog" >
  <Transformation height="250" width="150" gravity="auto" crop="fill" />
  <Transformation quality="auto" />
</Video>
Vue.js:
Copy to clipboard
<cld-video publicId="frisbee_dog" >
  <cld-transformation height="250" width="150" gravity="auto" crop="fill" />
  <cld-transformation quality="auto" />
</cld-video>
Angular:
Copy to clipboard
<cl-video public-id="frisbee_dog" >
  <cl-transformation height="250" width="150" gravity="auto" crop="fill">
  </cl-transformation>
  <cl-transformation quality="auto">
  </cl-transformation>
</cl-video>
.Net:
Copy to clipboard
cloudinary.Api.UrlVideoUp.Transform(new Transformation()
  .Height(250).Width(150).Gravity("auto").Crop("fill").Chain()
  .Quality("auto")).BuildVideoTag("frisbee_dog")
Android:
Copy to clipboard
MediaManager.get().url().transformation(new Transformation()
  .height(250).width(150).gravity("auto").crop("fill").chain()
  .quality("auto")).resourceType("video").generate("frisbee_dog.mp4");
iOS:
Copy to clipboard
cloudinary.createUrl().setResourceType("video").setTransformation(CLDTransformation()
  .setHeight(250).setWidth(150).setGravity("auto").setCrop("fill").chain()
  .setQuality("auto")).generate("frisbee_dog.mp4")

Responsive images

Upload a single high resolution image and let Cloudinary automatically transform it to perfectly fit any HiDPI device and Retina display, at any pixel density (DPR). Cloudinary supports responsive images using smart, on-the-fly resizing and cropping based on your visitor specific web layout, and also provides various solutions for automatically implementing responsive images on your website. Cloudinary also offers comprehensive options for delivering responsive image options on native android and iOS mobile apps.

Even more transformation and delivery options

You may also want to take advantage of:

  • Eager transformations: Create derived transformations for images and videos during the upload process and before publishing to visitors. All transformed resources will be available before your users request them for the first time.
  • Incoming transformations: Transform original images and videos during the upload process and then store them as original resources.
  • Named transformations: Define named transformations through the Management Console. This is useful when you have relatively long or complex transformations, or multiple transformations that are commonly used.
  • Conditional transformations: Apply transformations if a specified condition is met. The condition is based on specific image characteristics. Especially useful for delivering user generated content, and allows treating different images with different transformation criteria using a single transformation sequence.
  • User-defined variables: Enable you to create
  • Advanced URL delivery options: Cloudinary offers a range of advanced URL delivery options including:
    media access control, fetch and deliver remote images with transformations, asset versions, private CDNs and CNAMEs, SEO friendly URLs, multi-CDN solutions and more.

5. Next steps

Congratulations! You've taken the first steps to integrating Cloudinary capabilities into your app and you've answered many of the essential questions needed to make the most of Cloudinary.

At this point, you may also want to:

Learn more

  • Learn how to programmatically manage your assets using Admin API (rate-limited) and Upload API (non-rate-limited) methods.
  • Further enhance your media upload and delivery with Cloudinary's add-ons.
  • Enjoy Cloudinary's media capabilities from directly within leading platforms.

Sign up for a course at Cloudinary Academy

Cloudinary Academy

 

Check out Cloudinary Academy, where you can take free self-paced courses or register for instructor-led virtual or on-site courses.

You may want to start with one or both of the following free courses:

(You must be signed in to your Cloudinary account to register for these courses.)

Stay on top of What's New

Once you've got the hang of using Cloudinary, you'll probably want to know when new features, integrations, SDKs, and add-ons are available. Bookmark the Cloudinary Documentation Home page, where you can always see a list of the latest additions and jump straight into the docs for how to use them.

Documentation Home page What's New

Follow and impact the Cloudinary Roadmap

We invite you to take a look at what's coming, what we are thinking about, and suggest your own ideas on the Cloudinary Roadmap. You can even vote on the planned or considered Roadmap items, indicating what's nice-to-have, what's important and what you see as critical.

Cloudinary Roadmap

✔️ Feedback sent!