SDKs

Last updated: Dec-28-2022

On this page:

Cloudinary's Programmable Media SDK libraries wrap Programmable Media REST APIs and additionally include a variety of useful helper methods, enabling you to implement comprehensive image and video upload, transformation, optimization, and delivery capabilities in your application, using code that integrates seamlessly with your existing application code.

SDKs are available for most popular frontend, backend and mobile programming languages.

The SDK Guides, available from the links below, provide quick starts (start using Cloudinary in 5 minutes or less), as well as detailed information on setting up and using Cloudinary's Programmable Media solution with your selected SDK.

Note
These SDK guides are intended to help get you started with the SDK and provide introductory information on how to use the most common Cloudinary features with your chosen SDK. Additional documentation for all Cloudinary features as well as sample code demonstrating how to use specific features for each SDK, can be found in our Developer and DAM Guides.

Available SDKs

Backend

Ruby on Rails

Guide
Library
Quick start

Dart

Guide
Library
BETA

Frontend

jQuery

Guide
Library

Vue.js

Guide
Library

Mobile

iOS (Swift/ObjectiveC)

Guide
Library

Android

Guide
Library

Flutter

Guide
Library
BETA

Kotlin

Guide
Library

Community-developed libraries

We invite you to use and contribute to these community-developed framework integrations for Cloudinary:

   Gatsby Offers two Gatsby plugins that enable you to to fetch media assets from Cloudinary (gatsby-source-cloudinary) and upload images from file nodes to Cloudinary (gatsby-transformer-cloudinary) and then transform them to Cloudinary file nodes.
   Gridsome Offers plugins that enable you to fetch image assets from Cloudinary into Gridsome (gridsome-source-cloudinary) and to upload images to Cloudinary and apply transformations (gridsome-plugin-cloudinary). You can also use the generic gridsome-transformer-img to upload and load local images with Cloudinary as the loader.
   Laravel The cloudinary-laravel package enables you to upload, optimize, transform and deliver media files using Cloudinary. It also provides a fluent and expressive API to attach your media files to Eloquent models.
   Netlify Hooks in to your Netlify build process and sets up images for optimization and delivery. Install the plug-in on Netlify or contribute to the open-source library.
   Next.js This open-source library provides components to enable you to upload and apply popular Cloudinary transformation and optimization features to your media when building Next.js applications.
   NuxtJS Enables you to upload, optimize and transform images and videos in a Nuxt application with the @nuxtjs/cloudinary module.
   Storefront UI Offers Cloudinary components that enable you to enhance and optimize your media while building your front end in Vue or Nuxt.

Important

  • Community-developed libraries are developed, tested and maintained by the community. Bug fixes and feature requests should be submitted in the relevant repository.
  • Throughout this documentation site, unless otherwise specified, the term "SDKs" refers to official Cloudinary SDK libraries. That information may or may not be relevant or accurate for these community-developed framework integration libraries. For information on setup, configuration and usage of these libraries, refer to the relevant community documentation.

Configuration parameters

The first step in setting up any Cloudinary SDK is to set the global configuration parameters in the relevant configuration file (see the relevant SDK guide above for details on where and how to configure them for your SDK).

  • The cloud_name product environment identifier must be set for every SDK.
  • Your product environment api_key and api_secret are mandatory configurations for all backend SDKs.
    (The api_secret should never be exposed in client-side code.)
  • For all legacy SDKs, you'll probably want to set the secure parameter to true to ensure that your transformation URLs are always generated as HTTPS. (In SDK major versions with initial release in 2020 or later, this configuration parameter is true by default.)
  • There are also a number of additional optional configuration parameters you may want to define at a global level.

You can additionally set any of these configuration parameters in individual operations, which then overrides the globally set or default configuration values for that command.

The table below details all available Cloudinary SDK configuration parameters.
For details and examples of where and how to define these configuration parameters, see the relevant Cloudinary SDK framework guide.

Tip
In some SDK languages, you may need to adjust the case of the parameters shown below (for example to camelCase or kebab-case) to match the conventions of the language you are using.

Parameter Type Description
Cloud
cloud_name string Mandatory. The cloud name of your product environment. Used to build the public URL for all your media assets.
api_key string Mandatory for server-side operations. Used together with the API secret to communicate with the Cloudinary API and sign requests.
api_secret string Mandatory for server-side operations. Used together with the API key to communicate with the Cloudinary API and sign requests.
URL
secure Boolean Optional. Force HTTPS URLs for asset delivery even if they are embedded in non-secure HTTP pages.

When using this option with a custom domain name (CNAME), specify your CNAME using the secure_distribution parameter (and not the cname parameter).

Default:

  • false in legacy SDK versions
  • true in SDK major versions with initial release in 2020 or later.
private_cdn Boolean Optional. Set this parameter to true if you are an Advanced plan user with a private CDN distribution. Default: false.

For details, see Private CDNs and CNAMEs.
secure_distribution string Optional. The custom domain name (CNAME) to use for building HTTPS URLs. Use this option in conjunction with the secure=true option.

Relevant only for Advanced plan users that have a private CDN distribution and a custom CNAME. For details, see Private CDNs and CNAMEs.
cname string Optional. The custom domain name to use for building HTTP URLs. Use this option only if you do not set secure=true.

Relevant only for Advanced plan users that have a private CDN distribution and a custom CNAME. For details, see Private CDNs and CNAMEs.
cdn_subdomain Boolean Optional. Whether to automatically build URLs with multiple CDN sub-domains. In most cases, this is no longer necessary. Default: false.

For details, see Multiple sub-domains.
upload_prefix

(ApiBaseAddress in .NET)

 string Optional. Replaces the https://api.cloudinary.com part of the API endpoint with the string specified.

Relevant only for Enterprise plan users that are using an alternative data center, for example https://api-eu.cloudinary.com.
analytics Boolean Optional. When true, URLs generated by the SDK include an appended query parameter that passes SDK usage information. This data is used in aggregate form to help Cloudinary improve future SDK versions. No individual data is collected and this data cannot be used to identify end users in any way.

Note that if you have developed proprietary functionality that relies on asset delivery URL values (CDN-based functionality, other query parameters, local storage of asset delivery URLs, etc), the appended query param could impact that functionality.

Default: true.

Relevant only for new major SDK versions with initial release in 2020 or later.
Other
upload_preset string Optional. The name of a defined upload preset. You can create upload presets in the Upload page of the the Cloudinary Console Settings or using the upload_preset method of the Admin API. If you are planning to offer unsigned uploads, you can define an unsigned upload preset to use with all uploads. This is especially useful for frontend SDKs.
api_proxy 1 string Optional. The URL of a proxy server in your environment for routing all Cloudinary Admin API and Upload API method calls to Cloudinary.
signature_algorithm enum Optional. Sets the algorithm to use when the SDK generates a signature for API calls or URL generation. Possible values: sha1 (default), sha256.
Provisioning
provisioning_api_key string Mandatory for Provisioning API operations. Used together with the Provisioning API secret to communicate with the Cloudinary API and authenticate provisioning requests.
provisioning_api_secret string Mandatory for Provisioning API operations. Used together with the Provisioning API key to communicate with the Cloudinary API and authenticate provisioning requests.
account_id string Mandatory for Provisioning API operations. The ID of the Cloudinary product environment for provisioning.
Rails SDK only
static_image_support Boolean Relevant the Ruby/Rails SDK only. Optional. Whether to deliver uploaded static images through Cloudinary. Default: false.

For details, see Rails Static images.
enhance_image_tag Boolean Relevant for the Ruby/Rails SDK only. Optional. Whether to wrap the standard image_tag view helper's method. Default: false.

Set this parameter to true if static_image_support is set to true.
Python SDK only
disable_tcp_keep_alive Boolean Relevant for Python SDK only. Optional. If true disables TCP socket keep-alive. Default: false.

Footnote

  1. If you're using the Python SDK and setting your configuration parameters globally, you must set your configuration parameters before importing the cloudinary.uploader and cloudinary.api classes in order to set up a proxy server successfully.

SDKs with action-based syntax

SDK major versions with initial release in 2020 or later provide an intuitive coding experience for transforming an asset. Whereas the syntax for each SDK differs based on its programming language, the concept behind the syntax follows these principles:

  • The syntax is action-based, designed to make building delivery URLs and transformations more logical.
  • It allows discovering the available options from within your development environment, and ensures that only options that are supported can be used together.

The general form of the syntax is:

Transformation general syntax

An example being:

Transformation structure

The syntax is based on Actions, ActionGroups, and Qualifiers:

  • Assets expose methods called Action Groups (myImage.adjust()) that represent a directive to Cloudinary on how to transform a specific aspect of an asset
  • Action Groups receive an Action object as a parameter that defines the specific action to apply
  • Action objects are created through Factory methods (Adjust.replaceColor())
  • Some actions require a Qualifier as a parameter (lightblue)
  • Qualifiers usually accept a QualifierValue (17 in tolerance(17)).

Supported browsers (SDKs)

The most recent 5 versions of the following browsers are regularly tested with Cloudinary's SDKs and are officially supported:

Desktop

  • Google Chrome
  • Internet Explorer 11
  • Microsoft Edge
  • Mozilla Firefox
  • Safari

Mobile

  • Mobile Chrome
  • Mobile Firefox
  • Mobile Safari

Notes

  • Internet Explorer 10 and earlier is not supported.
  • Other browsers not mentioned above may work well, but have not been tested.
    If there is another popular browser that you think we should add to our browser support matrix, please submit a support request and we will evaluate it.

Important
Microsoft is ending support for Internet Explorer 11 from the 15th of June, 2022. From that date forward, Cloudinary's widgets and SDKs may also not function as expected on IE11, and we will no longer test or support that browser.

✔️ Feedback sent!

Rate this page: