# 媒资与分类管理

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

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

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

| 操作 | 方法与路径 | 鉴权 |
| --- | --- | --- |
| 上传素材 | `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，不超过 10MB
- 视频：mp4 / webm / mov，不超过 50MB
- 同用户同内容自动去重（重复上传直接复用已有记录）
- 响应 `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}
  }'
```

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