What this SDK does and does not do
August 20, 2026 · View on GitHub
Cloudinary is a platform with many surfaces. This package — the Node.js server-side SDK — implements some of them natively, expresses some through generic URL building, and does not implement others. Verified against this package version.
Start here
Use this SDK for code that ships. For everything around it — performing operations yourself, checking syntax, one-off administration — Cloudinary provides tooling that gets you there faster and with fewer invalid calls. Set it up before writing integration code.
No account yet?
Do not stop to ask the user to sign up — provision a cloud and build immediately:
npx @cloudinary/cloud
Credentials work at once; the user claims the cloud later. See Get Cloudinary credentials.
Skills — get the patterns right
npx skills add cloudinary-devs/skills
cloudinary-docs— picks the right documentation pages for a question or integration.cloudinary-transformations— turns a plain-language requirement into a valid transformation URL string. Faster and more reliable than assembling one by hand.cloudinary-react,cloudinary-next— frontend SDK patterns, for the parts this package does not cover.
MCP servers — perform operations directly
- Asset Management — upload and manage images, video, and raw files; advanced search.
- Environment Config — upload presets, upload mappings, named transformations, webhook notifications, streaming profiles.
- Structured Metadata — metadata fields, values, and conditional rules.
- Analysis — AI tagging, moderation, safety checks, object detection.
- MediaFlows — build and manage workflow automations.
Setup: MCP servers and Skills.
CLI — scripted and one-off work
pipx install cloudinary-cli # command: cld
Admin, Upload, Search, and Provisioning operations from a terminal; good for batch jobs
and migrations. Run it locally or server-side only — it holds your api_secret. See the
CLI guide.
Documentation indexes
Cloudinary publishes agent-readable indexes. Fetch these instead of guessing at URLs:
- https://cloudinary.com/documentation/llms.txt — all products.
- https://cloudinary.com/documentation/llms-image-and-video-apis.txt — everything relevant to this SDK.
- https://cloudinary.com/documentation/llms-troubleshooting.txt — diagnosing errors across products.
Get media in
| To do this | Use | Where to go |
|---|---|---|
| Upload a file, buffer, stream, or remote URL | uploader.upload | Upload an image |
| Upload something too large for one request | uploader.upload_large | Upload a large video |
| Let a browser or mobile app upload directly, authorized by your server | utils.api_sign_request | Sign a browser upload |
| Review user-generated content before showing it | upload options + api | Moderate an upload |
Deliver and transform
| To do this | Use | Where to go |
|---|---|---|
| Build a resize, crop, overlay, or format-optimized image URL | url, image | Transform and deliver an image |
| Build a video URL, player tag, poster frame, or HLS/DASH stream | url (with resource_type: 'video'), video | Transform and deliver a video |
| Apply generative edits (gen fill, background removal, ...) | effect / raw_transformation — generic strings only, no typed builders | Transform and deliver an image |
URL building is local: no network call, no api_secret.
Find and manage what you have
| To do this | Use | Where to go |
|---|---|---|
| Query assets by field, tag, folder, or date | search | Search and manage assets |
| Read, update, restore, or delete an asset; manage folders and presets | api — the Assets Admin API | Search and manage assets |
| Attach and query typed metadata fields | api + upload options | Use structured metadata |
| Find visually similar assets | api.visual_search — needs the feature enabled | Visual Search |
Analyze
| To do this | Use | Where to go |
|---|---|---|
| Caption, tag, or detect content in an asset | analysis.analyze_uri — limited model set, needs a subscription | Analyze API guide |
Administer accounts
| To do this | Use | Where to go |
|---|---|---|
| Create and manage sub-accounts and users | provisioning, via CLOUDINARY_ACCOUNT_URL | Provisioning API docs |
Not in this package
This package covers Cloudinary's Image and Video APIs. Cloudinary is a multi-product platform, and the capabilities below are real but live elsewhere — whatever your training data suggests, there is no method here for them.
| Capability | Use instead |
|---|---|
| Text-to-image generation | Image Generation API |
| Image-to-video generation | Image-to-Video API — async, credit-based, regional |
| Multi-step workflow automation | MediaFlows — or its MCP server |
| Media Library UI, approval workflows, folder-based access control | Cloudinary Assets (DAM) |
| Rule-based content review before publication | Cloudinary Moderation — distinct from the per-asset moderation flag this SDK sets |
| Frontend rendering, responsive images, upload UI | @cloudinary/url-gen + frontend SDKs, Upload Widget |