# 上传与管理 (/docs/api/compatible/cloudinary/upload)



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

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

上传接受文件字节、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 接受。

```javascript
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。

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

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

## 上传素材 [#上传素材]

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

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

### 请求体 [#请求体]

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

返回: `CloudinaryResource`.

### 响应 [#响应]

#### HTTP 200 [#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 |  |

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

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

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

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

返回: `DestroyResult`.

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

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

Successful response.

**application/json**

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

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

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

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

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

返回: `CloudinaryResource`.

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

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

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

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

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

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

返回: `PublicIds`.

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

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

Successful response.

**application/json**

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

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

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

### 请求体 [#请求体-4]

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

返回: `PublicIds`.

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

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

Successful response.

**application/json**

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

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

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

### 请求体 [#请求体-5]

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

返回: `CloudinaryResource`.

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

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

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}/image/explicit" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"public_id":"docs/pixel","tags":["docs"]}'
```

HTTP 200

```json
{
  "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 [#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 [#destroyresult]

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

## PublicIds [#publicids]

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

## ChunkPending [#chunkpending]

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

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