# 媒资与分类管理

素材上传、分类管理与任务回调：接口契约、鉴权方式与调用示例。

平台素材库用于管理视频生成、图生视频等任务的输入素材（参考图/参考视频），并提供按用户隔离的分类体系与任务完成回调。

## 接口概览 [#接口概览]

| 操作 | 方法与路径 | 鉴权 |
| --- | --- | --- |
| 上传素材 | `POST /v1/media` | API Key（Bearer） |
| 素材列表 | `GET /v1/media` | API Key（Bearer） |
| 删除素材 | `DELETE /v1/media/{id}` | API Key（Bearer） |
| 创建分类 | `POST /v1/media/categories` | API Key（Bearer） |
| 分类列表 | `GET /v1/media/categories` | API Key（Bearer） |
| 重命名分类 | `PUT /v1/media/categories/{id}` | API Key（Bearer） |
| 删除分类 | `DELETE /v1/media/categories/{id}` | API Key（Bearer） |
| 素材归类/取消 | `PUT /v1/media/{id}/category` | API Key（Bearer） |

站内控制台走同样的能力（Session 鉴权）：`/api/v1/user/upload/material`、`/api/v1/user/materials`、`/api/v1/user/materials/{id}`。

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

`multipart/form-data` 表单，字段 `file` 必填，`kind`（image/video）与 `category_id` 选填：

```bash
curl -X POST https://api.gfw.net/v1/media \
  -H "Authorization: Bearer $GFW_API_KEY" \
  -F "file=@reference.png" -F "kind=image" -F "category_id=42"
```

- 图片：jpg / jpeg / png / webp / gif / bmp，不超过 30MB（参考图上游口径）
- 视频：mp4 / webm / mov，不超过 200MB

上传大小限制按请求体整体计算（multipart 编码会带来少量开销），贴近上限的文件建议略留余量。

**用作参考视频时的上游约束**（与上传大小无关，生成阶段由模型侧校验）：

- 参考视频/音频单段时长**不超过 15 秒**（超长会被生成任务拒绝，可先剪辑截取）
- **参考素材数量上限按模型不同**（详见[视频生成的能力矩阵](/docs/video-generation)）：
  - `doubao-seedance-2-5-260628`：图 30 + 视频 10 + 音频 10（支持仅音频输入）
  - `doubao-seedance-2-0-260128` / `seedance-2.0-lite`：图 9 + 视频 3 + 音频 3
  - `wan3.0-video` / `wan3.0-video-prime`：图 10 + 视频 5 + 音频 5
  - `wan2.7`：单图（首帧）或两图（首尾帧）+ 视频续接
  - `happyhorse-1.1`：参考图 4 张
  - `minimax-h3` / `minimax-h3-fast`：图 9 + 视频 3 + 音频 3
- 平台按素材组合自动判定任务类型：1 图=图生视频、2 图=首尾帧、>2 图或含视频/音频=参考生视频

- 同用户同内容自动去重（重复上传直接复用已有记录）
- 响应 `data.url` 为公网可访问的素材地址，可直接填入视频生成的参考图字段

```json
{
  "id": 3,
  "url": "https://api.gfw.net/uploads/materials/<user_id>/<md5>.png",
  "kind": "image",
  "mime": "image/png",
  "size": 7933
}
```

## 列表与删除 [#列表与删除]

```bash
curl "https://api.gfw.net/v1/media?kind=image&category_id=42&page=1&page_size=20" \
  -H "Authorization: Bearer $GFW_API_KEY"

curl -X DELETE https://api.gfw.net/v1/media/3 \
  -H "Authorization: Bearer $GFW_API_KEY"
```

删除为软删除：记录与磁盘文件一并清理，列表立即不可见。

## 分类体系 [#分类体系]

分类按用户隔离，支持父子层级（两级），同级名称不可重复：

```bash
# 创建一级分类
curl -X POST https://api.gfw.net/v1/media/categories \
  -H "Authorization: Bearer $GFW_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "参考图片"}'

# 创建二级分类（parent_id 为一级分类 id）
curl -X POST https://api.gfw.net/v1/media/categories \
  -H "Authorization: Bearer $GFW_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "风景", "parent_id": 1}'

# 素材归类（category_id 传 0 或缺省为取消归类）
curl -X PUT https://api.gfw.net/v1/media/3/category \
  -H "Authorization: Bearer $GFW_API_KEY" -H "Content-Type: application/json" \
  -d '{"category_id": 2}'
```

删除分类时其下素材自动解绑（素材本身保留）；存在子分类时需先删除子分类。

## 任务完成回调 [#任务完成回调]

视频生成等异步任务支持完成回调：提交任务时携带 `parameters.notify_url`（http/https，不超过 1024 字节），任务到达终态后平台上游会将结果原样回调到该地址。

```bash
curl -X POST https://api.gfw.net/v1/video/generations \
  -H "Authorization: Bearer $GFW_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model",
    "content": [{"type": "text", "text": "日落下的海滩"}],
    "parameters": {
      "duration": 5,
      "aspect_ratio": "16:9",
      "notify_url": "https://your-service.com/hook/video-done"
    }
  }'
```

回调地址需公网可达；非法协议（非 http/https）或超长地址会在提交时被拒绝。

## 与视频生成的组合 [#与视频生成的组合]

上传素材后，把返回的 `url` 直接用于参考输入：

```bash
curl -X POST https://api.gfw.net/v1/video/generations \
  -H "Authorization: Bearer $GFW_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model",
    "content": [
      {"type": "text", "text": "让画面动起来"},
      {"type": "image_url", "image_url": {"url": "<素材上传返回的 url>"}}
    ],
    "parameters": {"duration": 5}
  }'
```

视频参考同理：把参考视频上传为素材（`kind=video`），将返回的 `url` 填入 `video_url` 输入（注意 15 秒时长约束）：

```bash
curl -X POST https://api.gfw.net/v1/video/generations \
  -H "Authorization: Bearer $GFW_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "content": [
      {"type": "text", "text": "参考这段视频的风格"},
      {"type": "video_url", "video_url": {"url": "<参考视频素材 url>"}}
    ],
    "parameters": {"duration": 5, "aspect_ratio": "16:9"}
  }'
```

Yike 系模型的成片地址为上游直通签名地址（约 6 小时时效，请及时下载）。

相关文档：[视频生成](/docs/video-generation)、[模型与能力](/docs/models)。