Cloudinary Node.js SDK

Upload, transform, optimize, and manage images and videos with Cloudinary from Node.js — the cloudinary package on npm.

Install

npm install cloudinary

Quick start

Set your API environment variable (Console > Settings > API Keys):

export CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>

Upload an image and get an optimized delivery URL:

const cloudinary = require('cloudinary').v2;

async function main() {
  // Upload a remote image (a local file path works the same way)
  const result = await cloudinary.uploader.upload(
    'https://res.cloudinary.com/demo/image/upload/sample.jpg',
    { public_id: 'quickstart-sample' }
  );
  console.log(`Uploaded: ${result.public_id}`);

  // Build a 400x400 auto-cropped URL with automatic format and quality
  const url = cloudinary.url(result.public_id, {
    width: 400,
    height: 400,
    crop: 'fill',
    gravity: 'auto',
    fetch_format: 'auto',
    quality: 'auto',
    secure: true
  });
  console.log(`Optimized URL: ${url}`);
}

main().catch((error) => {
  console.error(`Quick start failed: ${error.message}`);
  console.error('Check that CLOUDINARY_URL is set (Console > Settings > API Keys).');
  process.exitCode = 1;
});

Save as quickstart.js and run node quickstart.js. Create a free account if you don't have one — or run npx @cloudinary/cloud to provision one without signing up.

upload() also accepts a Buffer, Uint8Array, ArrayBuffer, Blob or File. Pass filename so that raw uploads keep their extension and original_filename is useful (the default is the File name, or "file"):

const csv = Buffer.from('id,name\n1,sample\n');
await cloudinary.uploader.upload(csv, { resource_type: 'raw', filename: 'report.csv' });

Common tasks

• Get Cloudinary credentials
• Upload an image
• Upload a large video
• Sign a browser upload
• Transform and deliver an image
• Transform and deliver a video
• Search and manage assets
• Moderate an upload
• Use structured metadata
• Troubleshoot errors

Runnable versions live in examples/ — each is a complete file you can run directly.

When to use this SDK

Use this package in Node.js server-side code: uploads, signed operations, asset administration, search, moderation, and delivery URL generation.

For other jobs, better-fitting tools exist:

• Browser or frontend framework rendering: @cloudinary/url-gen and the frontend SDKs (md).
• Complete in-browser upload UI: Upload Widget (md).
• Text-to-image generation and image-to-video: platform APIs (md), not wrapped by this package.
• Multi-step media workflow automation: MediaFlows (md).
• Interactive agent-driven asset operations: Cloudinary MCP servers and Skills (md).

The full capability map — plus the Skills, MCP servers, and CLI worth setting up first — is in docs/platform-capabilities.md.

Status and compatibility

Stable, actively maintained. See CHANGELOG.md.

SDK version	Node.js
2.x	9 and later
1.x	6 and later (no longer maintained)

Documentation

• Bundled task docs — ship inside the package, version-matched.
• Node SDK guide — the full documentation (md).

Documentation links in this README point at the browsable HTML page, with an (md) companion link that returns the same page as raw Markdown. Inside docs/ and examples/ the links are Markdown-only, since those files are written to be read by coding agents. Either form works for any page: add .md for Markdown, drop it for HTML.

For AI coding agents

• Contributing to this repo: read AGENTS.md.
• Using the installed package: the docs in node_modules/cloudinary/docs/ match your installed version and are the source of truth; start with platform-capabilities before assuming a feature exists.

Support

• SDK bugs and feature requests: GitHub issues
• Account and platform questions: Cloudinary support

Security

See SECURITY.md for private vulnerability reporting. Keep your api_secret in server-side code; for client uploads, use the server-signed pattern in Sign a browser upload.

License

Released under the MIT license — see LICENSE. Copyright (c) Cloudinary Ltd.