Back to Details

cloudinary

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cloudinary Media Hosting

Cloudinary 媒体托管

Cloudinary provides image and video hosting with CDN delivery, automatic optimization, and on-the-fly transformations.
Cloudinary 提供图片与视频托管服务，支持CDN分发、自动优化以及实时媒体转换。

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
  • 上传图片并自动优化
  • 上传视频并使用CDN分发
  • 获取CDN分发的媒体URL
  • 应用转换操作（调整尺寸、裁剪、格式转换）
  • 拼接多个视频
  • 为生产应用托管媒体

Prerequisites

前置条件

Set the following environment variables:
bash
export CLOUDINARY_CLOUD_NAME=your_cloud_name
export CLOUDINARY_API_KEY=your_api_key
export CLOUDINARY_API_SECRET=your_api_secret
Get credentials from: https://console.cloudinary.com/settings/api-keys
Important: When using 
$VAR
in a command that pipes to another command, wrap the command containing 
$VAR
in 
bash -c '...'
. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
设置以下环境变量：
bash
export CLOUDINARY_CLOUD_NAME=your_cloud_name
export CLOUDINARY_API_KEY=your_api_key
export CLOUDINARY_API_SECRET=your_api_secret
从以下地址获取凭证：https://console.cloudinary.com/settings/api-keys
重要提示： 当在包含管道的命令中使用
$VAR
时，请将包含
$VAR
的命令用
bash -c '...'
包裹。由于Claude Code的一个bug，直接使用管道时环境变量会被静默清除。
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'

How to Use

使用方法

Method 1: Unsigned Upload (Simpler)

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

First, create an unsigned upload preset in Cloudinary Console: Settings > Upload > Upload presets > Add upload preset > Signing Mode: Unsigned
bash
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"
首先，在Cloudinary控制台创建一个无签名上传预设： 设置 > 上传 > 上传预设 > 添加上传预设 > 签名模式：无签名
bash
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

方法2：签名上传

Generate signature and upload:
bash
undefined
生成签名并上传：
bash
undefined

Generate timestamp

生成时间戳

TIMESTAMP=$(date +%s)
TIMESTAMP=$(date +%s)

Generate signature (alphabetical order of params)

生成签名（参数按字母顺序排序）

SIGNATURE=$(bash -c 'echo -n "timestamp=$TIMESTAMP$CLOUDINARY_API_SECRET" | sha1sum | cut -d" " -f1')
SIGNATURE=$(bash -c 'echo -n "timestamp=$TIMESTAMP$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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"
undefined
curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/image/upload" -F "file=@/path/to/image.png" -F "api_key=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"
undefined

Upload from URL

从URL上传

bash
TIMESTAMP=$(date +%s)
SIGNATURE=$(bash -c 'echo -n "timestamp=$TIMESTAMP$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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"
bash
TIMESTAMP=$(date +%s)
SIGNATURE=$(bash -c 'echo -n "timestamp=$TIMESTAMP$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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

Upload Video

上传视频

bash
TIMESTAMP=$(date +%s)
SIGNATURE=$(bash -c 'echo -n "timestamp=$TIMESTAMP$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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"
bash
TIMESTAMP=$(date +%s)
SIGNATURE=$(bash -c 'echo -n "timestamp=$TIMESTAMP$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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

Upload Video with Custom Public ID

自定义Public ID上传视频

bash
TIMESTAMP=$(date +%s)
PUBLIC_ID="my-videos/clip1"
SIGNATURE=$(bash -c 'echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"
bash
TIMESTAMP=$(date +%s)
PUBLIC_ID="my-videos/clip1"
SIGNATURE=$(bash -c 'echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

Upload Video from URL

从URL上传视频

bash
TIMESTAMP=$(date +%s)
PUBLIC_ID="my-videos/clip1"
SIGNATURE=$(bash -c 'echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"
bash
TIMESTAMP=$(date +%s)
PUBLIC_ID="my-videos/clip1"
SIGNATURE=$(bash -c 'echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

With Custom Public ID

自定义Public ID上传图片

bash
TIMESTAMP=$(date +%s)
PUBLIC_ID="my-folder/my-image"
SIGNATURE=$(bash -c 'echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"
bash
TIMESTAMP=$(date +%s)
PUBLIC_ID="my-folder/my-image"
SIGNATURE=$(bash -c 'echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"

Response

响应示例

json
{
  "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/...)
json
{
  "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/...)

URL Transformations

URL 转换

Cloudinary URLs support on-the-fly transformations:
https://res.cloudinary.com/{cloud_name}/image/upload/{transformations}/{public_id}.{format}
Examples:
undefined
Cloudinary URL支持实时媒体转换：
https://res.cloudinary.com/{cloud_name}/image/upload/{transformations}/{public_id}.{format}
示例：
undefined

Resize to 300x200

调整尺寸为300x200

.../image/upload/w_300,h_200/sample.png
.../image/upload/w_300,h_200/sample.png

Auto format and quality

自动格式与质量优化

.../image/upload/f_auto,q_auto/sample.png
.../image/upload/f_auto,q_auto/sample.png

Crop to square

裁剪为正方形

.../image/upload/w_200,h_200,c_fill/sample.png
.../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
undefined
.../image/upload/w_400,h_300,c_fill,f_auto,q_auto/sample.png
undefined

Video Concatenation (Splice)

视频拼接

Concatenate videos using URL transformations with 
l_video:
(overlay) and 
fl_splice
flag.
使用URL转换功能，通过
l_video:
（叠加）和
fl_splice
标志实现视频拼接。

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
将
clip2
追加到
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
将
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

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
将所有视频调整为相同尺寸：
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
为第一个视频添加淡出效果（-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

Add Image as Intro (3 seconds)

添加图片片头（3秒）

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
在视频前添加图片作为片头：
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
  • URL长度限制（约2000字符）会限制可拼接的视频数量
  • 首次请求会触发服务器端处理（速度较慢）
  • 若需拼接10个以上视频，建议使用ffmpeg或专用视频API

Delete Media

删除媒体资源

bash
TIMESTAMP=$(date +%s)
PUBLIC_ID="<your-public-id>"
SIGNATURE=$(bash -c 'echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$CLOUDINARY_API_SECRET" | sha1sum | cut -d" " -f1')
bash
TIMESTAMP=$(date +%s)
PUBLIC_ID="<your-public-id>"
SIGNATURE=$(bash -c 'echo -n "public_id=$PUBLIC_ID&timestamp=$TIMESTAMP$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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"
curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/image/destroy" -F "public_id=$PUBLIC_ID" -F "api_key=$CLOUDINARY_API_KEY" -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=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"
undefined
curl -X POST "https://api.cloudinary.com/v1_1/<your-cloud-name>/video/destroy" -F "public_id=$PUBLIC_ID" -F "api_key=$CLOUDINARY_API_KEY" -F "timestamp=$TIMESTAMP" -F "signature=$SIGNATURE"
undefined

Free Tier Limits

免费版限制

  • 25 credits/month
  • ~25,000 transformations or ~25GB storage/bandwidth
  • Sufficient for personal projects
  • 每月25个积分
  • 约25,000次转换操作或25GB存储/带宽
  • 足以满足个人项目需求

Guidelines

使用指南

  1. Use unsigned presets for simpler uploads when security isn't critical
  2. Signature order: Parameters must be alphabetically sorted when generating signature
  3. Auto optimization: Add 
    f_auto,q_auto
    to URLs for automatic format/quality
  4. Folders: Use 
    public_id="folder/subfolder/name"
    to organize media
  5. Video concatenation: Keep URLs short; for 10+ videos use external tools
  1. 使用无签名预设：当安全性要求不高时，可使用无签名预设简化上传流程
  2. 签名顺序：生成签名时，参数必须按字母顺序排序
  3. 自动优化：在URL中添加
    f_auto,q_auto
    以实现自动格式/质量优化
  4. 文件夹管理：使用
    public_id="folder/subfolder/name"
    来组织媒体资源
  5. 视频拼接：保持URL长度简短；若拼接10个以上视频，建议使用外部工具

API Reference

API 参考文档