# platform +material-upload

> **前置条件：** 先阅读 [`../cai-shared/SKILL.md`](../../cai-shared/SKILL.md) 了解认证、全局参数和安全规则。

上传本地素材文件（图片/视频/PDF）到素材库。内部自动完成两步流程：先调用 create 接口获取上传凭证，再上传文件内容。服务端支持秒传：若文件 MD5 已存在则直接返回，无需重复上传。

## 命令

```bash
# 上传图片
cai-cli platform +material-upload --file /path/to/image.png --yes

# 上传视频
cai-cli platform +material-upload --file /path/to/video.mp4 --yes

# 上传 PDF
cai-cli platform +material-upload --file /path/to/document.pdf --yes

# 预览请求（不实际发送）
cai-cli platform +material-upload --file /path/to/image.jpg --dry-run
```

## 参数

| Flag | 类型 | 必填 | 说明 |
|------|------|------|------|
| `--file` | string | ✓ | 本地文件路径 |
| `--yes` | bool | — | 跳过确认提示，直接执行上传（**默认始终加上此参数**）|

## 支持格式

| 扩展名 | 类型 | fileType |
|--------|------|----------|
| `.jpg` `.jpeg` `.png` | 图片 | `2` |
| `.mp4` `.mov` `.avi` | 视频 | `3` |
| `.pdf` | PDF | `4` |

最大文件大小：**10MB**

## 响应字段（`data` 对象）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 素材 ID |
| `url` | string | CDN 访问地址 |
| `fileType` | int | 文件类型：`2`=图片，`3`=视频，`4`=PDF |
| `fileName` | string | 文件名（不含扩展名） |
| `fileSize` | string | 文件大小（字节，字符串类型） |
| `statusText` | string | 状态：`"上传成功"` / `"审核中"` |
| `width` | int | 宽度（像素；图片/视频有） |
| `height` | int | 高度（像素；图片/视频有） |
| `duration` | string | 视频时长（秒，字符串类型；仅视频有） |

## 注意事项

- **秒传**：服务端按文件 MD5 去重，同一文件重复上传会直接返回已有素材记录，不重复计费存储。
- **审核**：视频和 PDF 上传后进入审核流程，`statusText` 为 `"审核中"`；图片直接 `"上传成功"`。
- **文件大小**：超过 10MB 会在本地校验阶段报错，不会发起网络请求。

## 风险等级

`write`（写入操作，使用 `--yes` 跳过确认，直接执行）

## 参考

- [cai-platform](../SKILL.md) — 平台管理全部命令
- [cai-shared](../../cai-shared/SKILL.md) — 认证和全局参数