媒资与分类管理

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

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

接口概览

操作	方法与路径	鉴权
上传素材	`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，不超过 30MB（参考图上游口径）
视频：mp4 / webm / mov，不超过 200MB

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

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

参考视频/音频单段时长不超过 15 秒（超长会被生成任务拒绝，可先剪辑截取）
参考素材数量上限按模型不同（详见视频生成的能力矩阵）：
- 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 为公网可访问的素材地址，可直接填入视频生成的参考图字段

{
  "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}
  }'

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

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 小时时效，请及时下载）。

相关文档：视频生成、模型与能力。

接口概览复制章节链接

上传素材复制章节链接

列表与删除复制章节链接

分类体系复制章节链接

任务完成回调复制章节链接