Seedance 素材库

网关代理 Seedance（即梦）素材库上游：素材/素材组按用户隔离，网关负责归属校验并替换上游鉴权。

通用说明

• Base URL：https://token.taiha.cn（本地开发为 http://localhost:3000）

• 认证（素材库接口）：

  Authorization: Bearer sk-xxxxxxxx

  使用 API 令牌（sk- 开头）。真人认证接口例外，见第 3 节。

• GET 列表接口参数：支持两种传参方式，任选其一——

  1. URL 查询串（推荐）：

     curl -G 'https://token.taiha.cn/api/seedance/proxy/assets' \
       -H 'Authorization: Bearer sk-xxx' \
       --data-urlencode 'GroupType=AIGC' \
       --data-urlencode 'PageSize=20'

  2. 官方风格 JSON 请求体（火山 ARK 结构，Filter 嵌套）：

     curl --request GET 'https://token.taiha.cn/api/seedance/proxy/assets/groups' \
       -H 'Authorization: Bearer sk-xxx' \
       -H 'Content-Type: application/json' \
       --data-raw '{"Filter":{"GroupType":"AIGC","GroupIds":["group-xxx"]},"PageNumber":1,"PageSize":10}'

     注意 GroupIds / Statuses 在请求体中是数组，在查询串中是逗号分隔字符串。两种方式混用时查询串优先。

• 错误格式（网关侧错误）：

  {
    "success": false,
    "error": { "message": "Name is required", "type": "seedance_proxy_error" }
  }

• 上游错误：状态码与响应体原样透传。

• ProjectName：上游不支持项目概念，所有接口均不支持该参数（传入会被忽略/剔除）。

• 分页：与官方一致支持两种方式，参数语义对齐官方——

  • 页码式：PageNumber（页码，从 1 开始）+ PageSize（每页条数，[1, 100]）
  • 游标式：NextToken（翻页凭证，取上次响应的 Result.NextToken，首次查询不传）+ MaxResults（每页条数，[1, 100]）

  行为规则（网关宽松兼容，不做互斥强校验）：

  • 两种方式可混用、可单传：NextToken 优先于 PageNumber，PageSize 优先于 MaxResults
  • 未传任何分页参数时默认每页 10 条（官方 MaxResults 缺省值）
  • NextToken 为空串或无效凭证时按 PageNumber（缺省 1）处理
  • 列表响应始终携带 Result.NextToken：还有下一页时非空，原样回传取下一页；空串表示已到最后一页
  • 与官方规范的差异：官方要求页码式与游标式互斥、PageNumber/PageSize 须同时传入、PageSize * PageNumber > 10000 时应改用 NextToken 深翻页——本网关不强制上述限制，按优先级取值即可

---

1. 素材组

1.1 创建素材组

POST /api/seedance/proxy/assets/groups

Request Body（JSON）：

字段	类型	必填	说明
Name	string	是	组名，1~64 字符
Description	string	否	组描述，最长 300 字符
GroupType	string	否	仅支持 AIGC（缺省）；真人素材组须经人脸认证获得，不能手动创建

校验规则：同一用户下 Name + GroupType 唯一，重复创建返回 400。

Request 示例：

curl -X POST 'https://token.taiha.cn/api/seedance/proxy/assets/groups' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-xxx' \
  -d '{"Name": "my-group", "Description": "第一个group"}'

Response 200（上游透传）：

{
  "Result": { "Id": "group-20260923104404-gnv27" }
}

错误：

状态码	message
400	Name is required / Name must be at most 64 characters / Description must be at most 300 characters
400	GroupType only supports AIGC
400	an asset group with the same Name and GroupType already exists
500	failed to check asset group / failed to record asset group
502	Seedance upstream unavailable

1.2 查询素材组列表

GET /api/seedance/proxy/assets/groups

Query 参数（也可放官方风格 JSON 请求体的 Filter 内，见通用说明）：

参数	必填	说明
GroupType	否	AIGC（缺省）/ LivenessFace
GroupIds	否	组 ID 列表，逗号分隔或重复传参；缺省查本人该类型全部组；传入须均为本人组，否则 403
Name	否	组名精确匹配，最长 64 字符（以网关建组记录为准）
SortBy	否	CreateTime（缺省）/ UpdateTime
SortOrder	否	Desc（缺省）/ Asc
NextToken	否	分页游标，取上次响应的 Result.NextToken，优先于 PageNumber
MaxResults	否	每页数量（官方游标分页参数），与 PageSize 等价，PageSize 优先，缺省 10
PageNumber	否	页码，缺省 1
PageSize	否	每页数量，1~100，缺省 10

Request 示例：

curl -G 'https://token.taiha.cn/api/seedance/proxy/assets/groups' \
  -H 'Authorization: Bearer sk-xxx' \
  --data-urlencode 'GroupType=AIGC' \
  --data-urlencode 'GroupIds=group-aaa,group-bbb' \
  --data-urlencode 'PageNumber=1' \
  --data-urlencode 'PageSize=20'

Response 200（官方结构，字段与官方 ListAssetGroups 对齐）：

{
  "Result": {
    "Items": [
      {
        "Id": "group-20260923104404-gnv27",
        "Name": "my-group",
        "Description": "第二个group",
        "GroupType": "AIGC",
        "CreateTime": "2026-09-23T10:44:04+08:00",
        "UpdateTime": "2026-09-23T10:44:04+08:00"
      }
    ],
    "NextToken": "",
    "TotalCount": 2
  }
}

说明：

• Result.NextToken：还有下一页时非空，原样回传取下一页；空串表示已到最后一页
• 上游优先；上游查询失败或无数据时自动回退网关数据库（以建组记录构造，UpdateTime 同 CreateTime）
• 上游 item 缺 Name 字段时以网关建组记录补齐；其余字段原样透传
• GroupType=LivenessFace 查询真人素材组（经人脸认证获得）

错误：400（参数校验）、403（GroupIds contain asset groups not belonging to you）、500、502

---

2. 素材

2.1 创建素材（异步接口）

POST /api/seedance/proxy/assets

Request Body（JSON）：

字段	类型	必填	说明
GroupId	string	是	本人素材组 ID（AIGC 组或 LivenessFace 组），否则 403
GroupType	string	否	网关侧参数：AIGC（缺省）/ LivenessFace，决定按哪类组校验归属；不透传上游
URL	string	是	素材文件地址（https），由上游校验
AssetType	string	是	Image / Video，由上游校验
Name	string	否	素材名称

其余字段原样透传上游；ProjectName 会被自动剔除。

Request 示例：

curl -X POST 'https://token.taiha.cn/api/seedance/proxy/assets' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-xxx' \
  -d '{
    "GroupId": "group-20260923114838-spsqh",
    "URL": "https://example-tos.cn-beijing.volcengine.com/asset-xxx.jpg",
    "Name": "pexels-photo-15213183",
    "AssetType": "Image"
  }'

Response 200（上游透传，异步任务受理）：

{
  "Result": { "Id": "asset-20260923120000-xxxxx" }
}

重要：创建为异步操作。拿到 Result.Id 后必须轮询 2.3 素材详情，直到 Result.Status 为 Active（成功）或 Failed（失败）。

错误：400（group_id is required...）、403（group_id does not belong to your asset groups）、502

2.2 查询素材列表

GET /api/seedance/proxy/assets

Query 参数（也可放官方风格 JSON 请求体的 Filter 内，见通用说明）：

参数	必填	说明
GroupType	否	AIGC（缺省）/ LivenessFace
GroupIds	否	组 ID 列表，逗号分隔或重复传参；缺省查本人该类型全部组；传入须均为本人组，否则 403
Name	否	素材名称精确匹配，最长 64 字符
Statuses	否	素材状态，Active / Processing / Failed，逗号分隔或重复传参
SortBy	否	CreateTime（缺省）/ UpdateTime / GroupId
SortOrder	否	Desc（缺省）/ Asc
NextToken	否	分页游标，取上次响应的 Result.NextToken，优先于 PageNumber
MaxResults	否	每页数量（官方游标分页参数），与 PageSize 等价，PageSize 优先，缺省 10
PageNumber	否	页码，缺省 1
PageSize	否	每页数量，1~100，缺省 10

Request 示例：

curl -G 'https://token.taiha.cn/api/seedance/proxy/assets' \
  -H 'Authorization: Bearer sk-xxx' \
  --data-urlencode 'GroupType=AIGC' \
  --data-urlencode 'GroupIds=group-20260923114838-spsqh' \
  --data-urlencode 'Statuses=Active' \
  --data-urlencode 'PageNumber=1' \
  --data-urlencode 'PageSize=20'

Response 200（官方结构，素材字段为上游透传，返回完整字段）：

{
  "Result": {
    "Items": [
      {
        "Id": "asset-20260923120000-xxxxx",
        "GroupId": "group-20260923114838-spsqh",
        "Name": "pexels-photo-15213183",
        "AssetType": "Image",
        "Status": "Active",
        "URL": "https://example-tos.cn-beijing.volcengine.com/asset-xxx.jpg",
        "CreateTime": "2026-09-23 03:26:49",
        "UpdateTime": "2026-09-23 03:26:52"
      }
    ],
    "NextToken": "",
    "TotalCount": 1
  }
}

说明：

• Result.NextToken：还有下一页时非空，原样回传取下一页；空串表示已到最后一页
• 上游列表不区分用户，网关侧始终按本人素材组过滤（Name/Statuses 过滤参数同时透传上游并在网关侧兜底）。

错误：400（参数校验）、403（GroupIds 归属）、500、502

2.3 素材详情

GET /api/seedance/proxy/assets/{asset_id}

Path 参数：asset_id — 素材 ID。

Request 示例：

curl 'https://token.taiha.cn/api/seedance/proxy/assets/asset-20260923120000-xxxxx' \
  -H 'Authorization: Bearer sk-xxx'

Response 200（上游透传）：

{
  "Result": {
    "Id": "asset-20260923120000-xxxxx",
    "GroupId": "group-20260923114838-spsqh",
    "Name": "pexels-photo-15213183",
    "AssetType": "Image",
    "Status": "Active",
    "URL": "https://example-tos.cn-beijing.volcengine.com/asset-xxx.jpg",
    "CreateTime": "2026-09-23 03:26:49",
    "UpdateTime": "2026-09-23 03:26:52"
  }
}

说明：轮询创建状态即反复调用本接口，关注 Result.Status（Active / Processing / Failed）。素材须属于本人素材组，否则 403（asset not found in your asset group）。

2.4 修改素材

PUT   /api/seedance/proxy/assets/{asset_id}
PATCH /api/seedance/proxy/assets/{asset_id}

Request Body（JSON）：可修改字段（如 Name）原样透传上游，由上游校验；ProjectName 会被自动剔除。

Request 示例：

curl -X PATCH 'https://token.taiha.cn/api/seedance/proxy/assets/asset-20260923120000-xxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-xxx' \
  -d '{"Name": "renamed-photo"}'

Response：上游透传（状态码与响应体）。

2.5 删除素材

DELETE /api/seedance/proxy/assets/{asset_id}

Request 示例：

curl -X DELETE 'https://token.taiha.cn/api/seedance/proxy/assets/asset-20260923120000-xxxxx' \
  -H 'Authorization: Bearer sk-xxx'

Response：上游透传（状态码与响应体）。

---

3. 真人认证（LivenessFace）

认证接口使用 Web 会话登录态（浏览器 Cookie），不接受 API 令牌（sk-），供前端个人资料页调用。

3.1 发起真人认证

POST /api/seedance/face-verifications

Request Body（JSON）：原样透传上游认证接口。

Request 示例：

curl -X POST 'https://token.taiha.cn/api/seedance/face-verifications' \
  -H 'Content-Type: application/json' \
  -b 'session=xxx' \
  -d '{}'

Response 200（上游透传）：

{
  "verification_id": "vfy-20260923120000-xxxxx",
  "status": "waiting_user",
  "h5_url": "https://xxx/verification?token=xxx",
  "expires_at": 1790135000
}

用户打开 h5_url 完成人脸认证。

3.2 查询认证任务

GET /api/seedance/face-verifications/{verification_id}

仅任务创建者可查询（否则 404 verification not found）。

Request 示例：

curl 'https://token.taiha.cn/api/seedance/face-verifications/vfy-20260923120000-xxxxx' \
  -b 'session=xxx'

Response 200（上游透传）：

{
  "verification_id": "vfy-20260923120000-xxxxx",
  "status": "verified",
  "group_id": "group-20260923130000-xxxxx"
}

状态流转：waiting_user → callback_received → resolving → verified / failed / expired。

说明：认证成功（响应携带 group_id）时，网关自动将该真人素材组记入用户映射表；后续以 GroupType=LivenessFace 查询/上传真人素材。

---

4. 典型调用流程

AIGC 虚拟人像素材

1. POST /api/seedance/proxy/assets/groups        → 得到 Result.Id（group_id）
2. POST /api/seedance/proxy/assets               → 携带 GroupId，得到 Result.Id（asset_id）
3. GET  /api/seedance/proxy/assets/{asset_id}    → 轮询，直至 Result.Status = Active / Failed

真人素材（LivenessFace）

1. POST /api/seedance/face-verifications               → 得到 verification_id + h5_url（会话认证）
2. 用户完成 H5 人脸认证
3. GET  /api/seedance/face-verifications/{id}          → 轮询，status=verified 时取得 group_id
4. GET  /api/seedance/proxy/assets?GroupType=LivenessFace  → 查询真人素材（API 令牌）
5. POST /api/seedance/proxy/assets（GroupId=真人组、GroupType=LivenessFace）→ 上传真人素材

---

5. 状态码汇总

状态码	场景
200	成功
400	参数校验失败（缺字段、超长、取值非法、重复建组等）
401	令牌无效或未认证
403	归属校验失败（GroupIds / GroupId / 素材不属于本人）
404	认证任务不存在或不属于当前用户
500	网关内部错误（数据库等）
502	上游不可用或上游响应无效
其他	上游错误，状态码与响应体原样透传