用途:通过 Cloudinary 的 REST API 管理媒体资源,包括上传、变换、优化与分发图片和视频。
主要能力:上传图片与视频;用 URL 参数做裁剪、缩放、特效等变换;f_auto、q_auto 自动优化;生成响应式断点 URL;视频以 /video/upload/ 分发,可用 sp_auto 生成 HLS/DASH 自适应流;用 Admin API 列出资源、查询详情;用 destroy 按资源类型删除资源。支持 e_gen_* 生成式 AI 效果(如移除、替换对象、换背景、修复)以及 e_background_removal 背景移除;auto_tagging 自动打标签需先注册相应附加组件。
使用方式:先配置凭证,可用 CLOUDINARY_URL,或用 CLOUDINARY_CLOUD_NAME、CLOUDINARY_API_KEY、CLOUDINARY_API_SECRET 三个变量;未配置时需在 Cloudinary 注册后从控制台 API Keys 页面获取。上传参数中除 file、cloud_name、api_key、resource_type 和 signature 外,其余参数都要参与签名并按字母排序;浏览器端上传不要让 api_secret 进入客户端,可走服务端签名或 unsigned upload_preset。变换 URL 形如 https://res.cloudinary.com/{cloud_name}/image/upload/{transformations}/{public_id}.{format}。也可选装 URL Gen SDK,例如 npm install @cloudinary/url-gen @cloudinary/react。
适用场景:产品图、头像、社交分享图、响应式图片、视频交付、素材库管理等。
限制与注意:单次 POST 不能上传超过 100 MB 的文件,大视频需分块上传并传 resource_type="video",eager 变换可加 eager_async=true。Admin API 每次最多返回 500 条,需要用 next_cursor 翻页。删除要传对应资源类型,invalidate=true 才能清除 CDN 缓存。动态文件夹模式用 asset_folder(不影响 public_id),固定模式用 folder。上传前需检查文件夹模式。生成式 AI 效果部分仍标注 Beta,背景移除会计费。l_text 覆盖层支持希伯来语时需 URL 编码并使用内置含该字形的字体,非内置字体需加 @google 且字重必须为数字。部分收费、价格和平台细节资料未提供,应参照官方文档确认。