Seedance 视频素材管理接口接入指南

Seedance 2.0 支持图生视频、首尾帧生视频、多模态参考生视频、参考视频/音频生视频等多种模式。这些模式需要提前准备参考素材（人像、参考图、参考视频、参考音频）。

本指南介绍如何通过素材管理接口将参考素材入库，并在生成视频时引用这些素材。

接口基地址: https://api.numspirit.com/v1

前提条件

请牢记 SiliEvo 中转服务的核心两要素：

中转基地址 (Base URL): https://api.numspirit.com/

安全秘钥 (API Key / Token): 通过平台官网 https://numspirit.com 或联系 15685255305 申请，形如 sk-silievo-xxxxxxxx

所有素材接口均需在请求头携带鉴权信息，且按 API Key 做数据隔离（一个 Key 看不到另一个 Key 的素材）。

Authorization: Bearer sk-silievo-xxxxxxxx

使用流程总览

⚠️⚠️ 最重要提醒：素材中凡是含人物形象的，务必先上传到素材集合入库，再在生视频时引用；直接用外部裸 URL 会被 Seedance 校验拒绝（该模型会校验素材中是否有人物形象，人脸/人物参考必须走素材库通道）。

素材集合用于归档同类参考素材（如「女主参考」「产品图库」）。日常使用优先复用已有的集合，不必每次都新建：

① 确认集合 → ② 上传素材到集合 → ③ 生成视频时引用素材（asset:// 或 URL）

步骤	接口	说明
① 确认集合	`GET /v1/material-collections`	先查自己已有的集合：已有合适的就直接复用它的 id；没有（或需要新分类）才 `POST /v1/material-collections` 新建一个
② 上传素材	`POST /v1/materials/upload`	把图片/视频/音频上传到上面确定的集合，返回素材 id
③ 引用素材	见「与生视频打通」	优先用 `asset://<素材id>` 填到生成请求（推荐）；直接传素材 HTTP 地址大概率被拒或报错

💡 日常使用建议：
首次使用：新建一个集合 → 上传素材 → 之后一直复用这个集合 id；
后续使用：直接 GET /v1/material-collections 查已有集合，选合适的，把新素材 upload 进去即可用；
集合名会随场景归类（如「女主参考」「产品图库」），建议按用途建集合，避免素材堆在一个集合里难以管理。

接口概览

素材集合（Material Collections）

功能	接口路径	方法	说明
创建集合	`/v1/material-collections`	POST	新建素材集合
集合列表	`/v1/material-collections`	GET	分页查询我的集合
集合详情	`/v1/material-collections/{id}`	GET	查询单个集合
更新集合	`/v1/material-collections/{id}`	PATCH	改名 / 改描述
删除集合	`/v1/material-collections/{id}`	DELETE	删除集合（其下素材一并软删）

素材（Material Assets）

功能	接口路径	方法	说明
上传素材	`/v1/materials/upload`	POST	上传图片/视频/音频到集合
素材列表	`/v1/materials`	GET	分页查询素材（可按集合/类型过滤）
素材详情	`/v1/materials/{id}`	GET	查询单个素材
更新素材	`/v1/materials/{id}`	PATCH	改素材名
删除素材	`/v1/materials/{id}`	DELETE	删除素材

一、素材集合管理

1. 创建素材集合 POST /v1/material-collections

请求参数

参数	类型	必填	说明
`name`	string	是	集合名称，≤64 字符
`description`	string	否	集合描述，≤300 字符

cURL 示例

响应示例

{
  "success": true,
  "data": {
    "id": "group-20260806100927-srqmv",
    "name": "女主参考",
    "description": "女主首帧/多模态参考图集合",
    "material_count": 0,
    "created_at": "2026-08-06 10:09:27",
    "updated_at": "2026-08-06 10:09:27"
  }
}

记下返回的 data.id（集合 ID），后续上传素材的 collection_id 要用它。
💡 仅首次使用或需要新分类时才调本接口；日常复用已有集合见「使用流程总览」。

2. 集合列表 GET /v1/material-collections

请求参数

参数	类型	必填	说明
`name`	string	否	按名称模糊搜索
`page`	integer	否	页码，默认 1
`size`	integer	否	每页条数，默认 20

cURL 示例

响应示例

{
  "success": true,
  "data": {
    "list": [
      {
        "id": "group-20260806100927-srqmv",
        "name": "女主参考",
        "description": "女主首帧/多模态参考图集合",
        "material_count": 3,
        "created_at": "2026-08-06 10:09:27",
        "updated_at": "2026-08-06 10:09:27"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20
  }
}

💡 日常使用先调本接口，从返回的 list[].id 里挑一个已有的集合 id，直接用于上传素材；material_count 可判断集合里已有多少素材。

3. 集合详情 GET /v1/material-collections/{id}

cURL 示例

响应示例

{
  "success": true,
  "data": {
    "id": "group-20260806100927-srqmv",
    "name": "女主参考",
    "description": "女主首帧/多模态参考图集合",
    "material_count": 3,
    "created_at": "2026-08-06 10:09:27",
    "updated_at": "2026-08-06 10:09:27"
  }
}

4. 更新集合 PATCH /v1/material-collections/{id}

只传想改的字段即可，name / description 都可省略。

cURL 示例

响应示例

{
  "success": true,
  "data": {
    "id": "group-20260806100927-srqmv",
    "name": "女主参考v2",
    "description": "女主首帧/多模态参考图集合",
    "material_count": 3,
    "created_at": "2026-08-06 10:09:27",
    "updated_at": "2026-08-06 10:10:11"
  }
}

5. 删除集合 DELETE /v1/material-collections/{id}

删除集合会级联软删该集合下所有素材（不可恢复，请谨慎）。

cURL 示例

响应示例

{
  "success": true,
  "data": {}
}

二、素材管理

6. 上传素材 POST /v1/materials/upload（multipart）

请求参数

参数	类型	必填	说明
`file`	file	是	要上传的文件（图片/视频/音频）
`collection_id`	string	是	归属集合 ID
`name`	string	否	素材名，≤255 字符

支持的文件类型

类型	MIME 类型	大小上限
图片	`image/png`, `image/jpeg`, `image/jpg`, `image/webp`, `image/gif`, `image/bmp`, `image/tiff`, `image/heic`, `image/heif`	30MB
视频	`video/mp4`, `video/webm`, `video/quicktime`	200MB
音频	`audio/mpeg`, `audio/wav`, `audio/mp3`, `audio/aac`, `audio/ogg`, `audio/flac`, `audio/x-wav`, `audio/x-m4a`	15MB

cURL 示例

响应示例

{
  "success": true,
  "data": {
    "id": "asset-20260806101453-abc12",
    "collection_id": "group-20260806100927-srqmv",
    "asset_type": "Image",
    "status": "Active",
    "name": "女主首帧",
    "mime": "image/jpeg",
    "size_bytes": 5212396,
    "url": "https://numspirit-media.oss-cn-shenzhen.aliyuncs.com/users/15/uploads/2026-08/5e0dd81d083941319bd5393c1e80ff74.jpg?Expires=...",
    "created_at": "2026-08-06 10:14:53",
    "updated_at": "2026-08-06 10:14:53"
  }
}

⚠️ 关于 status：方舟处理素材是异步的。首次返回可能为 Processing（服务端会轮询最多 2 分钟），此时素材还不能用于生成视频；稍后 GET /v1/materials/{id} 刷新，status 变为 Active 即可引用。若为 Failed，响应会带 error_message 说明原因。

🔑 引用方式（推荐用 asset）：
✅ 推荐：asset://<素材id> —— 走方舟素材库原生引用，稳定不依赖公网 URL 有效期，所有素材都建议用这种方式
⚠️ 不推荐：直接填返回的 HTTP url —— 大概率会被模型拒绝或报错（尤其含人物形象、或素材未在素材库中），仅在特殊场景（如纯风景等无人物素材且确认可用）才尝试

7. 素材列表 GET /v1/materials

请求参数

参数	类型	必填	说明
`collection_id`	string	否	只查该集合下的素材
`asset_type`	string	否	类型过滤：`image` / `video` / `audio`（大小写不敏感）
`page`	integer	否	页码，默认 1
`size`	integer	否	每页条数，默认 20

cURL 示例

响应示例

{
  "success": true,
  "data": {
    "list": [
      {
        "id": "asset-20260806101453-abc12",
        "collection_id": "group-20260806100927-srqmv",
        "asset_type": "Image",
        "status": "Active",
        "name": "女主首帧",
        "mime": "image/jpeg",
        "size_bytes": 5212396,
        "url": "https://numspirit-media.oss-cn-shenzhen.aliyuncs.com/users/15/uploads/2026-08/5e0dd81d083941319bd5393c1e80ff74.jpg?Expires=...",
        "created_at": "2026-08-06 10:14:53",
        "updated_at": "2026-08-06 10:14:53"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20
  }
}

8. 素材详情 GET /v1/materials/{id}

cURL 示例

响应示例

{
  "success": true,
  "data": {
    "id": "asset-20260806101453-abc12",
    "collection_id": "group-20260806100927-srqmv",
    "asset_type": "Image",
    "status": "Active",
    "name": "女主首帧",
    "mime": "image/jpeg",
    "size_bytes": 5212396,
    "url": "https://numspirit-media.oss-cn-shenzhen.aliyuncs.com/users/15/uploads/2026-08/5e0dd81d083941319bd5393c1e80ff74.jpg?Expires=...",
    "created_at": "2026-08-06 10:14:53",
    "updated_at": "2026-08-06 10:14:53"
  }
}

9. 更新素材名 PATCH /v1/materials/{id}

cURL 示例

响应示例

{
  "success": true,
  "data": {
    "id": "asset-20260806101453-abc12",
    "collection_id": "group-20260806100927-srqmv",
    "asset_type": "Image",
    "status": "Active",
    "name": "女主首帧-改版",
    "mime": "image/jpeg",
    "size_bytes": 5212396,
    "url": "https://numspirit-media.oss-cn-shenzhen.aliyuncs.com/users/15/uploads/2026-08/5e0dd81d083941319bd5393c1e80ff74.jpg?Expires=...",
    "created_at": "2026-08-06 10:14:53",
    "updated_at": "2026-08-06 10:15:02"
  }
}

10. 删除素材 DELETE /v1/materials/{id}

删除后不可恢复。

cURL 示例

响应示例

{
  "success": true,
  "data": {}
}

三、与生视频打通（重点）

上传成功的素材，等 status = Active 后即可在 POST /v1/videos/generations 中引用。

⚠️ 含人物形象的素材必须走素材库：Seedance 会校验素材中是否有人物形象。人脸/人物参考图、真人出镜的视频等一律先上传到素材集合，再用下面的方式引用，否则直接填外部 URL 会被模型拒绝。

两种引用方式：

✅ asset 引用（推荐）：把素材 id 拼 asset://<素材id> 填入，走方舟素材库原生解析。建议所有素材都用这种方式——含人物形象的素材务必用它（不经过公网下载，同时满足方舟的素材校验），通用素材用它也最稳定，不受 URL 有效期限制。

⚠️ URL 引用（不推荐）：把 upload / detail 返回的 data.url 原样填入。直接传素材 HTTP 地址大概率会被模型拒绝或报错（尤其含人物形象、或素材未在素材库中的情况），仅在确无其它办法时尝试。

图生视频（首帧）

首尾帧生视频

多模态参考生视频（3~9 张参考图）

参考视频 / 参考音频生视频

⚠️ 注意：seedance-2-0-mini 模型不支持参考视频/音频。
生成视频的完整参数说明见《seedance视频接入.md》。

四、注意事项

⚠️ 人物素材必须入库：Seedance 会校验素材中是否有人物形象。凡是含人物形象（人脸/真人出镜等）的素材，必须先上传到素材集合，再以 asset://<素材id> 引用；直接传外部裸 URL 大概率会被模型拒绝。素材库通道同时满足方舟的素材校验与人脸/形象一致性要求。

素材状态：上传后素材先 Processing，需等 Active 才能用于生成；Failed 表示入库失败（见 error_message）。后台任务会持续同步状态，稍后刷新即可。

数据隔离：素材按 API Key 隔离，A Key 无法读取/操作 B Key 的集合与素材（未命中一律返回 404）。

⚠️ 优先用 asset:// 引用：直接传素材 HTTP 地址大概率会被模型拒绝或报错，建议一律用 asset://<素材id> 引用（走方舟素材库原生解析）。返回的 url 仅是签名 URL（有效期 24 小时），只作兜底参考。

大小限制：图片 30MB、视频 200MB、音频 15MB；单个 API Key 最多 100 个集合、500 个素材。

级联删除：删除集合会一并软删其下所有素材，操作前请确认。

五、错误码速查表

场景	HTTP 状态码	message
集合不存在 / 非本人集合	404	`素材集合不存在`
素材不存在 / 非本人素材	404	`素材不存在`
集合名缺失	400	`集合名称不能为空`
集合名超长	400	`集合名称不能超过64个字符`
描述超长	400	`集合描述不能超过300个字符`
素材名超长	400	`素材名称不能超过255个字符`
空文件	400	`文件不能为空`
类型不支持	400	`不支持的文件类型: xxx，仅支持图片、视频、音频文件`
文件超限	400	`文件大小超过限制（30MB / 200MB / 15MB）`
集合数达上限	409	`素材集合数量已达上限（100个）`
素材数达上限	409	`素材数量已达上限（500个）`
认证失败	401	Key 无效或未携带

技术支持: 如有任何问题，请联系客服微信或加入服务群获取帮助。

seedance视频素材接入文档

Seedance 视频素材管理接口接入指南#

前提条件#

使用流程总览#

接口概览#

素材集合（Material Collections）#

素材（Material Assets）#

一、素材集合管理#

1. 创建素材集合 POST /v1/material-collections#

请求参数#

cURL 示例#

响应示例#

2. 集合列表 GET /v1/material-collections#

请求参数#

cURL 示例#

响应示例#

3. 集合详情 GET /v1/material-collections/{id}#

cURL 示例#

响应示例#

4. 更新集合 PATCH /v1/material-collections/{id}#

cURL 示例#

响应示例#

5. 删除集合 DELETE /v1/material-collections/{id}#

cURL 示例#

响应示例#

二、素材管理#

6. 上传素材 POST /v1/materials/upload（multipart）#

请求参数#

支持的文件类型#

cURL 示例#

响应示例#

7. 素材列表 GET /v1/materials#

请求参数#

cURL 示例#

响应示例#

8. 素材详情 GET /v1/materials/{id}#

cURL 示例#

响应示例#

9. 更新素材名 PATCH /v1/materials/{id}#

cURL 示例#

响应示例#

10. 删除素材 DELETE /v1/materials/{id}#

cURL 示例#

响应示例#

三、与生视频打通（重点）#

图生视频（首帧）#

首尾帧生视频#

多模态参考生视频（3~9 张参考图）#

参考视频 / 参考音频生视频#

四、注意事项#

五、错误码速查表#

Seedance 视频素材管理接口接入指南

前提条件

使用流程总览

接口概览

素材集合（Material Collections）

素材（Material Assets）

一、素材集合管理

1. 创建素材集合 POST /v1/material-collections

请求参数

cURL 示例

响应示例

2. 集合列表 GET /v1/material-collections

请求参数

cURL 示例

响应示例

3. 集合详情 GET /v1/material-collections/{id}

cURL 示例

响应示例

4. 更新集合 PATCH /v1/material-collections/{id}

cURL 示例

响应示例

5. 删除集合 DELETE /v1/material-collections/{id}

cURL 示例

响应示例

二、素材管理

6. 上传素材 POST /v1/materials/upload（multipart）

请求参数

支持的文件类型

cURL 示例

响应示例

7. 素材列表 GET /v1/materials

请求参数

cURL 示例

响应示例

8. 素材详情 GET /v1/materials/{id}

cURL 示例

响应示例

9. 更新素材名 PATCH /v1/materials/{id}

cURL 示例

响应示例

10. 删除素材 DELETE /v1/materials/{id}

cURL 示例

响应示例

三、与生视频打通（重点）

图生视频（首帧）

首尾帧生视频

多模态参考生视频（3~9 张参考图）

参考视频 / 参考音频生视频

四、注意事项

五、错误码速查表