Developer solution overview

Resources are uploaded, managed, and transformed using Cloudinary’s Management Console and easy to use APIs, and delivered from high-performance servers through Content Delivery Networks (CDNs). While you can use Cloudinary's APIs directly within your own custom code, it is simpler (and recommended) to use one of Cloudinary's client libraries (SDKs), which wrap the Cloudinary APIs and simplify integration with web sites and mobile applications.

Quick example

The following example shows the single line of code needed to upload an image to your Cloudinary account, and then the single line of code to deliver the image to your users (including on-the-fly transformations).

• Upload an image from the remote URL http://www.example.com/sample.jpg, and set its public_id (identifier) as sample_woman:

Cloudinary::Uploader.upload("http://www.example.com/sample.jpg",
  :public_id => "sample_woman")

\Cloudinary\Uploader::upload("http://www.example.com/sample.jpg", 
  array("public_id" => "sample_woman"));

cloudinary.uploader.upload("http://www.example.com/sample.jpg", 
  public_id = "sample_woman")

cloudinary.v2.uploader.upload("http://www.example.com/sample.jpg",
  { public_id: "sample_woman" }, 
  function(error, result) {console.log(result) });

cloudinary.uploader().upload(new File("http://www.example.com/sample.jpg"),
  ObjectUtils.asMap("public_id", "sample_woman"));

• Deliver the sample_woman image with the following on-the-fly transformations:
  • Cropped to to a width of 400 pixels and a height of 350 pixels and automatically focused on the largest face in the image.
  • Rounded corners with a radius of 20 pixels.
  • A 5 pixel wide black border.
  • The cloudinary_icon image added 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.
  • Automatic quality encoding for minimizing the file size while maintaining good visual quality.
  • Automatic image format selection based on the viewers browser: WebP to Chrome/Opera, JPEG-XR to Internet Explorer, and JPEG to all others.

cl_image_tag("sample_woman.jpg", :transformation=>[
  {:width=>400, :height=>350, :gravity=>"face", :crop=>"crop"},
  {:radius=>20, :border=>"5px_solid_black"},
  {:overlay=>"cloudinary_icon", :opacity=>50, :width=>0.25, :flags=>"relative", :gravity=>"north_east", :y=>10, :x=>10},
  {:quality=>"auto", :fetch_format=>:auto}
  ])

cl_image_tag("sample_woman.jpg", array("transformation"=>array(
  array("width"=>400, "height"=>350, "gravity"=>"face", "crop"=>"crop"),
  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),
  array("quality"=>"auto", "fetch_format"=>"auto")
  )))

CloudinaryImage("sample_woman.jpg").image(transformation=[
  {'width': 400, 'height': 350, 'gravity': "face", 'crop': "crop"},
  {'radius': 20, 'border': "5px_solid_black"},
  {'overlay': "cloudinary_icon", 'opacity': 50, 'width': 0.25, 'flags': "relative", 'gravity': "north_east", 'y': 10, 'x': 10},
  {'quality': "auto", 'fetch_format': "auto"}
  ])

cloudinary.image("sample_woman.jpg", {transformation: [
  {width: 400, height: 350, gravity: "face", crop: "crop"},
  {radius: 20, border: "5px_solid_black"},
  {overlay: "cloudinary_icon", opacity: 50, width: "0.25", flags: "relative", gravity: "north_east", y: 10, x: 10},
  {quality: "auto", fetch_format: "auto"}
  ]})

cloudinary.url().transformation(new Transformation()
  .width(400).height(350).gravity("face").crop("crop").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).chain()
  .quality("auto").fetchFormat("auto")).imageTag("sample_woman.jpg");

cloudinary.imageTag('sample_woman.jpg', {transformation: [
  {width: 400, height: 350, gravity: "face", crop: "crop"},
  {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},
  {quality: "auto", fetchFormat: "auto"}
  ]}).toHtml();

$.cloudinary.image("sample_woman.jpg", {transformation: [
  {width: 400, height: 350, gravity: "face", crop: "crop"},
  {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},
  {quality: "auto", fetch_format: "auto"}
  ]})

<Image publicId="sample_woman.jpg" >
  <Transformation width="400" height="350" gravity="face" crop="crop" />
  <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" />
  <Transformation quality="auto" fetchFormat="auto" />
</Image>

<cl-image public-id="sample_woman.jpg" >
  <cl-transformation width="400" height="350" gravity="face" crop="crop">
  </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-transformation quality="auto" fetch-format="auto">
  </cl-transformation>
</cl-image>

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(400).Height(350).Gravity("face").Crop("crop").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).Chain()
  .Quality("auto").FetchFormat("auto")).BuildImageTag("sample_woman.jpg")

MediaManager.get().url().transformation(new Transformation()
  .width(400).height(350).gravity("face").crop("crop").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).chain()
  .quality("auto").fetchFormat("auto")).generate("sample_woman.jpg");

imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(400).setHeight(350).setGravity("face").setCrop("crop").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).chain()
  .setQuality("auto").setFetchFormat("auto")).generate("sample_woman.jpg")!, cloudinary: cloudinary)

Key benefits for developers

The Cloudinary solution offers many features and benefits for managing your resources in the cloud. Some of the main benefits to developers are:

• Eliminate media related R&D work from your IT and DevOps departments, and reduce your costs by up to 90%.
• Use one-liners for easy integration within your development framework.
• Cutting edge image manipulation features.
• Decrease the time to market of new products.
• Cloud based media library and APIs for upload, delivery and administration.
• Improved user experience: your site looks great and loads fast on any device.

Architecture and concepts

Cloudinary is a software–as-a-service (SaaS) solution for managing all your web or mobile application’s media assets in the cloud. The media assets are delivered from high-performance servers through Content Delivery Networks. Assets uploaded to Cloudinary and all generated assets are safely stored and managed by Cloudinary.

Cloudinary's media asset management solution includes:

• High performance servers behind Elastic Load Balancers that support fast upload and download rates.
• Highly available storage that promises that your assets are always available and safe.
• High performance media processing servers for generating your requested images and videos.

By default, resources are stored in Amazon S3 buckets that are privately accessed for writing. These can be shared buckets, dedicated buckets or private buckets.

Service architecture

Delivery lifecycle

The resource delivery lifecycle consists of 5 stages: Upload, Storage, Administration, Manipulation, and Delivery.

Once the original resource has been uploaded to your Cloudinary account, you can administer the resource via secured APIs or the Management Console, and embed dynamic resource URLs in your web page to deliver various versions of the original resource. The dynamic URLs include instructions on how to manipulate (or transform) the resource before delivery.

The first time a transformed resource is requested via a dynamic delivery URL:

1. The resource is requested by the user's browser.
2. The resource request reaches the closest CDN edge server.
3. The CDN edge servers checks if the resource is cached - it is not.
4. The CDN edge server requests the resource from Cloudinary.
5. Cloudinary generates the transformed resource as per the dynamic URL instructions.
6. Cloudinary returns the resource to the CDN edge server.
7. The CDN edge server caches the image and then returns the image to the user's browser.

Subsequent requests for the transformed resource via the same dynamic delivery URL:

1. The resource is requested by the user's browser.
2. The resource request reaches the closest CDN edge server.
3. The CDN edge servers checks if the resource is cached - it is.
4. The CDN edge server returns the image to the user's browser.

For a complete reference of possible transformations see Image transformations and Video transformations.

Scaling

Cloudinary’s architecture was built from the ground up to support high load and handle a practically unlimited amount of resources and usage. Cloudinary’s service includes a multitude of powerful cloud-based upload and transformation servers, with each server optimized to handle a very high rate of uploads, downloads, and complex image transformations. Cloudinary’s servers also automatically scale to easily manage large traffic peaks with advanced load balancers that are used to distribute the load between all our servers. Finally, an enterprise-grade content delivery network delivers resources quickly and efficiently through thousands of global delivery servers.

Security

Cloudinary's secure and safe cloud-based solution is accessible via secure and authenticated HTTPS APIs, with flexible access key provisioning. Cloudinary's security features include:

• Automatic backup of resources to a secondary protected location.
• Complete resource access control.
• Restricted access to resources based on specific transformations, file types and referral sites via the Cloudinary Management Console Security settings.
• Authenticated image access with signed URLs.
• Access control with multiple user roles and permissions, leveraging two-factor authentication via the Cloudinary Management Console User settings.

HTTP and HTTPS access

Uploaded public and private images are accessible via HTTP and HTTPS URLs and your web application can use either standard HTTP communication or secured HTTPS communication for uploading and transforming resources. Delivering resources using both kinds of communication methods can be done through the high-performance CDN. Note that if you are using our SDKs, we automatically detect whether the visited page is delivered using HTTP or HTTPS and dynamically build the correct resource URLs.

APIs

Cloudinary offers 3 different APIs for uploading, administering and delivering your resources as follows:

• Upload API - methods for uploading resources, creating new resources such as text images, ZIP files and sprites, and manipulating existing resources.
• Admin API - A secure API with methods for browsing, deleting, and restoring existing resources, and for managing upload presets, upload mappings, and transformations.
• URL API - a URL based API for delivering resources. Includes dynamic resource transformations, fetching remote images, and optimizing delivery of the resources. Resource URLs are dynamically mapped to CDN distributions that forward the requests to Cloudinary servers which generate the transformed resource on-demand and deliver them optimized to users.

Management console and media library

Cloudinary's web-based management console is used to administer your Cloudinary account. The console includes the following features:

• Dashboard: View details about your account and the usage status of resources, transformations, storage, bandwidth and add-ons.
  Watch the Dashboard intro video tutorial to learn more.
• Media library: Browse and search through your resources, moderate your images, upload new resources, organize and tag your resources, generate transformations, and much more.
  Watch the Media Library intro video tutorial to learn more.
• Transformations: Manage transformations created for your images (view, create, edit, delete) and enable/disable dynamic application of each transformation (with strict transformations enabled).
• Reports: Get insight on your resources with usage reports, in-depth analytics and advice.
• Add-ons: Manage Cloudinary's add-ons for your account.
• Settings: Manage your account, upload, security and user settings. These settings allow you to control and tweak almost every aspect of your resource pipeline's behavior.

Account and API setup

You can create a new Cloudinary account via the signup page. After filling in a few details, selecting a password and a cloud name, your account is created and available immediately. Logging in to your account will automatically direct you to the Cloudinary Management Console where you can manage your account settings.

Identifiers

In order to use Cloudinary services, unique cloud names and access identifiers are assigned to each of Cloudinary's customers.

Cloud name

The cloud name identifier is the name of your Cloudinary account, a unique public identifier for URL building and API access. This name is assigned to your account during signup (the field can be edited) and is listed in the Account Details section of the Cloudinary Management Console Dashboard. As your cloud name is used to build the public URL for all your resources (e.g. https://res.cloudinary.com/my_cloud_name/…), make sure you select an appropriate cloud name for your organization, site, or product.

After you create the cloud name it can be changed (in the Account tab of the Settings page) only if fewer than 50 resources have been uploaded to your account. If you need to change your cloud name and your account has more than 50 resources, you need to submit a support request. Note that changing your cloud name will invalidate all cached URLs and all previously derived resources.

If you use one of our SDKs, your cloud name needs to be configured for accessing Cloudinary from within your development framework. For example, if you’re using our Ruby GEM, and your cloud name is "demo", simply add the following content to your cloudinary.yml file (under ‘config/’ in Rails):

development: 
  cloud_name: "demo"

production:
  cloud_name: "demo"

Access identifiers

Accessing Cloudinary APIs for uploading and managing resources requires secure authentication that uses a standard method for signing API request parameters with your unique secret.

Cloudinary auto-generates a pair of access identifiers, the API Key and API Secret, that need to be used for communicating with Cloudinary's API and signing your requests. These identifiers are listed in the Account Details section of the Cloudinary Management Console Dashboard. You can manage your access keys on the Security tab of the Settings page (generate a new pair, activate and deactivate key pairs).

If you use one of our SDKs, the requests are automatically securely signed for you once the API Key and API Secret have been configured for accessing Cloudinary from within your development framework. For example, if you’re using our Ruby GEM, simply add the following content to your cloudinary.yml file (under ‘config/’ in Rails):

production:
  api_key: "YOUR_KEY"
  api_secret: "YOUR_SECRET"

Configuration parameters

In addition to the mandatory cloud_name identifier, and the api_key and api_secret that are mandatory for all server-side operations, there are also a number of optional parameters you may want to define. When using one of the Cloudinary SDKs, you can configure these parameters for each Cloudinary operation, or you can configure them globally.

The table below details all available configuration parameters (mandatory and optional).
For details and examples of where and how to define these configuration parameters, see the relevant Cloudinary SDK framework guide.

URLs and endpoints

The URLs for accessing Cloudinary are based on your cloud name, and you can access your public web resources using dynamic URLs. You can access them either in plain HTTP or secure HTTPS. The full URLs of resources (e.g., images) include various parts including the name of the resource, its version and transformation settings. However, all such URLs share the same base URLs: one for HTTP and one for HTTPS. You can view your base URLs and some sample URLs in the Account Details section in the Management Console.

The base URL will also include your cloud name. For example, if your cloud name is 'demo', the base URLs will be:

• 'api.cloudinary.com/v1_1/demo/' is the base URL for accessing Cloudinary's secure API.
• 'https://res.cloudinary.com/demo/' - is the base URL for Cloudinary's shared CDN Distribution (all Plans).
• 'https://demo-res.cloudinary.com/' - is the base URL for a private CDN Distribution (Advanced Plan and above only).

Building full URLs for accessing your resources is done automatically if you are using our SDKs. However, you can also build these URLs manually. For example, if your cloud name is 'demo' and you want to deliver the uploaded 'sample.jpg' file, simply point to:

This means that in your HTML code you can simply add the following tag:

<img src="https://res.cloudinary.com/demo/image/upload/sample.jpg" />

For more information and details on constructing dynamic URLs see Delivering images using dynamic URLs.

Features overview

The Cloudinary service offers a comprehensive feature set for managing your resources in the cloud, with an end-to-end solution for all your resource needs.

Upload

You can upload any file type, from almost any source, using a variety of upload options:

• Upload API - Upload resources by using the upload method of the Upload API.
• Auto Upload - Lazy automatic upload and on-demand resource manipulation, based on URL mapping. No need to upload all your resources in advance and you can lazily migrate your resources on demand.
• Fetch - Automatically fetch an image from anywhere on the Web, with on-the-fly manipulation and optimized delivery via a CDN.
• Direct uploading from the browser - Easily upload resources from the user's browser. You also have the option to upload the resources directly to Cloudinary (bypassing your servers) with unsigned uploads.
• Upload widget - Allows you to upload resources to cloudinary via a ready made interface that can be easily embedded within your web application.

Take note of the Upload Presets feature, which is an optional feature that allows you to centrally define the upload options instead of specifying them in each upload call. This feature is required for directly uploading resources from the browser to Cloudinary (bypassing your servers).

For the complete list of upload parameters available, see:

• Image upload reference
• Video upload reference

Storage

Resources uploaded to Cloudinary and all generated resources are safely stored and managed by Cloudinary on high-performance servers that support fast upload and download rates.

By default, Amazon’s Simple Storage Service (S3) is leveraged for resource management and resources are stored in S3 buckets that are privately accessed for writing. These can be shared buckets, dedicated buckets or private buckets.

Google Cloud Storage is also available for primary and/or backup storage. This is a premium feature that requires a special setup. For more information, contact customer support.

Manipulations and transformations

Upload an original image or video once and let Cloudinary generate different versions from the original, on-the-fly or in advance. You can manipulate your resources dynamically to perfectly fit your graphic design across every device and resolution. Resources are processed ultra fast in the cloud, with no local software installation or ongoing maintenance required. Cloudinary offers an extensive list of image and video transformations that can be classified as follows:

• Dynamic transformations - On demand (on-the-fly) image and video transformations via resource delivery URLs (AKA lazy), and delivered through a CDN.
• 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 for resources through the Management Console. 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.

For the complete list of transformations parameters available, see:

• Image transformation reference
• Video transformation reference

Transformation Counts

Your account's pricing plan is in part dependent on the total number of transformations used during a billing cycle. These are primarily counted when Cloudinary generates a new 'derived' resource from an asset based on a transformation URL (regardless of the complexity of the transformation).

As mentioned above, you may intentionally generate some 'derived' resources in advance using eager transformations so that they will be immediately available upon request. Otherwise, a derived resource is generated on-the-fly with the first request to the corresponding transformation URL.

Considerations

• Since transformations are only counted when a new derived resource is generated, multiple requests to the identical transformation URL do not affect transformation counts.
• The initial upload of each asset counts as one transformation.
• If two (or more) transformations generate an identical result, but the URL is different in any way - for example, the transformations are in a different order, or you use a transformation that has no impact (for example angle = 0), a separate transformed (derived) resource is created when each of those transformations is requested.
• If you perform an Upload API or Admin API operation that changes or replaces the original asset, then the stored derived resources for that asset are deleted. This means that the next time a corresponding transformation URL is requested, a new derived resource is generated based on the updated asset. A few examples of methods that cause this behavior include: Upload, Explicit, Tags, Context, Update, Delete
• Similarly, if you modify assets in the Media Library, such as renaming or adding/modifying tags or metadata, this also deletes any derived resources that depended on those values (such as a conditional transformation with a text overlay based on a tag value), and new ones will be generated when a transformation URL on that asset is requested.
• Using auto format (f_auto) can potentially result in multiple derived resources for a single transformation URL, depending on the browsers or devices that request the transformed asset.
• When you use the Media Library Edit UI in the management console to experiment with transformations, a new derived resource is generated each time you refresh the preview.
• Each derived resource for videos, animated images, and other files with multiple 'pages', such as TIFF, PDFs, or Photoshop images with layers, are counted as follows:
  • Animated images: 1 transformation plus an additional transformation for every 10 frames.
  • Animated images converted to video: Every 5 frames = 1 transformation.
  • Other 'paged' files: 1 transformation plus an additional transformation for every 10 pages.
  • SD Video: 1 second = 2 transformations
  • HD Video: 1 second = 4 transformations (Frame contains over 921,600 of total pixels, e.g., 1280 x 720)
• Metadata extraction (For example, use of the image_metadata parameter on an Upload or Explicit method call) is also counted as a transformation.

Image optimizations

Deliver your resources with the smallest possible file size while maintaining visual quality, saving bandwidth and improving performance for your website. Cloudinary automatically implements various image optimizations and offers many other features for optimizing the resources you deliver to your users.

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.

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 image delivery, your resources are efficiently delivered to your users all around the world.

Cloudinary also offers a range of advanced URL delivery options including:

• asset versions,
• private CDNs and CNAMEs,
• multiple sub-domains,
• SEO friendly URLs and
• image placeholders.

Administration

Cloudinary offers powerful tools for comprehensive administration your Cloudinary account:

• Web-based management console: Cloudinary's online web interface to interactively manage every aspect of your resource pipeline, from upload through to delivery. Configure your account settings, organize your resources, assign role-based access to all your team members, get important insights on your images with usage reports, plus much more. Also includes an interactive media library for browsing, tagging, transforming, moderating and managing your resources.
• Admin API: Automate all your image management and housekeeping with Cloudinary's RESTful API. This API offers a variety of methods for managing your resources, transformations, upload mappings, upload presets, and more.

Add-ons

Enhance your images even further with powerful functionality offered by our vision and image processing partners. The add-ons are simple to use and fully integrated into Cloudinary's image and video management pipeline.

For details on all available add-ons, see Cloudinary Add-ons.

Framework integration and migration

Cloudinary's client libraries (SDKs) take care of all your resource uploading and transformation URL building, and simplify the integration with your framework even further. They allow you to continue working in your preferred developer framework and provide helper methods to easily upload your resources, build image tags and image transformation URLs.

SDKs

Cloudinary offers a vast array of open source SDKs to easily implement Cloudinary's functionality in both your server and client side code. Cloudinary's SDK libraries wrap Cloudinary's 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.

SDKs are available for most popular programming languages include back-end, client-side, and mobile.

To learn more about the available SDKs, see the SDK guides.

Migration

Cloudinary offers various methods for uploading 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.

Additional resources

• Support Knowledge Base
• Blog
• Cookbook
• Facebook Community
• The Visual Web