# 资源管理 (/docs/api/compatible/cloudinary/admin)



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

[指南 →](/docs/cloud/services/media/quickstart)

[基础地址与鉴权](/docs/api/compatible/cloudinary)

## 读取素材 [#读取素材]

`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 [#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 |  |

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

HTTP 200

```json
{
  "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
    }
  ]
}
```

## 读取素材 [#读取素材-1]

`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`.

### 响应 [#响应-1]

#### HTTP 200 [#http-200-1]

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

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

HTTP 200

```json
{
  "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
    }
  ]
}
```

## 读取素材 [#读取素材-2]

`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`.

### 响应 [#响应-2]

#### HTTP 200 [#http-200-2]

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

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

HTTP 200

```json
{
  "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
    }
  ]
}
```

## 读取素材 [#读取素材-3]

`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`.

### 响应 [#响应-3]

#### HTTP 200 [#http-200-3]

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

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

HTTP 200

```json
{
  "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
}
```

## 读取素材 [#读取素材-4]

`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`.

### 响应 [#响应-4]

#### HTTP 200 [#http-200-4]

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

```bash
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

```json
{
  "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
    }
  ]
}
```

## 读取素材 [#读取素材-5]

`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`.

### 响应 [#响应-5]

#### HTTP 200 [#http-200-5]

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

```bash
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

```json
{
  "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
    }
  ]
}
```

## 读取素材 [#读取素材-6]

`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`.

### 响应 [#响应-6]

#### HTTP 200 [#http-200-6]

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

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

HTTP 200

```json
{
  "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
    }
  ]
}
```

## 读取素材 [#读取素材-7]

`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`.

### 响应 [#响应-7]

#### HTTP 200 [#http-200-7]

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

```bash
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

```json
{
  "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
    }
  ]
}
```

## 读取素材 [#读取素材-8]

`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`.

### 响应 [#响应-8]

#### HTTP 200 [#http-200-8]

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

```bash
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

```json
{
  "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 读取 [#按-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 或省略 |

返回: `ResourcePage`.

### 响应 [#响应-9]

#### HTTP 200 [#http-200-9]

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

```bash
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

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

### 请求体 [#请求体-1]

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

返回: `CloudinaryResource`.

### 响应 [#响应-10]

#### HTTP 200 [#http-200-10]

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

```bash
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

```json
{
  "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
}
```

## 更新素材 [#更新素材-1]

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

### 请求体 [#请求体-2]

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

返回: `CloudinaryResource`.

### 响应 [#响应-11]

#### HTTP 200 [#http-200-11]

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

```bash
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

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

### 响应 [#响应-12]

#### HTTP 200 [#http-200-12]

Successful response.

**application/json**

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

```bash
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

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

## 删除素材 [#删除素材-1]

`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`.

### 响应 [#响应-13]

#### HTTP 200 [#http-200-13]

Successful response.

**application/json**

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

```bash
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

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

### 响应 [#响应-14]

#### HTTP 200 [#http-200-14]

Successful response.

**application/json**

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

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

HTTP 200

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

### 响应 [#响应-15]

#### HTTP 200 [#http-200-15]

Successful response.

**application/json**

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

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

HTTP 200

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

## 列出文件夹 [#列出文件夹-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`.

### 响应 [#响应-16]

#### HTTP 200 [#http-200-16]

Successful response.

**application/json**

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

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

HTTP 200

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

## 创建文件夹 [#创建文件夹]

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

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

返回: `FolderResult`.

### 响应 [#响应-17]

#### HTTP 200 [#http-200-17]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object |  |

```bash
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

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

## 重命名文件夹 [#重命名文件夹]

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

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

### 请求体 [#请求体-3]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| to_folder | string | 是 | 目标文件夹路径 |

返回: `FolderResult`.

### 响应 [#响应-18]

#### HTTP 200 [#http-200-18]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object |  |

## 删除文件夹 [#删除文件夹]

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

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

返回: `FolderResult`.

### 响应 [#响应-19]

#### HTTP 200 [#http-200-19]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| $ | object |  |

```bash
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

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

## 检查连接 [#检查连接]

`GET /cloudinary/v1_1/{library_id}/ping`

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

返回: `Ping`.

### 响应 [#响应-20]

#### HTTP 200 [#http-200-20]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| status | string |  |

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

HTTP 200

```json
{
  "status": "ok"
}
```

## 读取用量 [#读取用量]

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

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

返回: `Usage`.

### 响应 [#响应-21]

#### HTTP 200 [#http-200-21]

Successful response.

**application/json**

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

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

HTTP 200

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

## 读取用量 [#读取用量-1]

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

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

返回: `Usage`.

### 响应 [#响应-22]

#### HTTP 200 [#http-200-22]

Successful response.

**application/json**

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

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

HTTP 200

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

## ResourcePage [#resourcepage]

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

## CloudinaryResource [#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 [#deletedresources]

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

## Tags [#tags]

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

## CompatFolders [#compatfolders]

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

## FolderResult [#folderresult]

| 字段 | 类型 | 必填 | 说明 |
| -- | -- | -- | -- |

## Ping [#ping]

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

## Usage [#usage]

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