Cloudinary Getting Started: Account, Keys, First Request (2026)

Getting started overview

This guide outlines the essential steps to initiate development with Cloudinary, focusing on account creation, credential retrieval, and executing a foundational API request. Cloudinary provides a cloud-based service for managing images and videos, including upload, storage, transformation, optimization, and delivery. Developers typically integrate with Cloudinary using one of its software development kits (SDKs), which abstract direct API interactions.

The core workflow for a new Cloudinary user involves:

1. Signing up for a Cloudinary account.
2. Locating and understanding your API credentials (Cloud name, API Key, API Secret).
3. Configuring your development environment with these credentials.
4. Making a first API call, commonly an image upload, to verify setup.

Cloudinary's API reference documentation details all available endpoints and parameters for media management. For a quick start, the focus remains on authentication and a basic upload operation.

Quick Start Table

Create an account and get keys

To begin using Cloudinary, you must first create a free account. The free tier offers significant usage limits, including 25,000 transformations, 25 GB of storage, and 25 GB of CDN bandwidth per month, suitable for initial development and small projects.

Account Creation Process

1. Navigate to the Cloudinary signup page.
2. Provide a valid email address, choose a password, and optionally specify your organization's name.
3. Review and accept the terms of service.
4. Complete the signup process. You may receive an email to verify your account.

Retrieving API Credentials

Upon successful account creation and login, you will be directed to your Cloudinary Dashboard. Your essential API credentials are prominently displayed under the Account Details section:

• Cloud name: A unique identifier for your Cloudinary account. This is part of the URL for accessing your media assets.
• API Key: A public identifier used to identify your account when making API requests.
• API Secret: A sensitive, private key used to sign authenticated API requests. Keep this secret secure and never expose it in client-side code.

For security best practices, Cloudinary recommends storing your API Secret as an environment variable rather than hardcoding it directly into your application code, especially in production environments. This practice aligns with general security guidelines for handling sensitive credentials, as described in guides like the Google Cloud API keys documentation.

Your first request

After obtaining your credentials, the next step is to make your first API call. A common initial request is uploading an image. This demonstrates successful authentication and interaction with the Cloudinary API. This example uses the Node.js SDK, but the principles apply across other Cloudinary SDKs.

1. Install the SDK

First, install the Cloudinary SDK for your chosen language. For Node.js, use npm:

npm install cloudinary

2. Configure Credentials

Set up your Cloudinary configuration using your Cloud name, API Key, and API Secret. It's recommended to use environment variables for the API Secret.

// For Node.js example
const cloudinary = require('cloudinary').v2;

cloudinary.config({
  cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
  secure: true
});

// Example environment variable setup (e.g., in a .env file or shell)
// CLOUDINARY_CLOUD_NAME="your_cloud_name"
// CLOUDINARY_API_KEY="your_api_key"
// CLOUDINARY_API_SECRET="your_api_secret"

3. Upload an Image

Now, you can upload an image. You can upload from a local file path, a remote URL, or a base64 string.

// Upload a local file
cloudinary.uploader.upload("path/to/your/image.jpg", 
  { public_id: "my_first_image" }, 
  function(error, result) {
    if (error) {
      console.error(error);
    } else {
      console.log(result);
      // The 'result' object contains details about the uploaded image,
      // including its URL, public ID, and transformation options.
      console.log("Image uploaded successfully! URL:", result.url);
    }
  });

// Upload from a remote URL
// cloudinary.uploader.upload("https://www.example.com/image.jpg", 
//   { public_id: "remote_image" }, 
//   function(error, result) {
//     if (error) { console.error(error); } else { console.log(result); }
//   });

Upon successful execution, the console will log a result object containing metadata about the uploaded image, including its secure URL. This URL can then be used to display the image in your application.

Common next steps

After successfully uploading your first image, several common paths extend your use of Cloudinary:

• Dynamic Image Transformations: Explore Cloudinary's extensive capabilities for on-the-fly image transformations. This includes resizing, cropping, applying filters, watermarking, and format conversion. These transformations are achieved by manipulating the image's URL.
• Video Management: Extend your understanding to video uploads, transformations, and delivery. Cloudinary offers similar powerful features for video content, including adaptive bitrate streaming, transcoding, and generating video previews.
• Digital Asset Management (DAM): For larger projects, investigate Cloudinary's DAM features. This includes organizing assets with tags and folders, searching, version control, and team collaboration tools. The DAM documentation provides details.
• Webhooks: Implement webhooks to receive notifications about asynchronous events, such as the completion of a lengthy video processing task or an upload. This allows your application to react to events without continuous polling. Twilio's webhook security guide offers a general overview of webhook implementation best practices, which can be applied to Cloudinary webhooks.
• Front-end Integration: Integrate Cloudinary's front-end libraries (e.g., for React, Angular, Vue.js) to simplify displaying and manipulating images and videos directly within your user interface.
• Error Handling and Logging: Implement robust error handling and logging mechanisms for your Cloudinary API calls to ensure application stability and facilitate debugging.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some frequent problems and their solutions:

• Authentication Errors (401 Unauthorized):
  • Issue: Incorrect API Key or API Secret.
  • Solution: Double-check your cloud_name, api_key, and api_secret against the values in your Cloudinary Dashboard. Ensure there are no leading/trailing spaces or typos. Verify environment variables are loaded correctly.
• Network or Connection Issues:
  • Issue: The application cannot reach Cloudinary servers.
  • Solution: Check your internet connection. If you are behind a corporate firewall or proxy, ensure that outbound connections to Cloudinary's domains (e.g., api.cloudinary.com, res.cloudinary.com) are permitted.
• File Not Found or Invalid Path:
  • Issue: The local file path provided for upload is incorrect or the file doesn't exist.
  • Solution: Verify the absolute or relative path to your image file. Ensure your application has read permissions for the file.
• SDK Not Initialized Correctly:
  • Issue: The Cloudinary SDK configuration is missing or malformed.
  • Solution: Ensure cloudinary.config() is called with all required parameters (cloud_name, api_key, api_secret) before making any upload or transformation calls.
• Exceeded Free Tier Limits:
  • Issue: If you are on the free tier, you might hit monthly limits for transformations, storage, or bandwidth.
  • Solution: Check your usage statistics in the Cloudinary Dashboard. If limits are exceeded, consider upgrading your plan or optimizing your usage.
• CORS Issues (for direct browser uploads):
  • Issue: If attempting direct uploads from a browser, Cross-Origin Resource Sharing (CORS) policies might block the request.
  • Solution: Configure upload presets with appropriate CORS settings in your Cloudinary console to allow requests from your domain.

For more detailed troubleshooting, consult the Cloudinary API reference for specific error codes and their meanings.