Programmable Media service introduction

Before you dive into the details of Cloudinary's many asset management features and begin adding Cloudinary Programmable Media capabilities 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.

Service architecture

Cloudinary's media asset management service 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, Cloudinary stores assets in Amazon S3 buckets that are privately accessed for writing. The buckets might be shared buckets, dedicated buckets or private buckets.

Delivery lifecycle

The asset delivery lifecycle consists of 5 stages: Upload, Storage, Administration, Transformation, and Delivery.

Once you've uploaded the original asset to Cloudinary, you can manage the asset via secured APIs or the Cloudinary Console, and embed dynamic asset URLs in your web page to deliver various versions of the original asset. The dynamic URLs include instructions on how to transform the asset before delivery.

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

1. The user's browser requests the asset.
2. The asset request reaches the closest CDN edge server.
3. The CDN edge servers checks if the asset is cached - it's not.
4. The CDN edge server requests the asset from Cloudinary.
5. Cloudinary generates the transformed asset as per the dynamic URL instructions.
6. Cloudinary returns the asset 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 asset via the same dynamic delivery URL:

1. The user's browser requests the asset.
2. The asset request reaches the closest CDN edge server.
3. The CDN edge servers checks if the asset 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 the Transformation URL API Reference.

Scaling

Cloudinary's architecture supports high load and can handle a practically unlimited amount of assets 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 distribute the load between all our servers. Finally, an enterprise-grade content delivery network delivers assets 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 API key provisioning using the access_keys endpoint. Cloudinary's security features include:

• Automatic backup of assets to a secondary protected location.
• Complete asset access control.
• Restricted access to assets based on specific transformations, file types and referral sites via the Security page of the Console Settings.
• Authenticated image access with signed URLs.
• Access control with multiple user roles and permissions, leveraging two-factor authentication (2FA), 3rd-party service provider logins (such as Google or GitHub), or SSO. You can set these preferences via the Account Security page of the Cloudinary Console Settings.

Storage

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

By default, Cloudinary uses Amazon's Simple Storage Service (S3) for asset management and storage 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.

APIs

Cloudinary offers several Programmable Media APIs:

• Upload API - methods for uploading assets, creating new assets such as text images, ZIP files and sprites, and transforming existing assets.
• Admin API - A secure API with methods for browsing, deleting, and restoring existing assets, and for managing upload presets, upload mappings, and transformations. This API also includes the search method and metadata method.
• Provisioning API - A secure API that enables account administrators to create and manage their account, product environments, users and user groups programmatically.
• URL API - a URL-based API for delivering assets. Includes dynamic asset transformations, fetching remote assets, and optimizing delivery of the assets. Asset URLs are dynamically mapped to CDN distributions that forward the requests to Cloudinary servers which generate the transformed asset on-demand and deliver them optimized to users.

URLs and endpoints

You can access your public web assets 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.

The base URL also includes your cloud name. For example, if your cloud name is 'demo', your base URLs would 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 plans and higher only).

Cloudinary SDKs build the delivery URLs for you. 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:

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

API keys

If you're a user with a Master admin, Admin, or Technical admin role, you can find your API keys and other credentials on the API Keys page of the Cloudinary Console Settings:

These credentials include your:

• Cloud Name: The product environment identifier. Required for configuring front-end SDKs and included as an identifer in all media asset URLs delivered from Cloudinary.
• API Key and API Secret: Needed to configure backend SDKs or to directly run REST API requests.
• API environment variable: A string that combines all three credential values. Copy the API environment variable format from the API Keys page of the Cloudinary Console Settings. Replace<your_api_key> and <your_api_secret> with your actual values, while your cloud name is already correctly included in the format.

If you need only your cloud name, such as for configuring a frontend SDK, you can find that on the Dashboard.

Managing product environment API keys

You can manage your API keys in the API Keys page of the Console Settings, including adding, activating, disabling, and naming API keys.

You can also configure granular API key permissions for your API keys, so that you can give different developers access to specific Upload and Admin API methods, but not others. Customers on a paid plan can contact support to enable this feature.

Managing API keys with the Provisioning API

Enterprise accounts that have the Provisioning API enabled can use it to programmatically create and manage API keys using the access_keys endpoint and product environments using the subaccounts endpoint, as well as users and user groups. To use the Provisioning API, you need a dedicated API key. If your account includes support for the Provisioning API, you can find your Provisioning API Access credentials in the Account page of the Cloudinary Console Settings.

Granular API key permissions for Upload and Admin APIs

You may want to allow certain developers to run specific endpoints in the Admin and Upload APIs and their equivalent SDK methods, and deny them from running others. You can create multiple API keys on the API Keys page of the Cloudinary Console Settings, and then coordinate with a Cloudinary solutions engineer to customize the keys for your product environment, with each key allowing access to different endpoints or groups of endpoints. You can then assign each customized API key to different developers to control who can perform which programmatic actions in your product environment.

For example, you might want to allow certain developers to:

• Use only GET methods, i.e., read-only permissions.
• Use only the transformations, upload_presets and streaming_profiles endpoints, with both read and write capabilities.
• Use all endpoints except DELETE methods.

If a user makes a call to an endpoint that's restricted by the API key, you'll get an error message stating that the provided API key doesn't have permission to run the API call.

To set up granular permissions for your API keys:

1. Create all the API keys you want to customize from the API Keys page of the Cloudinary Console Settings.

2. Make a request to Cloudinary support to configure your permissions. When making your request, specify the API keys to update and the list of Upload API and Admin API endpoints you want to restrict for each one. For example, "Please restrict the : GET /streaming_profiles and POST /transformations/:name endpoints for the API key named: front-end-developers."

Limitations and considerations for API key permissions:

• Actions you restrict for the API are generally still allowed via the Media Library. For example, if the metadata field endpoint is restricted by the API key, the user can still access metadata via the Media Library.
• If you want to restrict permissions in the Media Library, you should assign them to a Media Library admin or Media Library user role, so that they won't have access to API key/secret pairs that aren't configured for them.
• You can restrict actions in the Upload API only for signed upload requests.
• If the API key status is disabled, then any requests made using that API key are automatically denied.

Embeddable widgets

Cloudinary provides a variety of tools that you can embed in your applications to provide additional functionality for your users with just a few lines of code.

Upload Widget

The Upload Widget is a responsive, interactive UI that enables your users to upload files from a variety of sources to your website or application. For example, they can upload from their local device, their device camera, or from social media accounts like Dropbox, Instagram, or Facebook. You can also customize the look and feel of the widget, configure special behaviors, or take advantage of the widget's extensive event handling to integrate your own code.

Full screen Responsive mode

Product Gallery

Cloudinary's Product Gallery is an interactive user interface for displaying your products to your users on your website or application. The Product Gallery requires only pure JavaScript to integrate, is easy to use within any web development framework, and eliminates the need to develop an in-house interactive media gallery with just a few lines of code.

Video Player

The Cloudinary Video Player is a JavaScript-based HTML5 video player bundled with many valuable customization and integration capabilities, and is monetization and analytics-ready. The player is fully responsive for use on any device or screen size and it's fully integrated with Cloudinary's video delivery and transformation solution.

Media Library Widget

In addition to Programmable Media widgets, you can seamlessly integrate the Media Library widget into your custom integrations. This allows you to embed a compact version of the Media Library within your CMS or any web application. Your employees or end users can effortlessly search for and select images, videos, PDFs, or other stored raw files directly from a Cloudinary product environment. Then, they can insert them in a way that precisely fits your application design, required behavior, and overall workflow.

Media Editor

Cloudinary's Media Editor is an interactive user interface providing a set of common image editing actions to your users on your website or application. The editor helps to scale internal operations by reducing dependency on designers for simple recurring tasks. Combined with AI for automating simple actions, this allows manual review / fixing of media assets when needed.

Cloudinary Console

As a developer, you'll probably do most of your Cloudinary work directly in your favorite IDE. But there are some things that you can only do and/or might sometimes be easier/faster to do in the Cloudinary Console UI.

You log into the Console using the GitHub, Google, 3rd party (aka Heroku) account, or the username and password you registered with. For more details, see Updating Console login details.

Most of what you'll see in the Cloudinary Console relates to the currently selected product environment.

What's a product environment?

A product environment (previously known as a sub-account) is an entity within your account that includes an asset repository, some product environment-specific settings, and other elements that are stored in your product environment and help you manage it, such as upload presets, named transformations, and more.

A product environment can represent a production or staging environment, different organizations, products, or geographic sites that you want to manage separately within a single Cloudinary account.

You can manage the elements related to a product environment via the Cloudinary Console or programmatically using the Admin API.

Console Options

The following options are available from the Console Options sidebar, located at the far left of the Console:

Option	Description
	Open the Product Explorer to learn about Cloudinary's product offerings, including descriptions, feature lists and insights into how each product can significantly enhance your workflow.
Product selector	Click the logo for the Cloudinary product you want to work with to display the navigation options for that product.
---
Invite new users	Add new users to your account. Learn more.
Help	Access a variety of resources to learn more about working with Cloudinary including documentation, get customer support, view the latest release notes for your active product, find training courses, read blog posts, and more.
Settings	Manage your personal profile, account-level settings, and product environment-level settings. These settings allow you to control and tweak almost every aspect of your asset pipeline behavior.
Profile avatar	Jump to your profile settings, invite friends to sign up for Cloudinary and earn extra credits, or log out of your account.

Programmable Media navigation options

When you select the Programmable Media product, the following options are available from the Product Navigation menu, divided into several collapsible sections:

Console settings

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

To access your settings, click the Settings icon at the bottom-left of the console.

View or update your cloud name

On the Product Environments page of the Console Settings, you can see the current Cloud Name that was automatically generated during registration.

This cloud name is a unique identifier of your product environment that's also used in many places, including in the delivery URL of every Cloudinary asset. This can be valuable for SEO, so it's a good idea for your cloud name to be a good representation of your organization, site, or app.

You can modify your cloud name as long as you haven't uploaded more than 1000 new assets in that product environment. Select Edit from the 3-dots (options) menu at the end of the product environment's row. Additionally, you can set or change your product environment Display Name, which serves as an optional descriptive name displayed in the product environment selector at the top left of the Cloudinary Console. If you don't define a display name, the selector shows the product environment's cloud name instead.

Check 'My Profile' settings

In the My Profile page of the Console Settings, you can check your personal email notification and login preferences, and setup two-factor authentication.

Updating Console login details

• If you're registered with a user name (email address) and password, you can modify your password at any time from the My Profile page of the Console Settings

• If you registered with Google, GitHub or another third-party login such as Heroku, you can additionally define a Cloudinary username and password in the My Profile page of the Console Settings to set up direct access to Cloudinary.

  You must do this to enable two-factor authentication (2FA), as 2FA only applies to username-password logins. For more information, see the Can I set a password if I signed up to Cloudinary with Google, GitHub or other third-parties? FAQ.

  Important

  If you signed up through a third-party login (e.g., Google, GitHub, or Heroku), changing your email associated with the third-party service without first setting up direct access to your Cloudinary account may prevent you from logging in. To avoid this, establish direct access to Cloudinary via the My Profile page of the Console Settings before changing your third-party email.

Check backup settings

You may want to check or modify the automatic backup settings in the Upload Settings & Backup page of the Console 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 back up any file currently in your product environment.

Check user settings

Add users to your account, manage your users, and assign each user a role to define the permissions they have to areas in the Cloudinary Console.

All accounts can have at least 3 users. You can upgrade your plan to increase the number of users you're allowed on your account. If you're already on a paid plan and want to add users over and above your plan's limit, you can separately purchase additional user subscriptions, so that whole teams of developers can work together on delivering assets from Cloudinary.

For details on multiple-user accounts, roles, and permissions, and more, see User settings.

Configure webhook notifications

In the Webhook Notifications page of the Console Settings, or via the triggers method of the Admin API, you can specify which URL(s) receive notifications after the completion of certain API method calls or Console UI operations. If you specify more than one notification URL, you can designate specific notification URLs to receive responses for certain operations and method calls, but not others.

For details about the different types of webhook notifications as well as sample responses, see Webhook Notifications.

Check Media Library preferences

To access Media Library preferences, make sure you've selected Digital Asset Management from the Product Selector at the top-left of the console. Then select the page you want in the Preferences section from the Product Navigation menu, located on the left side of the Console. Here's the Display page.

As a developer, you may want to consider the following Media Library preference options:

• Keep existing metadata when uploading newer versions of an asset: By default, overwriting an asset clears all tags, contextual, and structured metadata values for that asset. If you prefer to retain these values (unless the upload call passes different values for the tags, context, or metadata parameters), select this option from the Upload page. This option impacts both Media Library and programmatic uploads.

• Manage Structured Metadata: Structured metadata enables you to predefine a number of typed fields, with or without validation rules, as optional or required fields for every asset in your product environment, and ensure that values are consistent for all assets in your product environment. For example, if your application supports user-generated content, you can define structured metadata fields to capture and pass as part of your end-user uploads to keep track of things like the user who uploaded the asset, product categories, countries, or other important data.

  You can define structured metadata fields for your product environment in the Manage Structured Metadata UI by selecting Structured Metadata from the Product Navigation menu located on the left side of the Console.

  It's also possible to define these metadata fields programmatically using the Metadata API methods. Once you create metadata fields, you can set the field values programmatically using the metadata parameter of upload or explicit commands, the metadata method of the Upload API, or manually in the Media Explorer.

Transformation counts

Your account's monthly pricing plan is in part dependent on the total number of transformations performed during a 30-day cycle. Each processing of an asset impacts your transformation counts. For details, see How are transformations counted?.

Additional resources

• Support Knowledge Base
• Blog
• Cloudinary Academy
• Cloudinary Community
• Podcasts
• Demos
• Cloudinary Roadmap
• More resources