媒资与分类管理
素材上传、分类管理与任务回调：接口契约、鉴权方式与调用示例。
平台素材库用于管理视频生成、图生视频等任务的输入素材（参考图/参考视频），并提供按用户隔离的分类体系与任务完成回调。
接口概览
| 操作 | 方法与路径 | 鉴权 |
|---|---|---|
| 上传素材 | 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 选填：
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为公网可访问的素材地址，可直接填入视频生成的参考图字段
{
"id": 3,
"url": "https://api.gfw.net/uploads/materials/<user_id>/<md5>.png",
"kind": "image",
"mime": "image/png",
"size": 7933
}列表与删除
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"删除为软删除：记录与磁盘文件一并清理，列表立即不可见。
分类体系
分类按用户隔离，支持父子层级（两级），同级名称不可重复：
# 创建一级分类
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 字节），任务到达终态后平台上游会将结果原样回调到该地址。
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 直接用于参考图输入：
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}
}'