Cloudinary 图像视频托管教程：CDN交付、自动优化与实时转换

cloudinary by vm0-ai/vm0-skills

105 周安装量

52 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/vm0-ai/vm0-skills --skill cloudinary

云服务图像处理 API

🇨🇳中文介绍

Cloudinary 媒体托管

Cloudinary 提供图像和视频托管服务，具备 CDN 交付、自动优化和实时转换功能。

使用场景

上传图像并自动优化
上传视频并通过 CDN 交付
获取通过 CDN 交付的媒体 URL
应用转换（调整大小、裁剪、格式转换）
拼接/连接多个视频
为生产应用程序托管媒体

前提条件

设置以下环境变量：

export CLOUDINARY_CLOUD_NAME=your_cloud_name
export CLOUDINARY_TOKEN=your_api_key
export CLOUDINARY_API_SECRET=your_api_secret

从以下网址获取凭证：https://console.cloudinary.com/settings/api-keys

使用方法

方法 1：无签名上传（更简单）

首先，在 Cloudinary 控制台中创建一个无签名上传预设：Settings > Upload > Upload presets > Add upload preset > Signing Mode: Unsigned

curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/image/upload" -F "file=@/path/to/image.png" -F "upload_preset=your_preset_name"

方法 2：签名上传

生成签名并上传：

# 生成时间戳
TIMESTAMP=$(date +%s)

# 生成签名（参数按字母顺序排列）
SIGNATURE=$(echo -n "timestamp=$TIMESTAMP$(printenv CLOUDINARY_API_SECRET)" | sha1sum | cut -d" " -f1)

# 上传
curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/image/upload" -F "file=@/path/to/image.png" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

使用自定义公共 ID 上传视频

TIMESTAMP=$(date +%s)
PUBLIC_ID="my-videos/clip1"
SIGNATURE=$(echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$(printenv CLOUDINARY_API_SECRET)" | sha1sum | cut -d" " -f1)

curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/video/upload" -F "file=@/path/to/video.mp4" -F "public_id=$PUBLIC_ID" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

从 URL 上传视频

TIMESTAMP=$(date +%s)
PUBLIC_ID="my-videos/clip1"
SIGNATURE=$(echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$(printenv CLOUDINARY_API_SECRET)" | sha1sum | cut -d" " -f1)

curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/video/upload" -F "file=https://example.com/video.mp4" -F "public_id=$PUBLIC_ID" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

使用自定义公共 ID

TIMESTAMP=$(date +%s)
PUBLIC_ID="my-folder/my-image"
SIGNATURE=$(echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$(printenv CLOUDINARY_API_SECRET)" | sha1sum | cut -d" " -f1)

curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/image/upload" -F "file=@/path/to/image.png" -F "public_id=$PUBLIC_ID" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

{
  "public_id": "sample",
  "secure_url": "https://res.cloudinary.com/demo/image/upload/v1234567890/sample.png",
  "url": "http://res.cloudinary.com/demo/image/upload/v1234567890/sample.png",
  "format": "png",
  "width": 800,
  "height": 600
}

关键字段：secure_url - 在 Markdown 中使用：![img](https://res.cloudinary.com/...)

Cloudinary URL 支持实时转换：

https://res.cloudinary.com/{cloud_name}/image/upload/{transformations}/{public_id}.{format}

# 调整大小为 300x200
.../image/upload/w_300,h_200/sample.png

# 自动格式和质量
.../image/upload/f_auto,q_auto/sample.png

# 裁剪为正方形
.../image/upload/w_200,h_200,c_fill/sample.png

# 组合转换
.../image/upload/w_400,h_300,c_fill,f_auto,q_auto/sample.png

使用带有 l_video:（叠加）和 fl_splice 标志的 URL 转换来拼接视频。

将 clip2 附加到 clip1 的末尾：

https://res.cloudinary.com/{cloud_name}/video/upload/l_video:clip2,fl_splice/fl_layer_apply/clip1.mp4

将 clip2 和 clip3 附加到 clip1：

https://res.cloudinary.com/{cloud_name}/video/upload/l_video:clip2,fl_splice/fl_layer_apply/l_video:clip3,fl_splice/fl_layer_apply/clip1.mp4

将所有视频调整为相同尺寸：

https://res.cloudinary.com/{cloud_name}/video/upload/w_640,h_360,c_fill/l_video:clip2,fl_splice,w_640,h_360,c_fill/fl_layer_apply/clip1.mp4

添加淡入淡出过渡

在第一个视频上添加淡出（-1000ms），在第二个视频上添加淡入（1000ms）：

https://res.cloudinary.com/{cloud_name}/video/upload/w_640,h_360,c_fill,e_fade:-1000/l_video:clip2,fl_splice,e_fade:1000,w_640,h_360,c_fill/fl_layer_apply/clip1.mp4

添加图像作为片头（3 秒）

在开头添加图像作为片头：

https://res.cloudinary.com/{cloud_name}/video/upload/l_intro_image,fl_splice,du_3/so_0,fl_layer_apply/clip1.mp4

URL 长度限制（约 2000 个字符）限制了视频数量
首次请求会触发服务器端处理（较慢）
对于大量视频（10 个以上），请考虑使用 ffmpeg 或专用视频 API

TIMESTAMP=$(date +%s)
PUBLIC_ID="<your-public-id>"
SIGNATURE=$(echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$(printenv CLOUDINARY_API_SECRET)" | sha1sum | cut -d" " -f1)

# 删除图像
curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/image/destroy" -F "public_id=$PUBLIC_ID" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

# 删除视频
curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/video/destroy" -F "public_id=$PUBLIC_ID" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

每月 25 个积分
约 25,000 次转换或约 25GB 存储/带宽
足以满足个人项目需求

使用无签名预设：当安全性要求不高时，用于更简单的上传
签名顺序：生成签名时，参数必须按字母顺序排序
自动优化：在 URL 中添加 f_auto,q_auto 以实现自动格式/质量优化
文件夹：使用 public_id="folder/subfolder/name" 来组织媒体
视频拼接：保持 URL 简短；对于 10 个以上的视频，请使用外部工具

2026 年 1 月 24 日

🇺🇸English

Cloudinary Media Hosting

Cloudinary provides image and video hosting with CDN delivery, automatic optimization, and on-the-fly transformations.

When to Use

Upload images with automatic optimization
Upload videos with CDN delivery
Get CDN-delivered media URLs
Apply transformations (resize, crop, format conversion)
Concatenate/splice multiple videos
Host media for production applications

Prerequisites

Set the following environment variables:

export CLOUDINARY_CLOUD_NAME=your_cloud_name
export CLOUDINARY_TOKEN=your_api_key
export CLOUDINARY_API_SECRET=your_api_secret

Get credentials from: https://console.cloudinary.com/settings/api-keys

How to Use

Method 1: Unsigned Upload (Simpler)

First, create an unsigned upload preset in Cloudinary Console: Settings > Upload > Upload presets > Add upload preset > Signing Mode: Unsigned

curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/image/upload" -F "file=@/path/to/image.png" -F "upload_preset=your_preset_name"

Method 2: Signed Upload

Generate signature and upload:

# Generate timestamp
TIMESTAMP=$(date +%s)

# Generate signature (alphabetical order of params)
SIGNATURE=$(echo -n "timestamp=$TIMESTAMP$(printenv CLOUDINARY_API_SECRET)" | sha1sum | cut -d" " -f1)

# Upload
curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/image/upload" -F "file=@/path/to/image.png" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

Upload from URL

TIMESTAMP=$(date +%s)
SIGNATURE=$(echo -n "timestamp=$TIMESTAMP$(printenv CLOUDINARY_API_SECRET)" | sha1sum | cut -d" " -f1)

curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/image/upload" -F "file=https://example.com/image.png" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

Upload Video

TIMESTAMP=$(date +%s)
SIGNATURE=$(echo -n "timestamp=$TIMESTAMP$(printenv CLOUDINARY_API_SECRET)" | sha1sum | cut -d" " -f1)

curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/video/upload" -F "file=@/path/to/video.mp4" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

Upload Video with Custom Public ID

TIMESTAMP=$(date +%s)
PUBLIC_ID="my-videos/clip1"
SIGNATURE=$(echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$(printenv CLOUDINARY_API_SECRET)" | sha1sum | cut -d" " -f1)

curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/video/upload" -F "file=@/path/to/video.mp4" -F "public_id=$PUBLIC_ID" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

Upload Video from URL

TIMESTAMP=$(date +%s)
PUBLIC_ID="my-videos/clip1"
SIGNATURE=$(echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$(printenv CLOUDINARY_API_SECRET)" | sha1sum | cut -d" " -f1)

curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/video/upload" -F "file=https://example.com/video.mp4" -F "public_id=$PUBLIC_ID" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

With Custom Public ID

TIMESTAMP=$(date +%s)
PUBLIC_ID="my-folder/my-image"
SIGNATURE=$(echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$(printenv CLOUDINARY_API_SECRET)" | sha1sum | cut -d" " -f1)

curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/image/upload" -F "file=@/path/to/image.png" -F "public_id=$PUBLIC_ID" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

Response

{
  "public_id": "sample",
  "secure_url": "https://res.cloudinary.com/demo/image/upload/v1234567890/sample.png",
  "url": "http://res.cloudinary.com/demo/image/upload/v1234567890/sample.png",
  "format": "png",
  "width": 800,
  "height": 600
}

Key field: secure_url - Use this in Markdown: ![img](https://res.cloudinary.com/...)

URL Transformations

Cloudinary URLs support on-the-fly transformations:

https://res.cloudinary.com/{cloud_name}/image/upload/{transformations}/{public_id}.{format}

Examples:

# Resize to 300x200
.../image/upload/w_300,h_200/sample.png

# Auto format and quality
.../image/upload/f_auto,q_auto/sample.png

# Crop to square
.../image/upload/w_200,h_200,c_fill/sample.png

# Combine transformations
.../image/upload/w_400,h_300,c_fill,f_auto,q_auto/sample.png

Video Concatenation (Splice)

Concatenate videos using URL transformations with l_video: (overlay) and fl_splice flag.

Basic Concatenation

Append clip2 to the end of clip1:

https://res.cloudinary.com/{cloud_name}/video/upload/l_video:clip2,fl_splice/fl_layer_apply/clip1.mp4

Concatenate Multiple Videos

Append clip2 and clip3 to clip1:

https://res.cloudinary.com/{cloud_name}/video/upload/l_video:clip2,fl_splice/fl_layer_apply/l_video:clip3,fl_splice/fl_layer_apply/clip1.mp4

With Uniform Size

Resize all videos to same dimensions:

https://res.cloudinary.com/{cloud_name}/video/upload/w_640,h_360,c_fill/l_video:clip2,fl_splice,w_640,h_360,c_fill/fl_layer_apply/clip1.mp4

With Fade Transition

Add fade out (-1000ms) on first video and fade in (1000ms) on second:

https://res.cloudinary.com/{cloud_name}/video/upload/w_640,h_360,c_fill,e_fade:-1000/l_video:clip2,fl_splice,e_fade:1000,w_640,h_360,c_fill/fl_layer_apply/clip1.mp4

Add Image as Intro (3 seconds)

Prepend an image as intro:

https://res.cloudinary.com/{cloud_name}/video/upload/l_intro_image,fl_splice,du_3/so_0,fl_layer_apply/clip1.mp4

Limitations

URL length limit (~2000 chars) restricts number of videos
First request triggers server-side processing (slow)
For many videos (10+), consider using ffmpeg or dedicated video APIs

Delete Media

TIMESTAMP=$(date +%s)
PUBLIC_ID="<your-public-id>"
SIGNATURE=$(echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$(printenv CLOUDINARY_API_SECRET)" | sha1sum | cut -d" " -f1)

# Delete image
curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/image/destroy" -F "public_id=$PUBLIC_ID" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

# Delete video
curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/video/destroy" -F "public_id=$PUBLIC_ID" -F "api_key=$(printenv CLOUDINARY_TOKEN)" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

Free Tier Limits

25 credits/month
~25,000 transformations or ~25GB storage/bandwidth
Sufficient for personal projects

Guidelines

Use unsigned presets for simpler uploads when security isn't critical
Signature order : Parameters must be alphabetically sorted when generating signature
Auto optimization : Add f_auto,q_auto to URLs for automatic format/quality
Folders : Use public_id="folder/subfolder/name" to organize media
Video concatenation : Keep URLs short; for 10+ videos use external tools

API Reference

Image Upload: https://cloudinary.com/documentation/image_upload_api_reference
Video Upload: https://cloudinary.com/documentation/video_upload_api_reference
Video Concatenation: https://cloudinary.com/documentation/video_trimming_and_concatenating
Console: https://console.cloudinary.com/
Transformation Reference: https://cloudinary.com/documentation/transformation_reference

Weekly Installs

Repository

vm0-ai/vm0-skills

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode87

gemini-cli86

codex84

github-copilot83

amp75

kimi-cli75

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

111,700 周安装