Service overview

Before you dive into the details of Cloudinary's many asset management features and begin adding Cloudinary code to your application, we recommend that you review this page to gain a high-level understanding about the service architecture, asset storage, security, and other details about how the Cloudinary service works.

See also
How to integrate Cloudinary in your app walks you through the steps involved, and the questions you may need to consider at each step, in order to successfully integrate Cloudinary into your application code, from initial account creation and setup and through to delivering transformed and optimized media in production.

On this page:

Service architecture

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.

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

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 the Transformation URL API Reference.

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 (2FA) via the Cloudinary Management Console User settings.

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.

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

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. The full URLs of the images or videos you deliver include various parts including the name of the asset, its version and transformation settings. However, all your delivery URLs use the same base URLs. 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/' - the base URL for accessing Cloudinary's secure API.
  • 'https://res.cloudinary.com/demo/' - the base URL for Cloudinary's shared CDN Distribution (all Plans).
  • 'https://demo-res.cloudinary.com/' - the base URL for a private CDN Distribution (Advanced Plan and above only).

Building full URLs for accessing your assets 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:

Copy to clipboard
https://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:

Copy to clipboard
<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.

Management console

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.

Add-ons

You can enhance your images and videos 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 example, Cloudinary offers add-ons that apply auto-tagging, automated asset moderation or anti-malware protection, AI, deep-learning and other analysis algorithms, face detection or recognition, or a variety of special transformation capabilities.

Nearly all add-ons offer a free tier that you can try regardless of your plan. For details on all available add-ons, see Cloudinary Add-ons.

Transformation counts

Your account's monthly pricing plan is in part dependent on the total number of transformations performed during a 30-day cycle. Transformation counts are impacted by each processing of an asset. The majority of these occur when Cloudinary generates a new 'derived' resource from an asset based on a transformation URL (regardless of the complexity of the transformation).

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 (and counted) when the transformation URL is requested for delivery for the first time.

Your pricing plan is also impacted by storage and bandwidth usage, not covered here.

Transformation counting basics

  • Upload processing: The upload of each image and video asset (with or without an incoming transformation) counts as one transformation.

    If you re-upload (overwrite) an asset with the same public ID in the future, that upload is again counted as a transformation.

    Stored raw assets impact your storage quota, but are not counted as transformations.

  • Transformation complexity: The count for a single transformation URL is not impacted by the number of transformation parameters in the URL, or the number of transformation components if chained transformations are applied.
  • Multiple requests: Since transformations are counted when a new derived resource is generated, multiple requests to the identical transformation URL do not affect transformation counts.

    This includes URLs using Dynamic SEO suffixes, which are resolved on the CDN layer and thus do not increase transformation counts, even if multiple SEO suffixes are delivered with the same transformation URL.

Based on the above, most images that you deliver result in one transformation for the initial asset upload, and one transformation per image transformation URL delivered (or eagerly generated).

Multiple transformation counts

The following features or operations are counted as multiple transformations:

Feature Count guideline Notes and calculation details
Video and audio Initial upload of a video counts as a single transformation regardless of its size.

The transformation count for each derived video resource is calculated based on its generated resolution and its duration.
  • Derived SD videos (less than or equal to 921,600 total pixels, e.g., 1280 x 720): 2 transformations per second.
  • Derived HD video: (more than 921,600 total pixels, regardless of the exact dimensions): 4 transformations per second.
  • Adaptive streaming videos: When generating a video transformation for delivery using adaptive bitrate streaming (HLS or MPEG-DASH), several representations of the same video are generated, and are all counted towards your transformation counts as per the SD and HD guidelines above.

    Example: If you use the full_hd streaming profile, you generate one representation that falls into the HD category, and 5 representations that fall into the SD category.

    If you request a 10 minute (600 second) video using this profile, the total transformation count for the derived adaptive streaming resources for that video would be 8400:

    • 600 * 5 SD representations * 2 transformations per second = 6000
    • 600 * 1 HD * 4 transformations per second = 2400
  • Audio files: 1 transformation per 10 seconds
Multi-page/frame image files Since transformations applied to animated images, and other files with multiple frames or 'pages', such as TIFF, PDFs, or Photoshop images with layers, are in essence applied to each page or frame, Cloudinary provides a special calculation for these. 1 transformation for the complete derived image, plus:

  • PDFs, TIFFs, PSDs, or other 'paged' files: An additional transformation for every 10 pages.
  • Animated images: An additional transformation for every 10 frames.
  • Animated images converted to video: An additional transformation for every five frames.
'Auto' transformations Some auto transformation parameters have the potential to generate multiple derived resources, depending on the browser, device, or viewing size being used when the URL is requested. Each time a new derived resource is generated, it counts as another transformation.
  • Auto format delivers images and videos in the optimal format for the requesting browser, so if a transformation URL including f_auto is requested on different types of browsers, that same URL may result in multiple derived assets in different formats. Example: Depending on the browsers and devices requesting a URL, that single URL might result in four derived images in different formats: webp, animated webp, wdp, and a standard (jpg or png) image format.
  • Auto DPR automatically delivers an image using the best DPR for the requesting device. So the single URL may, for example, result in two derived images, one using dpr_1, and one using dpr_2.
  • Auto Width automatically resizes the image to match the width available for the image in the responsive layout. When you use this parameter, the number of potential derived images depends on the screen or viewport size of the requesting devices and the breakpoints you set. Using this parameter might sometimes result in only two or three different derived images, or in other cases, may result in 20 or more images.
URL changes If two (or more) transformations generate an identical result, but the URL is different in any way, a separate transformed (derived) resource is created (and counted) when each of those transformations is requested. Examples:
  • The transformations are in a different order (w_200,h_200 vs h_200,w_200)
  • You use a transformation that has no impact (for example, angle = 0)
  • The same file format is specified in different ways (for example, specifying f_jpg as a transformation parameter vs using the .jpg file extension).
Auto-upload Auto-upload is much like uploading any other file, except that the upload occurs 'lazily' when the URL is first requested.

Thus at the time of the first request, the initial upload counts as a single transformation.

If the auto-upload URL also includes transformations, a derived resource is generated in addition to the uploaded file, resulting in a second transformation.

 When you deliver a fetched or social media profile image, it also counts as one transformation (whether or not you apply transformation parameters in the delivery URL).

These delivery types are not considered uploads, and thus there are no additional upload transformation counts associated with these assets.
API operations that delete derived assets Certain Upload API and Admin API operations that change or replace the original asset result in all stored derived resources for that asset being deleted. This means that the next time a corresponding transformation URL is requested, a new derived resource is generated based on the updated asset. Methods that cause this behavior include: Upload, Explicit, Tags, Context, Update, Delete.
Media library operations that delete derived assets Certain changes to assets via the Media Library, delete any derived resources that specifically depend on those values, and new derived assets are generated when a transformation URL on that asset is requested. Example: Adding/modifying tags may result in regeneration of a conditional transformation with a text overlay that's based on a tag value.
Placeholder images Placeholder images are used when the requested base image doesn't exist. In that case, then if transformations are applied to the placeholder image, and the relevant derived image doesn't already exist, it is generated and counted as a transformation.
Console asset editor When you use the Asset Editor in the management console to experiment with transformations, a new derived resource is generated each time you refresh the preview.
Metadata extraction Metadata extraction (for example, use of the image_metadata parameter on an Upload or Explicit method call) is counted as a transformation.
AVIF format The transformation count for images converted to AVIF from other formats (Beta) is calculated as a total per billing cycle, rather than on a per transformation basis. It is based on the number of megapixels encoded during the billing cycle, in addition to the number of transformed assets. AVIF transformation count per billing cycle = number of AVIF assets created + (2 * total AVIF megapixels encoded)

Tips

  • When using add-ons that are triggered by transformation parameters, then an add-on unit is used in addition to the normal transformation count for the derived asset.
  • For additional information on how your overall account usage is calculated (including storage and bandwidth), see this KB article and the Cloudinary Pricing page.
  • You can set your email preferences to receive notifications regarding your account usage.

Additional resources

✔️ Feedback sent!

Rate this page: