Last updated: Sep-26-2023
This page is for developers who want to build integrations with Cloudinary. It outlines the information you need to develop your integration, including Cloudinary features and tools, and provides links with more details about each of these items.
Read about our Technology Partner Program, which offers you the opportunity to get your integration verified and listed on our website. Find out the benefits of joining the program as well as some program requirements and best practices.
Companies often use Cloudinary within a tech stack of platforms (PIMs, CMSs, e-commerce platforms, marketing apps, and more) that interact with one another. Integrations combine valuable capabilities of Cloudinary with another platform in your tech stack and leverage the power of both by enabling them to function seamlessly together. As such, integrations that connect Cloudinary with other platforms can increase efficiency, productivity, and agility in the way that work is done.
Advantages of building a Cloudinary integration include:
- Streamlining work that involves Cloudinary and another platform by eliminating the overhead of switching between them.
- Allowing Cloudinary users to benefit from Cloudinary features within the UI they are used to, without needing to change habits.
- Automating processes that take place behind the scenes.
Here's a general diagram showing the possible architecture of an integration with Cloudinary. The integration connects Cloudinary with another platform using tools, like SDKs and Webhooks. The flow between Cloudinary and the platform can be bi-directional, meaning an event in Cloudinary can trigger an action within the platform, and an event on the platform might trigger an action within Cloudinary.
Some examples of possible Cloudinary integrations include:
- Implementing single-click optimization and delivery.
- Enriching Cloudinary media with product information from another platform.
- Providing easy access to a DAM for users of a CMS.
Cloudinary partners, agencies (system developers or dev shops), or any developer can build an integration with Cloudinary. Cloudinary provides the tools to implement some of your app features so that you can focus on the big picture.
Think about how your integration will combine Cloudinary features with the platform you want to integrate to best serve the needs of your end users:
- Cloudinary features: Cloudinary offers a wide variety of features that you can leverage. Learn about those features and how they can benefit your end users.
- Platform: Find the gaps in your end users' native platform that Cloudinary can fill.
- End users: Get to know your end users. How do they use Cloudinary? What are the most popular features? How do they use the platform you want to integrate?
- Integration: Identify how you can streamline the way you use your platform with Cloudinary features, and develop a strategy to implement it.
Once you know exactly what you want your integration to be able to do, select the Cloudinary tools that will enable you to implement your integration.
You can use your integration internally to serve the needs of your own organization, and you can share your integration anywhere you want so more Cloudinary users can benefit from it.
If you want to reach an even wider audience, verify your integration and have it listed on our website. Learn more about the Cloudinary Technology Partner Program, including the benefits of joining and how to become a partner.
This section describes Cloudinary's products, the value that they bring to users, and how they can be incorporated into Cloudinary integrations.
Cloudinary's Digital Asset Management (DAM) solution offers asset storage along with a fully-featured set of DAM capabilities, including uploading from different sources, asset management, and tagging, via an intuitive UI. In addition, the DAM comes with AI-powered solutions such as image-recognition, as well as editing and transformation capabilities.
In addition to storing assets, Programmable Media provides access to all of Cloudinary's APIs and SDKs, enabling asset management, transformation and optimization, and delivery through our fast CDNs.
When you're creating an integration, you can use API calls and SDK helper methods to code user interface solutions. You can also use APIs and SDKs to implement workflows that take place behind the scenes.
Learning about Cloudinary is an essential step to building your integration. Before you get started on any development work:
- Sign up for a free Cloudinary demo account to get familiar with the Cloudinary product offerings.
- Access our free training site, Cloudinary Academy, as well as our Knowledge Base and Documentation sites.
Feel free to contact Cloudinary support with questions at any point during the integration building process.
This section highlights some important Cloudinary features that your integration can leverage. Your integration isn't limited to the functionalities presented here. Feel free to explore the wide range of available Cloudinary features and integrate those that you find on your own, as well.
Implementing these features within other platforms can maximize the benefits of using Cloudinary's service.
Asset optimization means delivering assets in the format, dimensions, resolution, and quality that will yield the smallest possible file size while ensuring that the resulting asset is appropriate for the specific content, the overall page design, the requesting device, and the expectations of your site visitors. Optimized delivery is achieved using optimization transformations such as f_auto, q_auto, and others.
Using Cloudinary's media optimization and delivery features, you can build an integration that allows single-click, automatic quality and format optimization for all delivered assets, with the additional benefit of delivering the assets stored on your end user's platform via Cloudinary's fast CDN.
Cloudinary transformations offer easy ways to transform, adapt, and optimize assets. Here are just a few examples from the large selection of transformation features that you can include in your integration:
- Use AI-driven decision making to apply transformations to assets in bulk in order to create different variations of all your asset for different channels and campaigns.
- Apply different text overlays to personalize and deliver assets appropriately to different audiences.
- Crop, resize, transcode, and filter assets on the fly to fit your brand's look and feel.
- Add creative transformations such as effects and watermarks.
- Use AI-powered detection capabilities to automatically moderate user generated content. For example, you can use transformations to pixelate faces or remove text such as license plate numbers detected by AI.
- Automatically resize assets while ensuring that the most interesting elements are not cropped out using the g_auto feature.
- Perform background removal on upload.
Here are some visual examples of transformations:
You can effectively use and manage Cloudinary features programmatically with the following APIs:
|Transformation URL API||Enables you to deliver media assets, including a large variety of on-the-fly transformations through the use of URL parameters.|
|Upload API||Enables you to upload your media assets and provides a wide range of functionality, including basic and advanced asset management, metadata management, and asset generation.|
|Admin API||Provides full control of all uploaded media assets, fetched social profile pictures, generated transformations and more.|
|Search API||Allows you fine control on filtering and retrieving information on all the assets in your product environment with the help of query expressions in a Lucene-like query language.|
|Structured Metadata API||Allows you to define typed fields for media assets, populate them with values programmatically or via the Media Library, and perform searches on them. You can also add validation rules, set default values, and define fields as mandatory.|
|Provisioning API||Allows you to create several product environments, users and user groups. (This API is available to users on a Plus plan or higher.)|
You can include some of Cloudinary's media management features in your integration, including managing your assets' metadata and syncing your platform media with Cloudinary.
You can build an integration that allows customers to sync all or some of the assets they use on a different platform to Cloudinary. You can save space by storing assets only on Cloudinary, or you can store assets on Cloudinary as well as on your native platform to provide back-up and fallback mechanisms.
While implementing sync functionality, you can use the created_at field in the asset response to determine the last time the asset changed, and whether it needs to be re-synced accordingly.
Learn more: WordPress plugin: storage sync options
Cloudinary provides some advanced features that provide an optimal viewing experience, and decrease the time needed to load a page.
Cloudinary's responsive breakpoints feature is a smart algorithm that determines the ideal image dimensions for a particular end user's device/browser. When
responsive breakpoints is used, images are automatically displayed at the appropriate size.
You might want to build an integration that enables responsive breakpoints to all assets by default.
Lazy loading saves bandwidth and decreases the time needed to load a page by telling the browser to only render images that are visible on the user's screen, waiting to load more images until the user scrolls to them.
In your integration, you can configure media delivered through your platform to use lazy loading.
An image placeholder is a lightweight version of a target image that can be downloaded quickly, and will occupy the same location as the intended target image while the target image is still downloading. This feature enables the page to load quickly without blank spaces, and without content 'jumping' as the elements dynamically adjust to add downloaded images.
In your integration, you can configure media delivered through your platform to initially appear as placeholders.
In this video, you can see all the different placeholder types combined with lazy loading:
Cloudinary allows the end user to dynamically add meaningful suffixes to asset URLs.
Integrate this capability to improve the SEO of the user's website.
Learn more: Dynamic SEO suffixes
This section contains a list of libraries, packages and apps we created to help you build your integration easily. Follow the links to find in-depth documentation about relevant topics.
SDKs can be used to perform any REST API call to Cloudinary using your preferred language.
Some common ways of using SDKs when developing an integration include:
- Upload media from your platform to Cloudinary.
- Manage asset tags and metadata.
- Get product environment data, such as requests, number of resources, add-on usage, etc., and present it so your end user can view it without leaving the native platform.
- Build sophisticated media URLs.
Learn more: SDK documentation
Cloudinary provides a set of transformations in the Transformations Gallery with a variety of different transformations ready for you to use. Use these to get ideas on how to leverage transformations to improve your end user visual experience.
Possible integrations you can create with the help of the Transformations Gallery:
- Automatically detect the position of the faces within an image and crop a thumbnail based on the detected face.
- Add on-the-fly moderation to protect your end user from uploading offensive user generated content to the platform.
- Easily add sale banners to selected product images in your end user e-commerce platform.
This is the gallery UI:
Learn more: Creating named transformations
You can set up one or more notification URLs where Cloudinary can send you updates, notifications and data relating to operations you perform. You'll receive a webhook notification after certain operations in your system have been performed.
You can use webhooks to trigger logic in your integration. If you receive a notification that a certain event took place, you can use it to trigger the next event in your workflow.
Adding multiple notification URLs enables you to specify which destination handles responses for each type of event. This level of control makes it easy to trigger flows or sync multiple parts of your ecosystem when integrating Cloudinary with other platforms.
Possible integrations you can create using webhooks:
- Listen for uploads in your end user's product environment to automatically moderate uploaded assets.
- Listen for metadata changes to automatically update product information in your end user's platform.
Learn more: Notifications
Widgets are GUI components that you can include in your integration to easily add functionality and provide your end user with a great visual experience.
Here are some ways that you can use widgets in your integration:
- Enhance the platform's shopping experience by displaying products via Cloudinary's Product Gallery.
- Enhance the platform's video experience by using Cloudinary's Video Player.
- Enable your end users to easily upload media to Cloudinary directly from their native platform using the Upload Widget.
- Enable your end users to manage their media using Cloudinary's Media Library from directly within their native platform.
- Configure widgets, or enable your end users to, using our studios' WYSIWYG editors.
- Replace generic components in your application with Cloudinary widgets.
You can also add event handling to your widgets to trigger custom behaviors in your application, or to track information such as analytics and usage.
Learn more: Widgets
Embed Cloudinary's Upload widget to allow the end users of your integration to upload assets from various sources to Cloudinary.
Use the Media Library widget to provide access to almost all of Cloudinary's DAM functionality from directly within another platform.
Embedding this widget enables end users to:
- Select media from Cloudinary and insert it into the platform.
- Upload, search, manage, and edit assets within the Media Library.
Embed Cloudinary's Media Editor widget to allow the end users of your integration to edit and transform original assets. This widget enables end users to resize and crop images, as well as add image and text overlays directly from your website or application.
Use the Product Gallery in your integration to display your end user's products in an efficient and visually attractive way.
Use the Video Player in your integration to customize and optimize the way videos are played.
Learn more: Video Player documentation
Cloudinary's studios are interactive demos that automatically generate code for embedding one of the widgets into your integration. The studios have UIs that display a preview of one of the widgets with default style and options. You can then use the studio UI options to customize the widget design. As you make your selections, both the preview and required code update automatically. When you finish customizing, copy the generated code and embed it into your integration.
In addition, you can enable your end users to access the studios themselves, allowing them to customize the widgets on their own. For example, end users can access the Video Player studio to customize how the Cloudinary Video Player looks and feels on their websites.
Click each of the links to play with the studios:
Build flexible media applications using no-code/low-code drag-and-drop tools. You can build an entire integration using MediaFlows or use it to build specific parts of your integration.
Possible integrations you can create using MediaFlows:
- Listen for uploads to automatically trigger asset moderation, tagging, alerts, and more.
- Periodically scan your platform media and sync it to Cloudinary to provide better delivery and optimization.
Learn more: MediaFlows
In order to give your integration a look and feel consistent with Cloudinary's GUI, you can incorporate Cloudinary brand assets, such as logos, color palettes, and fonts. Access those resources here.
The following sections call out some additional topics that might be important for you to consider when building your integration.
Consider how you want to authenticate the API requests made to Cloudinary by the end user of your integration. You can use either API key and secret, or OAuth tokens to authenticate those requests.
End users can find their API Environment variable in the developer console. This variable is a single string containing the API key, secret, and additional information required to perform the API calls. The end users of your integration can copy this variable and use it to authenticate API calls. The credentials in the environment variable are valid for use within SDKs, or in any REST request to Cloudinary's API.
If you want to keep credentials hidden from your end users, you can use OAuth tokens for authentication. To use OAuth tokens, please contact support for your OAuth client ID, secret, and redirect URLs.
Cloudinary customers may work with more than one product environment. For example, an agency may manage a production product environment, a staging product environment, a product environment for each sub-brand, etc.
In addition to having multiple product environments, an account can have multiple users. You can build an integration that allows switching between different product environments and users from within the logged-in account. This would streamline user access to media from multiple product environments.
When you build your integration, keep in mind that users have different permissions, so some users may not have access to certain Cloudinary features.
The Admin API is rate limited, so avoid using this for functionality that's going to be performed in high volume.
Different product environments may have different limits, for example maximum image or video size. You can see your own usage limits in the Console Settings. To programmatically find out user limits, you can call the Admin API usage method.
You can see actual code examples for integrations that we've already made:
The following diagram illustrates an example of an e-commerce integration with Cloudinary that you can build:
This integration enables both optimizing Cloudinary assets for delivery within the e-commerce platform, and automating upload from an e-commerce platform to Cloudinary:
Optimizing assets for delivery: When media metadata is updated in Cloudinary, a webhook is sent. This triggers the integration to update product media and metadata on the e-commerce platform. The updated media is then displayed on the platform via the Product Gallery Widget and the Video Player.
Automating upload to Cloudinary: When media is updated on the platform, the updated product media information gets passed to the integration. The integration then uses SDK methods to upload the updated media to Cloudinary.
Cloudinary applies AI to the newly uploaded media detecting colors, objects, faces, etc., and automatically assigns metadata to the newly uploaded media assets accordingly. This triggers a webhook which notifies the integration that new metadata has been applied, and the integration adds the new metadata to the product media on the platform, as well.
Ready to start building your integration?
Learn more about our partner-built integrations program, including guidelines, the review process, and the benefits of developing your own integration with Cloudinary.
Contact the Cloudinary Integration Team for more information about our verification process.