Cloudinary Blog

RESTful API for Image Management for Your Website's Images and Other Online Assets

Image Management - REST API for Website Image Management
Different online services, websites and mobile applications have very different image management requirements. Despite the differences, the image management pipeline boils down to the same basic formula - upload the images, normalize them, store them and transform them to create derivatives (thumbnails, effects, watermarks, etc.). Afterwards, prepare them for delivery and make sure they are accessible to your users quickly and efficiently when browsing your website or using your mobile app.
 
When we set out to build Cloudinary, we envisioned a platform that could streamline an online service's entire asset management pipeline needs. We developed a simple yet powerful URL based API and made integration even simpler using client integration libraries for many web dev platforms and programming languages. It was a joy to see how each of our clients found new ways of utilizing our platform, hooking different API calls to solve scenarios we could barely imagine when Cloudinary was first conceived.
 
Sign up for Cloudinary free today!
 
In the regular flow of web applications, this works perfectly. But sometimes, you'll want even more fine grained control over your online assets - browse through user uploaded images, find specific images, delete images, delete transformations and more. If you already tried Cloudinary, you probably know that you can use our Management Console for manually achieving such tasks via our web-based user interface. But as many of our customers told us and frequently requested, more control is sometimes required than what they can currently achieve manually.
 
Today, we've made another important step in making the Cloudinary platform even more customizable. 
 
Without further ado, we'd like to welcome Cloudinary's powerful new administrative API, an intuitive RESTful HTTP API for programmatically managing all of your Cloudinary hosted assets.
 

Supported Operations

When building the API, we did our best to cover all common management tasks:
  • Listing all uploaded images and raw files.
  • Receiving details and metadata for uploaded images, including timestamps, format, dimensions, etc.
  • Listing the derived images of uploaded images.
  • Finding all images that share a given tag.
  • Listing all transformations.
  • Listing tags.
  • Receiving transformation details.
  • Creating named transformations.
  • Updating an existing transformation.
  • Deleting images, raw files, derived images and transformations.
 

API Overview

The API is accessed using HTTPS to endpoints in the following format:
 
https://api.cloudinary.com/v1_1/:cloud_name/:action
 
For example, resource listing of the 'demo' account:
 
https://api.cloudinary.com/v1_1/demo/resources/images
 
Authentication is done using Basic Authentication over secure HTTP. Your Cloudinary API Key and API Secret are used for the authentication.
 
Request parameters are appended to the URL. The response is in a simple JSON snippet. Like any REST API, read-only requests are sent in HTTP GET while write requests are sent in PUT, POST and DELETE. 
 
For more details, check out our documentation page.
 
Our client libraries provide an easy to use wrapper for this URL-based API, utilizing your native programming language of choice. Request building and authentication are done automatically, and the JSON response is parsed and returned. 
 

Usage Examples

 
The following Ruby example lists all your Cloudinary hosted images:
Copy to clipboard
$ result = Cloudinary::Api.resources
=> {"resources"=>
  [{"public_id"=>"sample1", 
    "format"=>"png",
    "version"=>1349196740, 
    "resource_type"=>"image", 
    "type"=>"upload",
    "created_at"=>"2012-10-02T16:52:20Z",
    "bytes"=>71376, "width"=>261, "height"=>253,
    "url"=>
     "https://res.cloudinary.com/sam/image/upload/v1349196740/sample1.png",
    "secure_url"=>
     "https://d3jpl91pxevbkh.cloudfront.net/sam/image/upload/v1349196740/sample1.png"},
   {"public_id"=>"sample2", 
    "format"=>"png",
    "version"=>1349196732, 
    "resource_type"=>"image", 
    "type"=>"upload",
    "created_at"=>"2012-10-02T16:52:12Z",
    "bytes"=>133171, "width"=>278, "height"=>432,
    "url"=>
     "https://res.cloudinary.com/sam/image/upload/v1349196732/sample2.png",
    "secure_url"=>
     "https://d3jpl91pxevbkh.cloudfront.net/sam/image/upload/v1349196732/sample2.png"},
 
    ... 
],
 "next_cursor"=>"e39ef944e18cfda7deafa4aea96791e7"}
Here's the same example in PHP:
Copy to clipboard
require "cloudinary.php" ;
require "api.php" ;
$api = new \Cloudinary\Api();
$result = $api->resources();
Python:
Copy to clipboard
import cloudinary.api
result = cloudinary.api.resources()
And Node.js:
Copy to clipboard
var cloudinary = require('cloudinary');  
cloudinary.api.resources(function(result)  { console.log(result) });
By default, 10 results are returned in a single request. You can specify the max_results parameter if you want more results in a single request. You can use this in conjunction with the next_cursor parameter for paginating through all your assets.
 
The next example shows how to get the full details of a single uploaded image, including the list of its derived images:
Copy to clipboard
$ result = Cloudinary::Api.resource("sample1")
=> {"public_id"=>"sample1",
 "format"=>"png",
 "version"=>1349196740,
 "resource_type"=>"image",
 "type"=>"upload",
 "created_at"=>"2012-10-02T16:52:20Z",
 "bytes"=>71376, "width"=>261, "height"=>253,
 "url"=>
  "https://res.cloudinary.com/sam/image/upload/v1349196740/sample1.png",
 "secure_url"=>
  "https://d3jpl91pxevbkh.cloudfront.net/sam/image/upload/v1349196740/sample1.png",
 "next_cursor"=>"f329da74de2a9ac9cbf99d2a6bc147b8",
 "derived"=>
  [{"transformation"=>"c_fill,h_50,r_20,w_70",
    "format"=>"png",
    "bytes"=>7313,
    "id"=>"a3b44a715c63f7ee91f11fb20b97c5df",
    "url"=>
     "https://.../sam/image/upload/c_fill,h_50,r_20,w_70/v1349196740/sample1.png",
    "secure_url"=>
     "https://.../sam/image/upload/c_fill,h_50,r_20,w_70/v1349196740/sample1.png"},
   {"transformation"=>"c_fill,h_75,w_75/jpg",
    "format"=>"jpg",
    "bytes"=>2889,
    "id"=>"7c0ca85b966b928179ce336fa2a7d1f8",
    "url"=>
     "https://.../sam/image/upload/c_fill,h_75,w_75/v1349196740/sample1.jpg",
    "secure_url"=>
    "https://.../sam/image/upload/c_fill,h_75,w_75/v1349196740/sample1.jpg"}]}
And now, the same example in PHP
Copy to clipboard
$result = $api->resource("sample1");
Python:
Copy to clipboard
cloudinary.api.resource("sample1")
And Node.js:
Copy to clipboard
cloudinary.api.resource("sample1", function(result)  { console.log(result) })
One final example - getting the details of a single transformation, including a list of all images assigned to this transformation:
Copy to clipboard
$ result = Cloudinary::Api.transformation("c_fill,h_75,w_75/jpg")
 
=> {"name"=>"c_fill,h_75,w_75/jpg",
       "allowed_for_strict"=>false,
       "used"=>true,
        "info"=>[{"width"=>75, "height"=>75, "format"=>"jpg", "crop"=>"fill"}],
        "derived"=>
  [{"public_id"=>"sample1",
    "resource_type"=>"image",
    "type"=>"upload",
    "format"=>"jpg",
    "url"=>
     "https://.../sam/image/upload/c_fill,h_75,w_75/v1349196740/sample1.jpg",
    "secure_url"=>
     "https://.../sam/image/upload/c_fill,h_75,w_75/sample1/sample1.jpg",
    "bytes"=>2889,
    "id"=>"7c0ca85b966b928179ce336fa2a7d1f8"},
  ...
]}
As you can see, the new API is quite powerful. Using this API allows for full control of all uploaded raw files and images, fetched social profile pictures, generated transformations and more. 
 
For more examples and a full reference, see our detailed documentation.
 

Usage Limits 

You can use the new API quite extensively. We ask for that you keep your ongoing API requests to 500 per hour (12,000 daily) when using our Free plan. Subscribe to Cloudinary's Basic plan onward to increase the limit to 2000 calls per hour. If you require more flexible limits, don't hesitate to contact us.
 
For each API call, standard HTTP headers are returned with details on your current usage statistics, including your per-hour limit, remaining number of actions and the time the hourly count will be reset.
 
Here is how these headers might look like:
 
    X-FeatureRateLimit-Limit: 500
    X-FeatureRateLimit-Remaining: 499
    X-FeatureRateLimit-Reset: Wed, 03 Oct 2012 08:00:00 GMT
 
Note that our client libraries provide easy access to the returned limit headers. In Ruby for example:
Copy to clipboard
$ result = Cloudinary::Api.resource_types
 => {"resource_types"=>["image"]} 
$ result.rate_limit_allowed
 => 500 
$ result.rate_limit_reset_at
 => 2012-10-03 10:00:00 +0200 
$ result.rate_limit_remaining
 => 499  
 

Summary 

The new admin API is available for all our free and paid plans. It would be great if you try it out, and tell us what you think. 
We have interesting ideas on how to further enhance this new API. If your want to be in the loop, go ahead and subscribe to our blog or Like Cloudinary on Facebook, and receive our timely updates.

Recent Blog Posts

Create Lightweight Sites With Low-Code and No-Code Technology

Consumers expect modern websites to be mainly visual. But, the more compelling and complex the related media is, the more data is involved, compounding the site’s weight. In today’s content-craving world, delivering unoptimized media can cost you because it leads to sluggish page loads, resulting in visitors abandoning your site in search of a faster alternative. In fact, a page load that takes more than three seconds can cause as many as 40% of your visitors to bounce. Given this competitive, digital-first environment, you can’t afford to lose page views, for time is of the essence.

Read more
A Blueprint for AWS-Secured Webhook Listeners for Cloudinary

tl;dr: An AWS-secured and optimized Cloudinary webhook listener for extending the Cloudinary service

Code: Github

A webhook is a communication medium for sending notifications from one platform to another about events that occurred. In place are user-defined HTTP callbacks that are triggered by specific events. When a triggered event takes place on the source site, the webhook listens to the event, collects the data, and sends it to the URL you specified in the form of an HTTP request.

Read more
New Accessibility Features for Cloudinary’s Product Gallery Widget

Cloudinary’s Product Gallery widget, which launched in 2019, has enabled many brands to effectively and efficiently showcase their products in a sleek and captivating manner, saving countless hours of development time and accelerating release cycles. By adding Cloudinary’s Product Gallery widget with its customizable UI to their product page, retailers reap numerous benefits, often turning visitors into customers in short order.

Read more
Why Successful Businesses Engage With and Convert Audiences With Visual Media

Most business buyers prefer to research purchase options online, as do many shoppers. No wonder online retail sales in the U.S. rose by 32.4% in 2020—an impressive gain of $105 billion.

For B2B and B2C businesses, text-heavy websites are no longer adequate in attracting shoppers. Instead, engaging visual media—spin images, videos, 3D models, augmented reality—are becoming a must for conveying eye-catching details and differentiators about products or services.

Read more
Making User-Generated Content (UGC) Shoppable With Cloudinary

User-generated content (UGC) is a powerful marketing tool. Not only does video complement marketing efforts for e-commerce by enabling customers to explore products in greater detail, but UGC also adds an element of trust. As a bonus, user-generated video is an exceptional opportunity for e-businesses to attract website traffic without their marketing team having to create promotional videos from scratch. User-generated content drives conversions and brand loyalty as a direct result of authentic interaction.

Read more