Praxis文档
控制台
Cloudinary

资源管理

端点与支持范围。

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

指南 →

基础地址与鉴权

读取素材

GET /cloudinary/v1_1/{library_id}/resources

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

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

名称类型说明
resourcesarray<object>
resources[].asset_idstring
resources[].public_idstring
resources[].display_namestring
resources[].asset_folderstring
resources[].resource_typestring
resources[].typestring
resources[].formatstring
resources[].versionnumber
resources[].version_idstring
resources[].bytesnumber
resources[].etagstring
resources[].widthnumber
resources[].heightnumber
resources[].durationnumber
resources[].pagesnumber
resources[].is_audioboolean
resources[].original_filenamestring
resources[].tagsarray<string>
resources[].contextobject
resources[].created_atstring
resources[].urlstring
resources[].secure_urlstring
resources[].placeholderboolean
resources[].existingboolean
resources[].processingobject
next_cursorstring
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_idpathstring库 ID
resource_typepathimage / video / rawimage、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
prefixquerystring—
public_idsquerystring[]素材 public_id 列表
asset_idsquerystring[]—
asset_folderquerystring组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
keyquerystring—
valuequerystring—
tagsquerystring素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
contextquerystring自定义文字键值；PATCH 整体替换，传 {} 清空
directionquerystring—
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

名称类型说明
resourcesarray<object>
resources[].asset_idstring
resources[].public_idstring
resources[].display_namestring
resources[].asset_folderstring
resources[].resource_typestring
resources[].typestring
resources[].formatstring
resources[].versionnumber
resources[].version_idstring
resources[].bytesnumber
resources[].etagstring
resources[].widthnumber
resources[].heightnumber
resources[].durationnumber
resources[].pagesnumber
resources[].is_audioboolean
resources[].original_filenamestring
resources[].tagsarray<string>
resources[].contextobject
resources[].created_atstring
resources[].urlstring
resources[].secure_urlstring
resources[].placeholderboolean
resources[].existingboolean
resources[].processingobject
next_cursorstring
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_idpathstring库 ID
resource_typepathimage / video / rawimage、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
prefixquerystring—
public_idsquerystring[]素材 public_id 列表
asset_idsquerystring[]—
asset_folderquerystring组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
keyquerystring—
valuequerystring—
tagsquerystring素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
contextquerystring自定义文字键值；PATCH 整体替换，传 {} 清空
directionquerystring—
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

名称类型说明
resourcesarray<object>
resources[].asset_idstring
resources[].public_idstring
resources[].display_namestring
resources[].asset_folderstring
resources[].resource_typestring
resources[].typestring
resources[].formatstring
resources[].versionnumber
resources[].version_idstring
resources[].bytesnumber
resources[].etagstring
resources[].widthnumber
resources[].heightnumber
resources[].durationnumber
resources[].pagesnumber
resources[].is_audioboolean
resources[].original_filenamestring
resources[].tagsarray<string>
resources[].contextobject
resources[].created_atstring
resources[].urlstring
resources[].secure_urlstring
resources[].placeholderboolean
resources[].existingboolean
resources[].processingobject
next_cursorstring
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_idpathstring库 ID
asset_idpathstring素材 ID
prefixquerystring—
public_idsquerystring[]素材 public_id 列表
asset_idsquerystring[]—
asset_folderquerystring组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
keyquerystring—
valuequerystring—
tagsquerystring素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
contextquerystring自定义文字键值；PATCH 整体替换，传 {} 清空
directionquerystring—
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: CloudinaryResource.

响应

HTTP 200

Successful response.

application/json

名称类型说明
asset_idstring
public_idstring
display_namestring
asset_folderstring
resource_typestring
typestring
formatstring
versionnumber
version_idstring
bytesnumber
etagstring
widthnumber
heightnumber
durationnumber
pagesnumber
is_audioboolean
original_filenamestring
tagsarray<string>
contextobject
context.customobject
created_atstring
urlstring
secure_urlstring
placeholderboolean
existingboolean
processingobject
processing.statestring
processing.kindsobject
processing.updated_atstring
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_idpathstring库 ID
prefixquerystring—
public_idsquerystring[]素材 public_id 列表
asset_idsquerystring[]—
asset_folderquerystring组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
keyquerystring—
valuequerystring—
tagsquerystring素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
contextquerystring自定义文字键值；PATCH 整体替换，传 {} 清空
directionquerystring—
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

名称类型说明
resourcesarray<object>
resources[].asset_idstring
resources[].public_idstring
resources[].display_namestring
resources[].asset_folderstring
resources[].resource_typestring
resources[].typestring
resources[].formatstring
resources[].versionnumber
resources[].version_idstring
resources[].bytesnumber
resources[].etagstring
resources[].widthnumber
resources[].heightnumber
resources[].durationnumber
resources[].pagesnumber
resources[].is_audioboolean
resources[].original_filenamestring
resources[].tagsarray<string>
resources[].contextobject
resources[].created_atstring
resources[].urlstring
resources[].secure_urlstring
resources[].placeholderboolean
resources[].existingboolean
resources[].processingobject
next_cursorstring
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_idpathstring库 ID
prefixquerystring—
public_idsquerystring[]素材 public_id 列表
asset_idsquerystring[]—
asset_folderquerystring组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
keyquerystring—
valuequerystring—
tagsquerystring素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
contextquerystring自定义文字键值；PATCH 整体替换，传 {} 清空
directionquerystring—
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

名称类型说明
resourcesarray<object>
resources[].asset_idstring
resources[].public_idstring
resources[].display_namestring
resources[].asset_folderstring
resources[].resource_typestring
resources[].typestring
resources[].formatstring
resources[].versionnumber
resources[].version_idstring
resources[].bytesnumber
resources[].etagstring
resources[].widthnumber
resources[].heightnumber
resources[].durationnumber
resources[].pagesnumber
resources[].is_audioboolean
resources[].original_filenamestring
resources[].tagsarray<string>
resources[].contextobject
resources[].created_atstring
resources[].urlstring
resources[].secure_urlstring
resources[].placeholderboolean
resources[].existingboolean
resources[].processingobject
next_cursorstring
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_idpathstring库 ID
resource_typepathimage / video / rawimage、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
tagpathstring标签名称
prefixquerystring—
public_idsquerystring[]素材 public_id 列表
asset_idsquerystring[]—
asset_folderquerystring组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
keyquerystring—
valuequerystring—
tagsquerystring素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
contextquerystring自定义文字键值；PATCH 整体替换，传 {} 清空
directionquerystring—
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

名称类型说明
resourcesarray<object>
resources[].asset_idstring
resources[].public_idstring
resources[].display_namestring
resources[].asset_folderstring
resources[].resource_typestring
resources[].typestring
resources[].formatstring
resources[].versionnumber
resources[].version_idstring
resources[].bytesnumber
resources[].etagstring
resources[].widthnumber
resources[].heightnumber
resources[].durationnumber
resources[].pagesnumber
resources[].is_audioboolean
resources[].original_filenamestring
resources[].tagsarray<string>
resources[].contextobject
resources[].created_atstring
resources[].urlstring
resources[].secure_urlstring
resources[].placeholderboolean
resources[].existingboolean
resources[].processingobject
next_cursorstring
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_idpathstring库 ID
resource_typepathimage / video / rawimage、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
prefixquerystring—
public_idsquerystring[]素材 public_id 列表
asset_idsquerystring[]—
asset_folderquerystring组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
keyquerystring—
valuequerystring—
tagsquerystring素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
contextquerystring自定义文字键值；PATCH 整体替换，传 {} 清空
directionquerystring—
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

名称类型说明
resourcesarray<object>
resources[].asset_idstring
resources[].public_idstring
resources[].display_namestring
resources[].asset_folderstring
resources[].resource_typestring
resources[].typestring
resources[].formatstring
resources[].versionnumber
resources[].version_idstring
resources[].bytesnumber
resources[].etagstring
resources[].widthnumber
resources[].heightnumber
resources[].durationnumber
resources[].pagesnumber
resources[].is_audioboolean
resources[].original_filenamestring
resources[].tagsarray<string>
resources[].contextobject
resources[].created_atstring
resources[].urlstring
resources[].secure_urlstring
resources[].placeholderboolean
resources[].existingboolean
resources[].processingobject
next_cursorstring
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_idpathstring库 ID
resource_typepathimage / video / rawimage、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
public_idpathstring交付地址中的素材名称，可带路径
prefixquerystring—
public_idsquerystring[]素材 public_id 列表
asset_idsquerystring[]—
asset_folderquerystring组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
keyquerystring—
valuequerystring—
tagsquerystring素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
contextquerystring自定义文字键值；PATCH 整体替换，传 {} 清空
directionquerystring—
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: CloudinaryResource.

响应

HTTP 200

Successful response.

application/json

名称类型说明
asset_idstring
public_idstring
display_namestring
asset_folderstring
resource_typestring
typestring
formatstring
versionnumber
version_idstring
bytesnumber
etagstring
widthnumber
heightnumber
durationnumber
pagesnumber
is_audioboolean
original_filenamestring
tagsarray<string>
contextobject
context.customobject
created_atstring
urlstring
secure_urlstring
placeholderboolean
existingboolean
processingobject
processing.statestring
processing.kindsobject
processing.updated_atstring
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_idpathstring库 ID

请求体

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

返回: ResourcePage.

响应

HTTP 200

Successful response.

application/json

名称类型说明
resourcesarray<object>
resources[].asset_idstring
resources[].public_idstring
resources[].display_namestring
resources[].asset_folderstring
resources[].resource_typestring
resources[].typestring
resources[].formatstring
resources[].versionnumber
resources[].version_idstring
resources[].bytesnumber
resources[].etagstring
resources[].widthnumber
resources[].heightnumber
resources[].durationnumber
resources[].pagesnumber
resources[].is_audioboolean
resources[].original_filenamestring
resources[].tagsarray<string>
resources[].contextobject
resources[].created_atstring
resources[].urlstring
resources[].secure_urlstring
resources[].placeholderboolean
resources[].existingboolean
resources[].processingobject
next_cursorstring
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_idpathstring库 ID
resource_typepathimage / video / rawimage、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
public_idpathstring交付地址中的素材名称，可带路径

请求体

字段类型必填说明
display_namestring否显示名称
asset_folderstring否组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
tagsstring[]否素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
contextobject否自定义文字键值；PATCH 整体替换，传 {} 清空

返回: CloudinaryResource.

响应

HTTP 200

Successful response.

application/json

名称类型说明
asset_idstring
public_idstring
display_namestring
asset_folderstring
resource_typestring
typestring
formatstring
versionnumber
version_idstring
bytesnumber
etagstring
widthnumber
heightnumber
durationnumber
pagesnumber
is_audioboolean
original_filenamestring
tagsarray<string>
contextobject
context.customobject
created_atstring
urlstring
secure_urlstring
placeholderboolean
existingboolean
processingobject
processing.statestring
processing.kindsobject
processing.updated_atstring
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_idpathstring库 ID
resource_typepathimage / video / rawimage、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
public_idpathstring交付地址中的素材名称，可带路径

请求体

字段类型必填说明
display_namestring否显示名称
asset_folderstring否组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
tagsstring[]否素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
contextobject否自定义文字键值；PATCH 整体替换，传 {} 清空

返回: CloudinaryResource.

响应

HTTP 200

Successful response.

application/json

名称类型说明
asset_idstring
public_idstring
display_namestring
asset_folderstring
resource_typestring
typestring
formatstring
versionnumber
version_idstring
bytesnumber
etagstring
widthnumber
heightnumber
durationnumber
pagesnumber
is_audioboolean
original_filenamestring
tagsarray<string>
contextobject
context.customobject
created_atstring
urlstring
secure_urlstring
placeholderboolean
existingboolean
processingobject
processing.statestring
processing.kindsobject
processing.updated_atstring
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_idpathstring库 ID
resource_typepathimage / video / rawimage、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
public_idsquerystring[]素材 public_id 列表
prefixquerystring—
allqueryboolean—
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: DeletedResources.

响应

HTTP 200

Successful response.

application/json

名称类型说明
deletedobject
partialboolean
next_cursorstring
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_idpathstring库 ID
resource_typepathimage / video / rawimage、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
tagpathstring标签名称
public_idsquerystring[]素材 public_id 列表
prefixquerystring—
allqueryboolean—
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: DeletedResources.

响应

HTTP 200

Successful response.

application/json

名称类型说明
deletedobject
partialboolean
next_cursorstring
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_idpathstring库 ID
resource_typepathimage / video / rawimage、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
prefixquerystring—
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: Tags.

响应

HTTP 200

Successful response.

application/json

名称类型说明
tagsarray<string>
next_cursorstring
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_idpathstring库 ID
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: CompatFolders.

响应

HTTP 200

Successful response.

application/json

名称类型说明
foldersarray<object>
folders[].namestring
folders[].pathstring
total_countnumber
next_cursorstring
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_idpathstring库 ID
folderpathstring—
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
next_cursorquerystring下一页游标；没有时为 null 或省略

返回: CompatFolders.

响应

HTTP 200

Successful response.

application/json

名称类型说明
foldersarray<object>
folders[].namestring
folders[].pathstring
total_countnumber
next_cursorstring
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_idpathstring库 ID
folderpathstring—

返回: 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_idpathstring库 ID
folderpathstring—

请求体

字段类型必填说明
to_folderstring是目标文件夹路径

返回: FolderResult.

响应

HTTP 200

Successful response.

application/json

名称类型说明
$object

删除文件夹

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

参数位置类型说明
library_idpathstring库 ID
folderpathstring—

返回: 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_idpathstring库 ID

返回: Ping.

响应

HTTP 200

Successful response.

application/json

名称类型说明
statusstring
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_idpathstring库 ID

返回: Usage.

响应

HTTP 200

Successful response.

application/json

名称类型说明
storageobject
storage.usagenumber
objectsobject
objects.usagenumber
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_idpathstring库 ID
datepathstring—

返回: Usage.

响应

HTTP 200

Successful response.

application/json

名称类型说明
storageobject
storage.usagenumber
objectsobject
objects.usagenumber
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

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

CloudinaryResource

字段类型必填说明
asset_idAssetId是素材 ID
public_idstring是交付地址中的素材名称，可带路径
display_namestring是显示名称
asset_folderstring是组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
resource_typeResourceType是image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
typeDeliveryType是资源或事件类型
formatstring是文件格式
versionnumber是交付版本号
version_idstring是版本标识
bytesnumber是文件字节数
etagstring是文件校验标识
widthnumber否宽度像素
heightnumber否高度像素
durationnumber否时长秒数
pagesnumber否文档页数
is_audioboolean否是否为音频
original_filenamestring否原文件名称
tagsstring[]是素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
contextobject否自定义文字键值；PATCH 整体替换，传 {} 清空
created_atIsoTimestamp是创建时间
urlstring是原文件地址
secure_urlstring是HTTPS 交付地址
placeholderfalse是固定为 false
existingboolean否未覆盖时是否返回已有素材
processingProcessing否整体与各项理解状态

DeletedResources

字段类型必填说明
deletedobject是删除结果
partialboolean是是否还有未处理的后续页
next_cursorstring否下一页游标；没有时为 null 或省略

Tags

字段类型必填说明
tagsstring[]是素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
next_cursorstring否下一页游标；没有时为 null 或省略

CompatFolders

字段类型必填说明
foldersobject[]是文件夹列表
total_countnumber是匹配总数
next_cursorstring否下一页游标；没有时为 null 或省略

FolderResult

字段类型必填说明

Ping

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

Usage

字段类型必填说明
storageobject是存储字节用量
objectsobject是素材数量

上传与管理

端点与支持范围。

检索

端点与支持范围。

导出
本页 Markdown本节 Markdown整本 PDF

本页内容

读取素材响应HTTP 200读取素材响应HTTP 200读取素材响应HTTP 200读取素材响应HTTP 200读取素材响应HTTP 200读取素材响应HTTP 200读取素材响应HTTP 200读取素材响应HTTP 200读取素材响应HTTP 200按 ID 读取请求体响应HTTP 200更新素材请求体响应HTTP 200更新素材请求体响应HTTP 200删除素材响应HTTP 200删除素材响应HTTP 200列出标签响应HTTP 200列出文件夹响应HTTP 200列出文件夹响应HTTP 200创建文件夹响应HTTP 200重命名文件夹请求体响应HTTP 200删除文件夹响应HTTP 200检查连接响应HTTP 200读取用量响应HTTP 200读取用量响应HTTP 200ResourcePageCloudinaryResourceDeletedResourcesTagsCompatFoldersFolderResultPingUsage