Cloudinary 兼容接口

2026-10-20

Cloudinary 兼容接口
上传与管理
资源管理
检索
交付与变换

Cloudinary 兼容接口

用官方 Cloudinary SDK 管理一个素材库。只需以下三项配置；API Key 作为 Bearer 凭据发送。

https://api.deepraxis.ai/cloudinary/v1_1/{library_id}

配置	值
cloud_name	library_id
oauth_token	API Key
upload_prefix	https://api.deepraxis.ai/cloudinary

Node.js

npm install cloudinary@2

import { v2 as cloudinary } from "cloudinary";

cloudinary.config({
  cloud_name: process.env.LIBRARY_ID,
  oauth_token: process.env.PRAXIS_API_KEY,
  upload_prefix: "https://api.deepraxis.ai/cloudinary",
});

Python

python -m pip install cloudinary

import os
import cloudinary
import cloudinary.uploader
import cloudinary.api

cloudinary.config(
    cloud_name=os.environ["LIBRARY_ID"],
    oauth_token=os.environ["PRAXIS_API_KEY"],
    upload_prefix="https://api.deepraxis.ai/cloudinary",
)

操作	支持
GET /v1_1/{library_id}/resources/visual_search	支持
POST /v1_1/{library_id}/resources/visual_search	支持
POST /v1_1/{library_id}/{resource_type}/upload	支持
POST /v1_1/{library_id}/{resource_type}/destroy	支持
POST /v1_1/{library_id}/{resource_type}/rename	支持
POST /v1_1/{library_id}/{resource_type}/tags	支持
POST /v1_1/{library_id}/{resource_type}/context	支持
POST /v1_1/{library_id}/{resource_type}/explicit	支持
GET /v1_1/{library_id}/resources/search	支持
POST /v1_1/{library_id}/resources/search	支持
GET /v1_1/{library_id}/resources	支持
GET /v1_1/{library_id}/resources/{resource_type}	支持
GET /v1_1/{library_id}/resources/{resource_type}/upload	支持
GET /v1_1/{library_id}/resources/{asset_id}	支持
GET /v1_1/{library_id}/resources/by_asset_ids	支持
GET /v1_1/{library_id}/resources/by_asset_folder	支持
GET /v1_1/{library_id}/resources/{resource_type}/tags/{tag}	支持
GET /v1_1/{library_id}/resources/{resource_type}/context	支持
GET /v1_1/{library_id}/resources/{resource_type}/upload/{public_id}	支持
POST /v1_1/{library_id}/resources/by_asset_ids	支持
POST /v1_1/{library_id}/resources/{resource_type}/upload/{public_id}	支持
PUT /v1_1/{library_id}/resources/{resource_type}/upload/{public_id}	支持
DELETE /v1_1/{library_id}/resources/{resource_type}/upload	支持
DELETE /v1_1/{library_id}/resources/{resource_type}/tags/{tag}	支持
GET /v1_1/{library_id}/tags/{resource_type}	支持
GET /v1_1/{library_id}/folders	支持
GET /v1_1/{library_id}/folders/{folder}	支持
POST /v1_1/{library_id}/folders/{folder}	支持
PUT /v1_1/{library_id}/folders/{folder}	支持
DELETE /v1_1/{library_id}/folders/{folder}	支持
GET /v1_1/{library_id}/ping	支持
GET /v1_1/{library_id}/usage	部分支持
GET /v1_1/{library_id}/usage/{date}	部分支持

不支持的操作

端点	HTTP
upload_presets	400
metadata_fields	400
transformations	400
streaming_profiles	400
upload_mappings	400
triggers	400
derived_resources	400
relations	400
restore	400
backups	400
text	400
sprite	400
multi	400
explode	400
generate_archive	400
create_slideshow	400
download_backup_asset	400
folders/search	400

上述端点错误消息含 is not supported；private 与 authenticated 交付类型也返回 400。

上传参数

参数	支持
file	支持
public_id	支持
public_id_prefix	支持
display_name	支持
asset_folder	支持
use_filename	支持
unique_filename	支持
use_filename_as_display_name	支持
filename_override	支持
overwrite	支持
tags	支持
context	支持
auto_tagging	部分支持
resource_type	支持
eager	不支持
eager_async	不支持
eager_notification_url	不支持
async	不支持
notification_url	不支持
upload_preset	不支持
moderation	不支持
detection	不支持
ocr	不支持
raw_convert	不支持
background_removal	不支持
categorization	不支持
transformation	不支持
responsive_breakpoints	不支持
proxy	不支持
backup	不支持
return_delete_token	不支持
access_control	不支持
access_mode	不支持
metadata	不支持
face_coordinates	不支持
custom_coordinates	不支持
regions	不支持
quality_analysis	不支持
accessibility_analysis	不支持
cinemagraph_analysis	不支持
media_metadata	不支持
phash	不支持
colors	不支持
faces	不支持
image_metadata	不支持
exif	不支持
invalidate	不支持
type	不支持

不支持的上传参数返回 400，消息为 Unsupported upload parameter: 参数名。

错误体与错误码

上传与管理

官方 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

响应

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	是	交付地址中的素材名称，可带路径

响应

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	否	是否覆盖同名素材

响应

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

响应

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

响应

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 整体替换，传 {} 清空

响应

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	是	已完成数量；分片响应中表示是否完成

资源管理

Admin 管理当前库的素材。usage 只返回当前存储量和素材数。

指南 →

基础地址与鉴权

读取素材

GET /cloudinary/v1_1/{library_id}/resources

参数	位置	类型	说明
library_id	path	string	库 ID
prefix	query	string	—
public_ids	query	string[]	素材 public_id 列表
asset_ids	query	string[]	—
asset_folder	query	string	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
key	query	string	—
value	query	string	—
tags	query	string	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	query	string	自定义文字键值；PATCH 整体替换，传 {} 清空
direction	query	string	—
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

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

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "resources": [
    {
      "asset_id": "9dfa312ef9bc4b00816339b598b1152c",
      "public_id": "walk-lib-r1-MDP-1791733789929-tagged",
      "display_name": "walk-lib-r1-MDP-1791733789929-tagged",
      "asset_folder": "",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791733815,
      "version_id": "26cb8171caa5431b8373ad417fd71e32",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "processing": {
        "state": "processing",
        "kinds": {
          "embedding": "running",
          "visual": "failed",
          "tagging": "failed"
        },
        "updated_at": "2026-10-11T15:50:21.512Z"
      },
      "created_at": "2026-10-11T15:50:15.996Z",
      "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
      "placeholder": false
    },
    {
      "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",
      "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
    }
  ]
}

读取素材

GET /cloudinary/v1_1/{library_id}/resources/{resource_type}

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
prefix	query	string	—
public_ids	query	string[]	素材 public_id 列表
asset_ids	query	string[]	—
asset_folder	query	string	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
key	query	string	—
value	query	string	—
tags	query	string	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	query	string	自定义文字键值；PATCH 整体替换，传 {} 清空
direction	query	string	—
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

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

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "resources": [
    {
      "asset_id": "e5f3de0d8609482d8b351894b133c8cb",
      "public_id": "examples/pixel",
      "display_name": "pixel",
      "asset_folder": "examples",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791538435,
      "version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "created_at": "2026-10-09T09:33:55.536Z",
      "url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "placeholder": false
    }
  ]
}

读取素材

GET /cloudinary/v1_1/{library_id}/resources/{resource_type}/upload

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
prefix	query	string	—
public_ids	query	string[]	素材 public_id 列表
asset_ids	query	string[]	—
asset_folder	query	string	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
key	query	string	—
value	query	string	—
tags	query	string	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	query	string	自定义文字键值；PATCH 整体替换，传 {} 清空
direction	query	string	—
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

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

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/upload" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "resources": [
    {
      "asset_id": "e5f3de0d8609482d8b351894b133c8cb",
      "public_id": "examples/pixel",
      "display_name": "pixel",
      "asset_folder": "examples",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791538435,
      "version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "created_at": "2026-10-09T09:33:55.536Z",
      "url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "placeholder": false
    }
  ]
}

读取素材

GET /cloudinary/v1_1/{library_id}/resources/{asset_id}

参数	位置	类型	说明
library_id	path	string	库 ID
asset_id	path	string	素材 ID
prefix	query	string	—
public_ids	query	string[]	素材 public_id 列表
asset_ids	query	string[]	—
asset_folder	query	string	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
key	query	string	—
value	query	string	—
tags	query	string	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	query	string	自定义文字键值；PATCH 整体替换，传 {} 清空
direction	query	string	—
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: 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 GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/9dfa312ef9bc4b00816339b598b1152c" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "asset_id": "9dfa312ef9bc4b00816339b598b1152c",
  "public_id": "walk-lib-r1-MDP-1791733789929-tagged",
  "display_name": "walk-lib-r1-MDP-1791733789929-tagged",
  "asset_folder": "",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791733815,
  "version_id": "26cb8171caa5431b8373ad417fd71e32",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "processing": {
    "state": "processing",
    "kinds": {
      "embedding": "running",
      "visual": "failed",
      "tagging": "failed"
    },
    "updated_at": "2026-10-11T15:50:21.512Z"
  },
  "created_at": "2026-10-11T15:50:15.996Z",
  "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
  "placeholder": false
}

读取素材

GET /cloudinary/v1_1/{library_id}/resources/by_asset_ids

参数	位置	类型	说明
library_id	path	string	库 ID
prefix	query	string	—
public_ids	query	string[]	素材 public_id 列表
asset_ids	query	string[]	—
asset_folder	query	string	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
key	query	string	—
value	query	string	—
tags	query	string	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	query	string	自定义文字键值；PATCH 整体替换，传 {} 清空
direction	query	string	—
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

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

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/by_asset_ids?asset_ids[]=e5f3de0d8609482d8b351894b133c8cb" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "resources": [
    {
      "asset_id": "e5f3de0d8609482d8b351894b133c8cb",
      "public_id": "examples/pixel",
      "display_name": "pixel",
      "asset_folder": "examples",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791538435,
      "version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "created_at": "2026-10-09T09:33:55.536Z",
      "url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "placeholder": false
    }
  ]
}

读取素材

GET /cloudinary/v1_1/{library_id}/resources/by_asset_folder

参数	位置	类型	说明
library_id	path	string	库 ID
prefix	query	string	—
public_ids	query	string[]	素材 public_id 列表
asset_ids	query	string[]	—
asset_folder	query	string	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
key	query	string	—
value	query	string	—
tags	query	string	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	query	string	自定义文字键值；PATCH 整体替换，传 {} 清空
direction	query	string	—
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

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

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/by_asset_folder?asset_folder=examples" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "resources": [
    {
      "asset_id": "e5f3de0d8609482d8b351894b133c8cb",
      "public_id": "examples/pixel",
      "display_name": "pixel",
      "asset_folder": "examples",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791538435,
      "version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "created_at": "2026-10-09T09:33:55.536Z",
      "url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "placeholder": false
    }
  ]
}

读取素材

GET /cloudinary/v1_1/{library_id}/resources/{resource_type}/tags/{tag}

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
tag	path	string	标签名称
prefix	query	string	—
public_ids	query	string[]	素材 public_id 列表
asset_ids	query	string[]	—
asset_folder	query	string	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
key	query	string	—
value	query	string	—
tags	query	string	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	query	string	自定义文字键值；PATCH 整体替换，传 {} 清空
direction	query	string	—
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

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

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/tags/docs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "resources": [
    {
      "asset_id": "e5f3de0d8609482d8b351894b133c8cb",
      "public_id": "examples/pixel",
      "display_name": "pixel",
      "asset_folder": "examples",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791538435,
      "version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "created_at": "2026-10-09T09:33:55.536Z",
      "url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "placeholder": false
    }
  ]
}

读取素材

GET /cloudinary/v1_1/{library_id}/resources/{resource_type}/context

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
prefix	query	string	—
public_ids	query	string[]	素材 public_id 列表
asset_ids	query	string[]	—
asset_folder	query	string	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
key	query	string	—
value	query	string	—
tags	query	string	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	query	string	自定义文字键值；PATCH 整体替换，传 {} 清空
direction	query	string	—
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

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

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/context?key=alt&value=sample" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "resources": [
    {
      "asset_id": "e5f3de0d8609482d8b351894b133c8cb",
      "public_id": "examples/pixel",
      "display_name": "pixel",
      "asset_folder": "examples",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791538435,
      "version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "created_at": "2026-10-09T09:33:55.536Z",
      "url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "placeholder": false
    }
  ]
}

读取素材

GET /cloudinary/v1_1/{library_id}/resources/{resource_type}/upload/{public_id}

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
public_id	path	string	交付地址中的素材名称，可带路径
prefix	query	string	—
public_ids	query	string[]	素材 public_id 列表
asset_ids	query	string[]	—
asset_folder	query	string	组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
key	query	string	—
value	query	string	—
tags	query	string	素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
context	query	string	自定义文字键值；PATCH 整体替换，传 {} 清空
direction	query	string	—
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: 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 GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/upload/examples/pixel" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "asset_id": "e5f3de0d8609482d8b351894b133c8cb",
  "public_id": "examples/pixel",
  "display_name": "pixel",
  "asset_folder": "examples",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791538435,
  "version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "context": {
    "custom": {
      "alt": "sample"
    }
  },
  "created_at": "2026-10-09T09:33:55.536Z",
  "url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
  "placeholder": false
}

按 ID 读取

POST /cloudinary/v1_1/{library_id}/resources/by_asset_ids

参数	位置	类型	说明
library_id	path	string	库 ID

字段	类型	必填	说明
asset_ids	string[]	是	—
max_results	integer	否	最多 500；检索默认 100，Admin 默认 10
next_cursor	string	否	下一页游标；没有时为 null 或省略

响应

HTTP 200

Successful response.

application/json

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

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/by_asset_ids" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"asset_ids":["e5f3de0d8609482d8b351894b133c8cb"]}'

HTTP 200

{
  "resources": [
    {
      "asset_id": "e5f3de0d8609482d8b351894b133c8cb",
      "public_id": "examples/pixel",
      "display_name": "pixel",
      "asset_folder": "examples",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791538435,
      "version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "created_at": "2026-10-09T09:33:55.536Z",
      "url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
      "placeholder": false
    }
  ]
}

更新素材

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

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
public_id	path	string	交付地址中的素材名称，可带路径

响应

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}/resources/image/upload/examples/pixel" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"display_name":"Sample image"}'

HTTP 200

{
  "asset_id": "e5f3de0d8609482d8b351894b133c8cb",
  "public_id": "examples/pixel",
  "display_name": "Sample image",
  "asset_folder": "examples",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791538435,
  "version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "context": {
    "custom": {
      "alt": "sample"
    }
  },
  "created_at": "2026-10-09T09:33:55.536Z",
  "url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
  "placeholder": false
}

更新素材

PUT /cloudinary/v1_1/{library_id}/resources/{resource_type}/upload/{public_id}

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
public_id	path	string	交付地址中的素材名称，可带路径

响应

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 PUT "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/upload/examples/pixel" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"tags":["docs"]}'

HTTP 200

{
  "asset_id": "e5f3de0d8609482d8b351894b133c8cb",
  "public_id": "examples/pixel",
  "display_name": "Sample image",
  "asset_folder": "examples",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791538435,
  "version_id": "001fb6336c9b4a4c9e4597b69fdec3cd",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "context": {
    "custom": {
      "alt": "sample"
    }
  },
  "created_at": "2026-10-09T09:33:55.536Z",
  "url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_b762c40631bd42278a204cd0370fed36/image/upload/v1791538435/examples/pixel.png",
  "placeholder": false
}

删除素材

DELETE /cloudinary/v1_1/{library_id}/resources/{resource_type}/upload

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
public_ids	query	string[]	素材 public_id 列表
prefix	query	string	—
all	query	boolean	—
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: DeletedResources.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
deleted	object
partial	boolean
next_cursor	string

curl -X DELETE "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/upload" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"prefix":"imported/"}'

HTTP 200

{
  "deleted": {},
  "partial": false
}

删除素材

DELETE /cloudinary/v1_1/{library_id}/resources/{resource_type}/tags/{tag}

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
tag	path	string	标签名称
public_ids	query	string[]	素材 public_id 列表
prefix	query	string	—
all	query	boolean	—
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: DeletedResources.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
deleted	object
partial	boolean
next_cursor	string

curl -X DELETE "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/image/tags/remove-me" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

HTTP 200

{
  "deleted": {
    "tagged/pixel": "deleted"
  },
  "partial": false
}

列出标签

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

参数	位置	类型	说明
library_id	path	string	库 ID
resource_type	path	image / video / raw	image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
prefix	query	string	—
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: Tags.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
tags	array<string>
next_cursor	string

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/tags/image" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "tags": [
    "docs"
  ]
}

列出文件夹

GET /cloudinary/v1_1/{library_id}/folders

参数	位置	类型	说明
library_id	path	string	库 ID
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: CompatFolders.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
folders	array<object>
folders[].name	string
folders[].path	string
total_count	number
next_cursor	string

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/folders" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "folders": [
    {
      "name": "examples",
      "path": "examples"
    }
  ],
  "total_count": 1
}

列出文件夹

GET /cloudinary/v1_1/{library_id}/folders/{folder}

参数	位置	类型	说明
library_id	path	string	库 ID
folder	path	string	—
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略

返回: CompatFolders.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
folders	array<object>
folders[].name	string
folders[].path	string
total_count	number
next_cursor	string

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/folders/examples" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "folders": [],
  "total_count": 0
}

创建文件夹

POST /cloudinary/v1_1/{library_id}/folders/{folder}

参数	位置	类型	说明
library_id	path	string	库 ID
folder	path	string	—

返回: FolderResult.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
$	object

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

HTTP 200

{
  "success": true,
  "path": "sample"
}

重命名文件夹

PUT /cloudinary/v1_1/{library_id}/folders/{folder}

参数	位置	类型	说明
library_id	path	string	库 ID
folder	path	string	—

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
$	object

删除文件夹

DELETE /cloudinary/v1_1/{library_id}/folders/{folder}

参数	位置	类型	说明
library_id	path	string	库 ID
folder	path	string	—

返回: FolderResult.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
$	object

curl -X DELETE "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/folders/sample" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

HTTP 200

{
  "success": true,
  "path": "sample"
}

检查连接

GET /cloudinary/v1_1/{library_id}/ping

参数	位置	类型	说明
library_id	path	string	库 ID

返回: Ping.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
status	string

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/ping" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "status": "ok"
}

读取用量

GET /cloudinary/v1_1/{library_id}/usage

参数	位置	类型	说明
library_id	path	string	库 ID

返回: Usage.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
storage	object
storage.usage	number
objects	object
objects.usage	number

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/usage" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "storage": {
    "usage": 70
  },
  "objects": {
    "usage": 1
  }
}

读取用量

GET /cloudinary/v1_1/{library_id}/usage/{date}

参数	位置	类型	说明
library_id	path	string	库 ID
date	path	string	—

返回: Usage.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
storage	object
storage.usage	number
objects	object
objects.usage	number

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/usage/2026-10-09" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "storage": {
    "usage": 70
  },
  "objects": {
    "usage": 1
  }
}

ResourcePage

字段	类型	必填	说明
resources	SearchResource[]	是	本页素材
next_cursor	string	否	下一页游标；没有时为 null 或省略

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	否	整体与各项理解状态

DeletedResources

字段	类型	必填	说明
deleted	object	是	删除结果
partial	boolean	是	是否还有未处理的后续页
next_cursor	string	否	下一页游标；没有时为 null 或省略

CompatFolders

字段	类型	必填	说明
folders	object[]	是	文件夹列表
total_count	number	是	匹配总数
next_cursor	string	否	下一页游标；没有时为 null 或省略

FolderResult

字段	类型	必填	说明

Ping

字段	类型	必填	说明
status	"ok"	是	资源状态

Usage

字段	类型	必填	说明
storage	object	是	存储字节用量
objects	object	是	素材数量

检索

指南 →

表达式检索仅支持以下子集。不支持的语法或字段返回 HTTP 400 INVALID_EXPRESSION；兼容错误体只包含消息。默认省略 tags 与 context；需要时用 with_field 请求。

语法	含义
AND / OR / NOT / - / ( )	布尔组合；相邻条件默认 AND
field:value / field=value	字段匹配
bytes > 1000 / width >= 160	数值比较；也支持 height、duration
created_at >= 2026-01-01 / uploaded_at > 7d	日期或相对时间，支持 d/w/m/y
tags:docs / context.alt:"sample image"	标签和自定义文字
public_id:docs*	仅末尾通配符
"sample image"	短语
sunset	裸词：在 public_id、display_name、tags、context 以及理解得到的描述、图片文字、转写中做全文匹配，不区分大小写
~ / ^ / [a TO z] / prefix / ab	不支持，返回 400

字段名不区分大小写（RESOURCE_TYPE:image 等同 resource_type:image）；resource_type、type、format 的值不区分大小写；tags、context 等其他字段的值区分大小写。空表达式返回全部素材；无法解析的表达式返回 400 INVALID_EXPRESSION。

查询字段: asset_id, resource_type, type, format, public_id, asset_folder, display_name, tags, bytes, width, height, duration, created_at, uploaded_at, context.<key>.

排序字段: created_at, public_id, display_name, bytes, uploaded_at.

统计字段: resource_type, format, asset_folder, processing_state. 指南 →

基础地址与鉴权

库的 search.image 为 true 时可用；不支持的库返回 LIBRARY_INVALID_STATE。图片仅接受 JPEG、PNG、WebP、GIF，解码后最大 10 MiB。每个素材返回最高分命中，视频定位到最佳帧。qwen3-vl-embedding 的图片相似度门槛为 0.35。标定来自 2026-10-10 的测试：同图变体 0.82–0.96，同类场景 0.38–0.66，无关图片最高 0.34。

image_asset_id、image_file（multipart）、image_url、text 必须且只能传一个。text 使用纯语义检索；返回 { "resources": [...] }。image_url 只接受本库交付 URL，不抓取外部 URL；外部 URL 返回 400「不支持抓取外部 URL」。

响应

HTTP 200

Successful response.

application/json

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

以图搜图

POST /cloudinary/v1_1/{library_id}/resources/visual_search

参数	位置	类型	说明
library_id	path	string	库 ID

请求体

字段	类型	必填	说明
image_asset_id	string	否	本库素材 ID
image_url	string	否	仅接受本库交付 URL，不支持抓取外部 URL
image_file	string	否	JPEG、PNG、WebP 或 GIF 文件，最大 10 MiB
text	string	否	自然语言查询，使用语义检索
max_results	integer	否	最多 500；检索默认 100，Admin 默认 10
filter	string	否	表达式筛选条件

返回: VisualResources.

响应

HTTP 200

Successful response.

application/json

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

表达式检索

GET /cloudinary/v1_1/{library_id}/resources/search

参数	位置	类型	说明
library_id	path	string	库 ID
expression	query	string	结构化查询表达式；空表达式返回全部素材
sort_by	query	string	排序字段与方向
max_results	query	integer	最多 500；检索默认 100，Admin 默认 10
next_cursor	query	string	下一页游标；没有时为 null 或省略
with_field	query	string[]	额外返回 tags 或 context
aggregate	query	string[]	统计字段

返回: CompatExpressionSearchResult.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
total_count	number
time	number
next_cursor	string
resources	array<object>
resources[].asset_id	string
resources[].public_id	string
resources[].display_name	string
resources[].asset_folder	string
resources[].resource_type	string
resources[].type	string
resources[].format	string
resources[].version	number
resources[].version_id	string
resources[].bytes	number
resources[].etag	string
resources[].width	number
resources[].height	number
resources[].duration	number
resources[].pages	number
resources[].is_audio	boolean
resources[].original_filename	string
resources[].tags	array<string>
resources[].context	object
resources[].created_at	string
resources[].url	string
resources[].secure_url	string
resources[].placeholder	boolean
resources[].existing	boolean
resources[].processing	object
aggregations	object

curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/search?expression=tags%3Adocs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

HTTP 200

{
  "total_count": 1,
  "time": 0,
  "resources": [
    {
      "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",
      "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
    }
  ]
}

表达式检索

POST /cloudinary/v1_1/{library_id}/resources/search

参数	位置	类型	说明
library_id	path	string	库 ID

请求体

字段	类型	必填	说明
expression	string	否	结构化查询表达式；空表达式返回全部素材
sort_by	object[]	否	排序字段与方向
max_results	integer	否	最多 500；检索默认 100，Admin 默认 10
next_cursor	string	否	下一页游标；没有时为 null 或省略
with_field	"tags" / "context"[]	否	额外返回 tags 或 context
aggregate	AggregateField[]	否	统计字段

返回: CompatExpressionSearchResult.

响应

HTTP 200

Successful response.

application/json

名称	类型	说明
total_count	number
time	number
next_cursor	string
resources	array<object>
resources[].asset_id	string
resources[].public_id	string
resources[].display_name	string
resources[].asset_folder	string
resources[].resource_type	string
resources[].type	string
resources[].format	string
resources[].version	number
resources[].version_id	string
resources[].bytes	number
resources[].etag	string
resources[].width	number
resources[].height	number
resources[].duration	number
resources[].pages	number
resources[].is_audio	boolean
resources[].original_filename	string
resources[].tags	array<string>
resources[].context	object
resources[].created_at	string
resources[].url	string
resources[].secure_url	string
resources[].placeholder	boolean
resources[].existing	boolean
resources[].processing	object
aggregations	object

curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/search" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"expression":"tags:docs"}'

HTTP 200

{
  "total_count": 2,
  "time": 0,
  "resources": [
    {
      "asset_id": "9dfa312ef9bc4b00816339b598b1152c",
      "public_id": "walk-lib-r1-MDP-1791733789929-tagged",
      "display_name": "walk-lib-r1-MDP-1791733789929-tagged",
      "asset_folder": "",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791733815,
      "version_id": "26cb8171caa5431b8373ad417fd71e32",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "processing": {
        "state": "processing",
        "kinds": {
          "embedding": "running",
          "visual": "failed",
          "tagging": "failed"
        },
        "updated_at": "2026-10-11T15:50:21.512Z"
      },
      "created_at": "2026-10-11T15:50:15.996Z",
      "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
      "placeholder": false
    },
    {
      "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",
      "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
    }
  ]
}

VisualResources

字段	类型	必填	说明
resources	CloudinaryResource[]	是	本页素材

CompatExpressionSearchResult

字段	类型	必填	说明
total_count	number	是	匹配总数
time	number	是	检索耗时，整数毫秒，由服务端测得
next_cursor	string	否	下一页游标；没有时为 null 或省略
resources	SearchResource[]	是	本页素材
aggregations	object	否	按请求字段统计

SearchResource

字段	类型	必填	说明
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	否	整体与各项理解状态

交付与变换

指南 →

用上传响应的 secure_url 读取原文件，在 upload 与版本之间插入变换。

https://media-develop.praxisusercontent.com/{library_id}/{resource_type}/upload/{transformation}/v{version}/{public_id}.{format}

原文件省略 transformation 及其后斜杠。仅接受以下白名单；其它变换返回错误。

参数	允许值
w_	160, 320, 640, 1280
c_	fill, fit, limit, scale, pad
g_	auto, center
f_	auto, jpg, png, webp, avif
q_	auto, auto:good, auto:eco
dpr_	1, 2
so_	视频秒数，扩展名 .jpg；源文件不超过 100 MiB

w_160,c_fit
w_320,c_fill,g_center,f_webp,q_auto,dpr_2

用户内容安全

交付使用独立的可注册域 praxisusercontent.com，与 API 和登录域隔离：Develop 为 media-develop.praxisusercontent.com，生产为 media.praxisusercontent.com。URL 路径形状不变，交付不携带任何 cookie。

只允许 GET 和 HEAD；其他方法返回 405。
不向上游转发 cookie 和凭据，响应移除 Set-Cookie。
所有响应都带 X-Content-Type-Options: nosniff。
HTML、SVG、XML、JavaScript 类内容都带 Content-Security-Policy: sandbox 和 Content-Disposition: attachment。
支持 Range 请求，部分内容返回 206。