Developer onboarding guide

Cloudinary's Programmable Media solution enables you to programmatically add image and video upload, transformation, optimization, and delivery capabilities to your applications via easy-to-use REST APIs. Furthermore, Cloudinary offers a variety of SDK libraries that wrap the APIs, enabling you to seamlessly integrate Programmable Media functionality with your existing application code.

This page offers a high-level overview on the steps required to integrate Cloudinary within your application, with links to more detailed documentation.

Each step of the process involves making some decisions based on your existing code, your programming preferences, and your application requirements. Some of these questions are highlighted at the beginning of each step below.

1. Create your account and set up your product environment

Creating your account and setting up your product environment takes only a few minutes.

• Sign up via Google, Github or email and set up two-factor authentication
• Create and explore your account
• Optional. Update your cloud name and other settings

Sign up via Google, Github or email and set up two-factor authentication

If you don't have a Cloudinary account yet, you can sign up for a free account now.

You can sign up for Cloudinary using an email address, Google account or GitHub account. If you register with the email option, don't forget to look for the Welcome to Cloudinary email and click the verification link inside to set your account as active.

Once your account is activated, consider improving your account security policy. Two-factor authentication (2FA) is recommended for any Production product environment, or per your organization's security policy. You can upgrade to two-factor authentication on any account, including free accounts and those registered via Github, Google, or email.

SSO is available for enterprise accounts and is recommended if you have more than 100 users or per your organization's security policy.

In the Account Security page of the Console Settings, check or modify two-factor authentication (2FA) and SAML/SSO login settings for your account.

Create and explore your account

When you create an account, an initial product environment is also created. Depending on the plan you're on, you may be able to create multiple product environments (previously known as 'sub-accounts') in your account.

For example, you might create a 'staging' and a 'production' environment, or you might create different product environments for different websites or, if you implement apps for 3rd-party customers, you could create a separate product environment for each customer.

Each product environment has a separate asset repository. Additionally, some options and preferences are set at the product environment level while others are global for the whole account.

Your active product environment is displayed at the bottom of the Product Navigation menu. It shows the product environment display name if one was defined. Otherwise it shows the cloud name.

Getting started page

When you register for your new account, a very short survey opens to help us understand how you'll be using Cloudinary and ensure the best experience for you.

Next, you'll be taken to the Programmable Media Getting Started page. This page contains a host of information and guidance to help you get started with Cloudinary, including how to access your credentials, how to get set up with our SDKs and an introduction to Cloudinary Programmable Media terminology.

Get familiar with the Cloudinary Console

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

To get started, the most important areas of the Console to become familiar with are the credentials section of the Dashboard page, the Media Explorer, and the Settings.

For details on other areas of the Console, see Cloudinary Console.

Product Environment Credentials

The Product Environment Credentials section on the Dashboard page shows the credentials for the product environment that was created with your account. These credentials include your cloud name identifier, and your API key and secret, which you'll need in order to configure your SDK or to directly run API requests against that product environment.

You can manage your API key and secret in the Access Keys page of the Console Settings. You can add, activate, disable, and name access key pairs. If you've generated additional access keys, the API key and secret that belong to the first access key in your product environment are displayed in the Product Environment Credentials section.

The API Environment variable combines all three credential values and can be copied for quick configuration of your SDK and other server-side integrations.

Check out this video tutorial to help you find your credentials.

Media Library

The Media Library page of your Cloudinary console provides a comprehensive UI for managing all the digital assets in your product environment, including navigating folders, performing advanced searches, compiling assets into ad-hoc collections, collaborating on assets with other Cloudinary users by commenting on assets, drag-and-drop upload of new assets, and more.

When you create a new Programmable Media product environment, a set of sample assets are provided in the Media Library. You can experiment with the Media Library features using these assets.

For more details, see the Digital Asset Management guide.

Optional. Update cloud name and other settings

You can get started using Cloudinary with the default settings, but there are a few initial settings you may want to 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 Account page of the Console Settings, you can see the current Product environment 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.

As long as you have not yet uploaded more than 1000 new assets in that product environment, you can change your cloud name now. You can also set or change your Product environment display name, which is an optional descriptive name that's shown in the product environment selector at the bottom left of the Cloudinary Console. (If no display name is defined, the selector shows the product environment's cloud name)

Check personal settings

In the My Profile page of the Console Settings, users in your account with any role can check their personal email notification and login preferences, and setup two-factor authentication.

Check Upload settings

You may want to check or modify the following product environment settings in the Upload 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 URLs that will 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 Preferences from the Product Navigation menu, located on the left side of the Console.

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 that these values will be retained (unless different values are specified for the tags, context, or metadata parameters as part of the upload), select this option. 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. For example, if your application supports user-generated content, you can define structured metadata fields that will be captured and passed 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, and can ensure that these fields are used consistently for all assets in your product environment.

  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. Once the fields are created, 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.

---

2. Configure your SDK

Cloudinary develops a vast array of open-source SDKs for easier implementation of Cloudinary Programmable Media functionality in both your server-side and client-side code. The SDK libraries wrap Cloudinary's REST APIs and additionally offer 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.

Select the SDK(s) you want to use

Cloudinary offers SDKs for backend, frontend, and mobile development.

Check out the full list of Cloudinary's supported SDKs to decide which one you want to work with.

Install the SDK and include it in your application code

You can use the examples below as one way to install an SDK using the relevant package manager. For more detailed instructions and additional options, review the Installation and setup section of the relevant SDK guide.

Set global configuration options

• For all SDKs, you'll need to configure at least your cloud name.
  
• For backend SDKs, you'll also need to configure your api_key and api_secret.
  
• 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.
• If you have a private CDN or CName, you'll need to configure those as well, and there are other optional configurations you may want to set.
• Here are some basic examples of setting global configuration options in our SDKs:

You can find more information on where and how to specify Cloudinary configuration options for your SDK in the Configuration section of the relevant SDK guide.

Run through an SDK quick start

The best way to get started with Cloudinary is to run through the SDK quick start for the language of your choice.

These quick starts provide step-by-step code snippets that help you get an end-to-end project up and running, from intial SDK setup through delivering optimized and transformed media in 5 minutes or less.

---

3. Add upload capabilities

Cloudinary offers a variety of options for programmatically uploading assets to your product environment from your application.

• Upload API - Implement your own upload functionality with the upload method of the Upload API. This method can be called directly from within your own custom code or by using one of Cloudinary's SDKs that wrap the REST API and greatly simplify the implementation. You also have the option to upload the resources directly to Cloudinary (bypassing your servers) with unsigned uploads - see how it's done in this CodeSandbox example.
  
  

  The following simple example shows the single line of code needed to upload an image from the remote URL https://www.example.com/mysample.jpg, and set its public_id (identifier) as sample_woman using any of our backend SDKs or the REST API:

• Upload widget - Enable your users to upload images, videos or other files from their device or from their social media or media storage accounts via a self-contained, interactive user interface that can be easily embedded within your web application. The widget requires just a couple lines of JavaScript code to integrate into your app and can be optionally implemented with unsigned upload, enabling you to offer it as an exclusively front-end upload solution and eliminates the need to develop in-house interactive media upload capabilities.

  
  

• Auto Upload - Lazily migrate your existing assets to your Cloudinary product environment based on dynamic URL mapping. Your assets are dynamically retrieved the first time the URL is accessed and then stored in your Cloudinary product environment.

Upload preferences

You can specify a wide range of parameters for customizing how a file will be uploaded including:

• Whether asset names will match the uploaded filename or include random characters
• What resource data should be extracted/stored/tagged with the asset
• Analysis or transformations to perform on the uploaded asset
• Incoming or on-demand transformations to perform as part of the upload

• Whether to send status updates to a notification URL
  
  

  And much more...

Check out the full list of available upload parameters.

You can set these preferences either by specifying them as parameters directly in your upload command or by specifying a pre-defined upload preset.

Upload presets enable you to centrally define a set of upload preferences instead of specifying them in each upload call. You can define multiple upload presets and then apply different presets in different upload scenarios. You can also assign the presets that should be used by default for API or Media Library uploads.

You can create and manage upload presets as well as set your product environment's default upload presets from the Upload page of the Console Settings. You can also create and manage upload presets programmatically using the upload_presets method of the Admin API. New product environments come with a default Media Library upload preset already configured.

For more information on upload presets, see Upload presets.

Migration

Cloudinary offers various methods for migrating your existing resources to Cloudinary:

• Direct migration: A one time migration based on the upload method of the Upload API for migrating all existing resources in one phase.
• Lazy migration: Migrate resources on demand from a remote location using Auto Upload, where migration is carried out only when the resource is requested by a visitor.
• Bulk migration code (Rails only): Complete, automatic and exhaustive migration of images from your production environment to Cloudinary with the Cloudinary migration tool.

---

4. Transform and deliver assets

Upload an original image or video once and use Cloudinary to generate different versions from the original, on the fly or in advance, enabling you to deliver optimized and responsive media via leading CDNs that perfectly fits your graphic design across every device and resolution.

Image and video transformations

By adding transformation parameters to an image or video URL (usually via SDK functions), you can apply a huge variety of automatic adjustments and effects to your delivered media.

Learn how to apply image transformations

For example, after uploading the following 'sample_woman' image:

Using on-the-fly transformation parameters directly in the image URL, you could deliver the image with the following changes automatically applied:

• Generate a 200x200px square thumbnail of the largest face in the image (w_200,h_200,c_thumb,g_face).
• Round the corners with a radius of 20 pixels (r_20).
• Add a 5 pixel wide black border (bo_5px_solid_black).
• Add the cloudinary_icon_white image as an overlay, scaled to 25% of the width of the main image, placed 10 pixels away (vertically and horizontally) from the northeast corner, and with 50% opacity (l_cloudinary_icon_white,o_50,w_0.25,fl_relative,g_north_east,y_10,x_10).
• Deliver as a PNG to enable transparency around the rounded corners.
  

And this is what the URL and corresponding SDK delivery code looks like for those transformations:

One of the great things about these transformations, is that once you've chosen the transformation combination that answers your needs, you can reliably apply and deliver any image with the same transformations. For example, here's the same automatically generated face thumbnail for an image of a business man (who was posing in front of the capitol building in the originally uploaded photo):

Learn how to apply video transformations

The same concepts apply for video transformations. This time we'll:

• Scale the portrait video to a height of 320 pixels (h_320,c_scale).
• Pad the video with a blurred version of the same video to generate a 480 * 320 landscape video (c_pad,h_320,w_480,b_blurred:400:15).
• Remove the audio from (mutes) the video (e_volume:mute).
• Double the video speed (e_accelerate:100).

For the complete list of transformations parameters available, see the Transformation URL API Reference.

Optimization and delivery

Cloudinary leverages multiple CDNs, including Akamai, the leading CDN provider, with thousands of global delivery servers. Together with Cloudinary's advanced caching techniques and dynamic URL-based asset delivery, your media assets are efficiently delivered to your users all around the world.

Image and video optimizations

Deliver your assets with the smallest possible file size while maintaining visual quality, saving bandwidth and improving performance for your website. For images, Cloudinary automatically implements certain image optimizations by default. Additionally, for both images and videos, Cloudinary offers many other features for optimizing the resources you deliver to your users, for example:

• Automatic gravity (g_auto) for images or videos instructs Cloudinary to resize and adjust your asset to fill the required dimensions while including the main subject.
• Automatic format selection (f_auto) for images or videos instructs Cloudinary to deliver your asset to each user in the optimal format for the requesting browser.
• Automatic quality selection (q_auto) for images or videos instructs Cloudinary's intelligent quality and encoding algorithm to apply the optimal quality compression level and encoding settings based on the specific content, format, and the requesting browser, in order to generate and deliver the asset with good visual quality while minimizing the file size.

The example shown on the left below applies all 3 of the above optimizations when delivering a cropped portrait video. The original (landscape orientation) 'frisbee_dog' video is shown on the right for comparison.

Responsive images

Upload a single high resolution image and let Cloudinary automatically transform it to perfectly fit any HiDPI device and Retina display, at any pixel density (DPR). Cloudinary supports responsive images using smart, on-the-fly resizing and cropping based on your visitor specific web layout, and also provides various solutions for automatically implementing responsive images on your website. Cloudinary also offers comprehensive options for delivering responsive image options on native android and iOS mobile apps.

Even more transformation and delivery options

You may also want to take advantage of:

• Eager transformations: Create derived transformations for images and videos during the upload process and before publishing to visitors. All transformed resources will be available before your users request them for the first time.
• Incoming transformations: Transform original images and videos during the upload process and then store them as original resources.
• Named transformations: Define named transformations through the Cloudinary Console. This is useful when you have relatively long or complex transformations, or multiple transformations that are commonly used.
• Conditional transformations: Apply transformations if a specified condition is met. The condition is based on specific image characteristics. Especially useful for delivering user generated content, and allows treating different images with different transformation criteria using a single transformation sequence.
• User-defined variables: Enable you to create
• Advanced URL delivery options: Cloudinary offers a range of advanced URL delivery options including:
  media access control, fetch and deliver remote assets with transformations, asset versions, private CDNs and CNAMEs, SEO friendly URLs, multi-CDN solutions and more.

---

5. Next steps

Congratulations! You've taken the first steps to integrating Cloudinary Programmable Media capabilities into your app and you've answered many of the essential questions needed to make the most of Cloudinary.

At this point, you may also want to:

Learn more

This get started page walked you through the most common developer features. Below are a few more major functionalities we didn't cover here:

• Learn how to programmatically manage your assets using Admin API (rate-limited) and Upload API (non-rate-limited) methods.
• Further enhance your media upload and delivery with Cloudinary's add-ons.
• Take advantage of Cloudinary's Integrations to use Cloudinary capabilities directly within leading platforms.

Try it!

Jump right in and start playing with Cloudinary features by taking advantage of our collection of code explorers and interactive demos.

Stay on top of What's New

Once you've got the hang of using Cloudinary, you'll probably want to know when new features, integrations, SDKs, and add-ons are available. Bookmark the Cloudinary Documentation Home page, where you can always see a list of the latest additions and jump straight into the docs for how to use them.

Sign up for a course at the Cloudinary Academy

 

Check out the Cloudinary Academy, where you can take free self-paced courses or register for instructor-led virtual or on-site courses.

You may want to start with one or both of the following free Programmable Media courses:

• Introduction to Cloudinary for Node.js Developers: Interactive lessons on developer-focused APIs and Node.js SDK.
• Cloudinary Fundamentals for Developers: 12 self-paced lessons for new developers on Cloudinary's APIs and working programmatically with media.

(You must be signed in to your Cloudinary account to register for these courses.)

Follow and impact the Cloudinary Roadmap

We invite you to take a look at what's coming, what we are thinking about, and suggest your own ideas on the Cloudinary Roadmap. You can even vote on the planned or considered Roadmap items, indicating what's nice-to-have, what's important and what you see as critical.

Ask questions or share answers on the Cloudinary Community Forum

 

Bookmark the Cloudinary Community Forum, so you can regularly visit to post your questions and get answers from fellow developers and the Cloudinary team, find or share cool tips, learn about new features, and help others solve their media management and delivery challenges.

Watch some DevJams podcasts

 

Choose from a variety of developer-centric podcasts where Cloudinary developers walk you through their innovative implementations for some very cool media use-cases.

Find all the DevJams podcasts on our Cloudinary Podcasts page or subscribe to the Cloudinary DevJams YouTube channel so you'll never miss one.