Skip to content
Blober Download Docs
Articles

Cloudinary

Cloudinary is a cloud-based media management platform for images, videos, and raw files. Blober connects using your Cloud Name, API Key, and API Secret.

Path format:

folder/subfolder/filename.ext

Capabilities

Section titled “Capabilities”
  • ✅ Browse folders and assets
  • ✅ Upload files (streaming, any size)
  • ✅ Download files
  • ✅ Delete assets
  • ✅ View file metadata (size, dates, format)
  • ✅ Automatic detection of images, videos, and raw files on upload
  • ✅ Mixed-type listing of images, videos, and raw files
  • ✅ Pre-generate derived versions at upload time (Eager Transformation)
  • ✅ Apply Eager Transformations to existing assets without re-uploading
  • ✅ Server-side pagination

Prerequisites

Section titled “Prerequisites”

Required Credentials

Section titled “Required Credentials”

Cloud Name

Section titled “Cloud Name”
  • Format: alphanumeric characters, hyphens, underscores
  • Example: my-cloud

Found on your Cloudinary Console under “Product Environment” on the Dashboard. It is also the value that appears after the @ symbol in your CLOUDINARY_URL environment variable.

API Key

Section titled “API Key”
  • Format: numeric string
  • Example: 123456789012345

API Secret

Section titled “API Secret”
  • Format: alphanumeric characters, hyphens, underscores
  • Example: abcdefghijklmnopqrstuvwxyz12

Optional Settings

Section titled “Optional Settings”

Eager Transformation (destination only)

Section titled “Eager Transformation (destination only)”
  • Default: empty (none)
  • Example: w_300,c_fill,f_auto,q_auto

A Cloudinary transformation string applied at upload time to pre-generate a derived asset. Only used when Cloudinary is the destination of your workflow.

Unique Filename (destination only)

Section titled “Unique Filename (destination only)”
  • Default: off (keep original filename)

When off, files keep their original name. When on, Cloudinary appends random characters to the filename (e.g. photo_a1b2c3.jpg) to avoid collisions with existing assets.

Apply Eager Transformation (mutate action)

Section titled “Apply Eager Transformation (mutate action)”
  • Required when running the mutate action
  • Example: w_300,c_fill,f_auto,q_auto

A transformation string applied to existing assets. Select files in Blober and run this mutation to pre-generate derived versions of the originals without re-uploading them.

Setup Guide

Section titled “Setup Guide”

1. Create a Cloudinary Account

Section titled “1. Create a Cloudinary Account”
  1. Go to cloudinary.com
  2. Sign up for a free account (25 credits/month included)
  3. After signing up, you’ll land on the Dashboard

2. Get Your Credentials

Section titled “2. Get Your Credentials”
  1. Open the Cloudinary Console. Your Cloud Name is shown under “Product Environment” on the Dashboard.
  2. Open Settings, then API Keys. You can also jump straight to the API Keys page.
  3. Copy your API Key and API Secret.

3. Configure in Blober

Section titled “3. Configure in Blober”
  1. In Blober, open Workflows, then click New Workflow.
  2. Select Cloudinary as source or destination.
  3. Enter your Cloud Name, API Key, and API Secret.
  4. Credentials are verified on save. Blober makes a test API call to confirm access.

File Organization

Section titled “File Organization”

Cloudinary organizes assets using:

  • Asset folders are the visual hierarchy shown in the Media Library.
  • Public IDs are the path Cloudinary uses internally to reference each asset.

Blober maps both: uploads land in the correct Media Library folder, and the original filename is preserved.

Assets at the root level have no folder prefix. Subfolders are supported to any depth:

samples/cloudinary-icon.png
products/shoes/sneaker.jpg

Cloudinary limits the internal asset path to 255 characters. Files with paths exceeding this limit fail with a validation error before any upload starts.

How Uploads Work

Section titled “How Uploads Work”
  • Files stream directly to Cloudinary. Nothing is buffered in memory, so file size is not a bottleneck.
  • Cloudinary automatically detects whether each file is an image, video, or raw file.
  • The original filename (with extension) is preserved.
  • Existing assets are never silently replaced. Uploading a duplicate returns the existing asset.
  • Files land in the right folder whether your account is on the newer dynamic folder mode or the legacy fixed folder mode.
  • If you set an Eager Transformation, the derived version is generated at upload time.

How Deletion Works

Section titled “How Deletion Works”
  • Deletions go through Cloudinary’s Upload API, which is not rate-limited.
  • Deletes never count against your hourly Admin API quota.

How Listing Works

Section titled “How Listing Works”
  • Listing returns all asset types (images, videos, raw files) in a single paginated call.
  • Sub-folders are loaded as you browse into them.
  • Pagination uses Cloudinary’s native server-side cursors, so even very large folders load smoothly.

Rate Limiting

Section titled “Rate Limiting”
  • The Upload API is not rate-limited. Uploads, deletions, and mutations are unaffected.
  • The Admin API (used for listing, browsing, and metadata) is rate-limited:
    • Free plan: 500 requests/hour
    • Paid plans: 2,000+ requests/hour

Troubleshooting

Section titled “Troubleshooting”

”cloud_name mismatch” error

Section titled “”cloud_name mismatch” error”
  • Verify your Cloud Name matches exactly what’s shown on the Dashboard
  • Cloud names are case-sensitive

”Authorization required” (401) error

Section titled “”Authorization required” (401) error”
  • Double-check your API Key and API Secret.
  • Make sure the key hasn’t been revoked. Open Settings, then API Keys in the Cloudinary Console to confirm.
  • If you recently regenerated the secret, update it in Blober.

Assets not appearing in listing

Section titled “Assets not appearing in listing”
  • Blober lists assets by their Media Library folder.
  • Assets that were uploaded outside the Media Library (for example, directly via the Cloudinary API without an asset folder) may not appear in the browse view. Move them into a Media Library folder so they show up.

Path validation error

Section titled “Path validation error”
  • Cloudinary limits the internal asset path to 255 characters.
  • Deeply nested folder structures can exceed this limit.
  • Blober checks the path length before uploading and fails immediately without making a network call.

Rate limit (420) errors

Section titled “Rate limit (420) errors”
  • You’ve hit the Admin API hourly limit
  • Wait for the rate limit to reset (shown in the error) or upgrade your plan
  • Uploads, deletions, and mutations use the Upload API and are not affected

Best Practices

Section titled “Best Practices”
  • Cloudinary’s free plan includes 25 credits/month covering storage, transformations, and bandwidth

External References

Section titled “External References”