Skip to content

platform-capabilities.md

Latest commit

 

History

History
124 lines (90 loc) · 6.61 KB

platform-capabilities.md

File metadata and controls

124 lines (90 loc) · 6.61 KB
Raw

What this SDK does and does not do

Cloudinary is a platform with many surfaces. This gem — the Ruby and Rails server-side SDK — implements some of them natively, expresses some through generic URL building, and does not implement others. Verified against this gem 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 gem 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:

Get media in

To do this Use Where to go
Upload a local path, IO, remote URL, or data URI Cloudinary::Uploader.upload Upload an image
Upload something too large for one request Cloudinary::Uploader.upload_large Upload a large video
Let a browser or mobile app upload directly, authorized by your server Cloudinary::Utils.api_sign_request Sign a browser upload
Review user-generated content before showing it upload options + Cloudinary::Api Moderate an upload
Attach uploads to an Active Record model Active Storage or CarrierWave Active Storage, CarrierWave

Deliver and transform

To do this Use Where to go
Build a resize, crop, overlay, or format-optimized image URL Cloudinary::Utils.cloudinary_url Transform and deliver an image
Render an <img> / <picture> tag in a Rails view cl_image_tag, cl_picture_tag Use with Rails
Build a video URL, player tag, poster frame, or HLS/DASH stream Cloudinary::Utils.cloudinary_url with resource_type: "video", cl_video_tag 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 Cloudinary::Search Search and manage assets
Read, update, restore, or delete an asset; manage folders and presets Cloudinary::Api — the Admin API Search and manage assets
Attach and query typed metadata fields Cloudinary::Api + upload options Use structured metadata
Find visually similar assets Cloudinary::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 Cloudinary::Api.analyze — 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 Cloudinary::AccountApi, via CLOUDINARY_ACCOUNT_URL Provisioning API docs

Not in this package

This gem 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 in JavaScript, upload UI frontend SDKs, Upload Widget