Developer solution overview

Introduction

Cloudinary is a Software-as-a-Service (SaaS) solution for managing all your web or mobile application’s media assets in the cloud. Cloudinary offers an end-to-end solution for all your image and video needs, including upload, storage, administration, manipulation and delivery. Media upload, processing, and delivery are done on Cloudinary’s servers and automatically scale for handling high load and bursts of traffic.

The Cloudinary solution

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:
RubyPHPPythonNode.jsJavaAll
Ruby:
Cloudinary::Uploader.upload("http://www.example.com/sample.jpg",
  :public_id => "sample_woman")
PHP:
\Cloudinary\Uploader::upload("http://www.example.com/sample.jpg", 
  array("public_id" => "sample_woman"));
Python:
cloudinary.uploader.upload("http://www.example.com/sample.jpg", 
  public_id = "sample_woman")
Node.js:
cloudinary.v2.uploader.upload("http://www.example.com/sample.jpg",
  { public_id: "sample_woman" }, 
  function(error, result) {console.log(result) });
Java:
cloudinary.uploader().upload(new File("http://www.example.com/sample.jpg"),
  ObjectUtils.asMap("public_id", "sample_woman"));
  • Deliver the sample_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.

URLRubyPHPPythonNode.jsJavajQuery.NetAll
URL:
http://res.cloudinary.com/demo/image/upload/w_400,h_350,c_crop,g_face/r_20,bo_5px_solid_black/l_cloudinary_icon,o_50,w_0.25,fl_relative,g_north_east,y_10,x_10/q_auto,f_auto/sample_woman.jpg
Ruby:
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}
  ])
PHP:
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")
  )))
Python:
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"}
  ])
Node.js:
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"}
  ]})
Java:
cloudinary.url().transformation(new Transformation()
  .width(400).height(350).gravity("face").crop("crop").chain()
  .radius(20).border("5px_solid_black").chain()
  .overlay("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")
jQuery:
$.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"}
  ]})
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(400).Height(350).Gravity("face").Crop("crop").Chain()
  .Radius(20).Border("5px_solid_black").Chain()
  .Overlay("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")
Image scaled down to a width of 400 pixels with rounded corners and a green border

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.

About this overview

The information contained in this overview is meant to give developers an overall picture on the Cloudinary solution, initial setup and configuration, and where to find more detailed information on the service's functionality, framework integration options, and the various features. This overview is divided into the following sections:

Architecture and concepts

Cloudinary is a software–as-a-service (SaaS) solution for managing all your web application’s resources in the cloud. The resources are delivered from high-performance servers through Content Delivery Networks. Resources uploaded to Cloudinary and all generated resources are safely stored and managed by Cloudinary. Cloudinary's resource management solution includes:

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

Resources are stored in S3 buckets that are privately accessed for writing. We can use shared buckets, dedicated buckets or private buckets.

Service architecture

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.

cloud architecture

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.
  • Media library: Browse and search through your resources, moderate your images, upload new resources, organize and tag your resources, generate transformations, and much 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. http://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"

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.
  • 'http://res.cloudinary.com/demo/' - is the base URL for Cloudinary's shared CDN Distribution (all Plans).
  • 'http://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:

http://res.cloudinary.com/demo/image/upload/sample.jpg
example dynamic URL

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

<img src="http://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.

Note: Resources refers to any file type. Any file that is not an image, audio or video file is treated as a 'raw' file: these files are stored as-is when uploaded to Cloudinary. No transformations on raw files are currently available, although you can access raw files through a CDN URL in the same way as you access original images and videos.

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. Unsigned upload
  • 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:

Storage

Resources uploaded to Cloudinary and all generated resources are safely stored and managed by Cloudinary on high-performance servers that supports fast upload and download rates. Cloud-based storage solutions such as Amazon’s Simple Storage Service (S3) are leveraged for resource management and resources are stored in S3 buckets that are privately accessed for writing. We can use shared buckets, dedicated buckets or private buckets.

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 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:

Administration

Cloudinary's 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 management pipeline.

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. For more detailed information on a specific framework SDK:

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