上传与管理

官方 SDK 的 upload("file_…") 会把字符串当作本地路径。从文件导入请使用自有接口 POST /media/v1/libraries/{library_id}/assets/import，见导入文件。

上传接受文件字节、HTTPS URL 或 data URI。音频使用 video，自动识别使用 auto。SDK 的 upload_large 将分片发送到同一 upload 端点。

tags 可写成逗号分隔字符串、数组或多个 tags 字段（-F tags=a -F tags=b），三者等价；逗号分隔时每项去首尾空白并丢弃空项。0 字节文件返回 FILE_EMPTY；读不出宽高的图片返回 Invalid image file；其他任意文件作为 raw 接受。

await new Promise((resolve, reject) => {
  cloudinary.uploader.upload_large("./video.mp4", {
    resource_type: "video",
    chunk_size: 20 * 1024 * 1024,
  }, (error, result) => error ? reject(error) : resolve(result));
});

每片共享 X-Unique-Upload-Id。Content-Range 为 bytes 起点-终点/总字节数；未知总数用 -1，末片给最终大小。非末片至少 5 MiB 且等长。会话有效期 24 小时。中间片返回 done=false 与 upload_id；末片返回素材和 done=true。

指南 →

基础地址与鉴权

上传素材

POST /cloudinary/v1_1/{library_id}/{resource_type}/upload

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw / auto	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
X-Unique-Upload-Id	header	string	—
Content-Range	header	string	—

请求体

字段	类型	必填	说明
file	string / string	是	文件字节、HTTPS URL、data URI 或同账户 file_…
public_id	string	否	交付地址中的素材名称，可带路径
public_id_prefix	string	否	public_id 的路径前缀；末尾的 / 可有可无，前缀与 ID 之间只保留一个 /
display_name	string	否	显示名称
asset_folder	string	否	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
use_filename	boolean	否	用文件名生成 public_id
unique_filename	boolean	否	自动附加唯一后缀
use_filename_as_display_name	boolean	否	用文件名作为显示名称
filename_override	string	否	覆盖原文件名称
overwrite	boolean	否	是否覆盖同名素材
tags	string / string[]	否	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	string / object	否	自定义文字键值；PATCH 整体替换，传 {} 清空
auto_tagging	number	否	理解后将达到阈值的标签合并；0–1
resource_type	ResourceType / "auto"	否	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400

返回: CloudinaryResource.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
asset_id	string
public_id	string
display_name	string
asset_folder	string
resource_type	string
type	string
format	string
version	number
version_id	string
bytes	number
etag	string
width	number
height	number
duration	number
pages	number
is_audio	boolean
original_filename	string
tags	array<string>
context	object
context.custom	object
created_at	string
url	string
secure_url	string
placeholder	boolean
existing	boolean
processing	object
processing.state	string
processing.kinds	object
processing.updated_at	string
done	boolean
upload_id	string

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/upload" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"file":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==","public_id":"walk-lib-r1-MDP-1791733789929-plain","tags":["docs"]}'

HTTP 200

{
  "asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
  "public_id": "walk-lib-r1-MDP-1791733789929-plain",
  "display_name": "walk-lib-r1-MDP-1791733789929-plain",
  "asset_folder": "",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791733810,
  "version_id": "fdf3c8cd40c2424d86e8397425a69857",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "created_at": "2026-10-11T15:50:10.842Z",
  "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
  "placeholder": false
}

删除素材

POST /cloudinary/v1_1/{library_id}/{resource_type}/destroy

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw / auto	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400

请求体

字段	类型	必填	说明
public_id	string	是	交付地址中的素材名称，可带路径

返回: DestroyResult.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
result	string

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/destroy" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"public_id":"docs/renamed"}'

HTTP 200

{
  "result": "ok"
}

重命名

POST /cloudinary/v1_1/{library_id}/{resource_type}/rename

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw / auto	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400

请求体

字段	类型	必填	说明
from_public_id	string	是	原 public_id
to_public_id	string	是	新 public_id
overwrite	boolean	否	是否覆盖同名素材

返回: CloudinaryResource.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
asset_id	string
public_id	string
display_name	string
asset_folder	string
resource_type	string
type	string
format	string
version	number
version_id	string
bytes	number
etag	string
width	number
height	number
duration	number
pages	number
is_audio	boolean
original_filename	string
tags	array<string>
context	object
context.custom	object
created_at	string
url	string
secure_url	string
placeholder	boolean
existing	boolean
processing	object
processing.state	string
processing.kinds	object
processing.updated_at	string

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/rename" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"from_public_id":"docs/pixel","to_public_id":"docs/renamed"}'

HTTP 200

{
  "asset_id": "9339cdae93804c0c8c65d5189ef1f646",
  "public_id": "docs/renamed",
  "display_name": "Sample image",
  "asset_folder": "examples",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791538418,
  "version_id": "35848c1529994e338e7aa634a1c13d9c",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "context": {
    "custom": {
      "alt": "Sample"
    }
  },
  "created_at": "2026-10-09T09:33:38.899Z",
  "url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/renamed.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/renamed.png",
  "placeholder": false
}

修改标签

POST /cloudinary/v1_1/{library_id}/{resource_type}/tags

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw / auto	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400

请求体

字段	类型	必填	说明
public_ids	string[]	是	素材 public_id 列表
tag	string	否	标签名称
command	add / remove / replace / remove_all	是	标签或上下文操作

返回: PublicIds.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
public_ids	array<string>

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/tags" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"public_ids":["docs/pixel"],"tag":"sample","command":"add"}'

HTTP 200

{
  "public_ids": [
    "docs/pixel"
  ]
}

修改上下文

POST /cloudinary/v1_1/{library_id}/{resource_type}/context

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw / auto	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400

请求体

字段	类型	必填	说明
public_ids	string[]	是	素材 public_id 列表
context	string / object	否	自定义文字键值；PATCH 整体替换，传 {} 清空
command	add / remove_all	是	标签或上下文操作

返回: PublicIds.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
public_ids	array<string>

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/context" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"public_ids":["docs/pixel"],"context":"alt=Sample","command":"add"}'

HTTP 200

{
  "public_ids": [
    "docs/pixel"
  ]
}

更新素材

POST /cloudinary/v1_1/{library_id}/{resource_type}/explicit

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw / auto	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400

请求体

字段	类型	必填	说明
public_id	string	是	交付地址中的素材名称，可带路径
tags	string / string[]	否	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	string / object	否	自定义文字键值；PATCH 整体替换，传 {} 清空

返回: CloudinaryResource.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
asset_id	string
public_id	string
display_name	string
asset_folder	string
resource_type	string
type	string
format	string
version	number
version_id	string
bytes	number
etag	string
width	number
height	number
duration	number
pages	number
is_audio	boolean
original_filename	string
tags	array<string>
context	object
context.custom	object
created_at	string
url	string
secure_url	string
placeholder	boolean
existing	boolean
processing	object
processing.state	string
processing.kinds	object
processing.updated_at	string

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/image/explicit" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"public_id":"docs/pixel","tags":["docs"]}'

HTTP 200

{
  "asset_id": "9339cdae93804c0c8c65d5189ef1f646",
  "public_id": "docs/pixel",
  "display_name": "Sample image",
  "asset_folder": "examples",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791538418,
  "version_id": "35848c1529994e338e7aa634a1c13d9c",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "context": {
    "custom": {
      "alt": "Sample"
    }
  },
  "created_at": "2026-10-09T09:33:38.899Z",
  "url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png",
  "placeholder": false
}

CloudinaryResource

字段	类型	必填	说明
asset_id	AssetId	是	素材 ID
public_id	string	是	交付地址中的素材名称，可带路径
display_name	string	是	显示名称
asset_folder	string	是	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
resource_type	ResourceType	是	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
type	DeliveryType	是	资源或事件类型
format	string	是	文件格式
version	number	是	交付版本号
version_id	string	是	版本标识
bytes	number	是	文件字节数
etag	string	是	文件校验标识
width	number	否	宽度像素
height	number	否	高度像素
duration	number	否	时长秒数
pages	number	否	文档页数
is_audio	boolean	否	是否为音频
original_filename	string	否	原文件名称
tags	string[]	是	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	object	否	自定义文字键值；PATCH 整体替换，传 {} 清空
created_at	IsoTimestamp	是	创建时间
url	string	是	原文件地址
secure_url	string	是	HTTPS 交付地址
placeholder	false	是	固定为 false
existing	boolean	否	未覆盖时是否返回已有素材
processing	Processing	否	整体与各项理解状态

DestroyResult

字段	类型	必填	说明
result	ok / not found	是	操作结果

PublicIds

字段	类型	必填	说明
public_ids	string[]	是	素材 public_id 列表

ChunkPending

字段	类型	必填	说明
done	false	是	已完成数量；分片响应中表示是否完成
upload_id	string	是	分片会话标识

ChunkComplete

字段	类型	必填	说明
asset_id	AssetId	是	素材 ID
public_id	string	是	交付地址中的素材名称，可带路径
display_name	string	是	显示名称
asset_folder	string	是	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
resource_type	ResourceType	是	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
type	DeliveryType	是	资源或事件类型
format	string	是	文件格式
version	number	是	交付版本号
version_id	string	是	版本标识
bytes	number	是	文件字节数
etag	string	是	文件校验标识
width	number	否	宽度像素
height	number	否	高度像素
duration	number	否	时长秒数
pages	number	否	文档页数
is_audio	boolean	否	是否为音频
original_filename	string	否	原文件名称
tags	string[]	是	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	object	否	自定义文字键值；PATCH 整体替换，传 {} 清空
created_at	IsoTimestamp	是	创建时间
url	string	是	原文件地址
secure_url	string	是	HTTPS 交付地址
placeholder	false	是	固定为 false
existing	boolean	否	未覆盖时是否返回已有素材
processing	Processing	否	整体与各项理解状态

字段	类型	必填	说明
done	true	是	已完成数量；分片响应中表示是否完成

上传与管理

本页内容