Seedance 资产与真人认证

资产接口用于登记可复用的图片、视频和音频，并通过 asset://ASSET_ID 在 Seedance 生视频 中引用。创建资产成功与素材处理完成是两个阶段，先确认素材已就绪再提交视频任务。

本页以火山/豆包兼容资产流程为主。其他渠道可能使用不同的状态和结果字段，资产组、远端更新及真人认证并非所有渠道都支持。

两种调用入口

方式	地址
Action 路径	POST https://api.wisgate.cn/api/v3/open/{Action}
SDK / Query Action	POST https://api.wisgate.cn/api/v3/assets?Action={Action}&Version=2024-01-01

请求体为 JSON，普通调用使用 Authorization: Bearer YOUR_API_KEY。Query Action 入口也兼容 ApiKey: YOUR_API_KEY，供火山 SDK 使用。两种入口调用相同的业务 Handler，但认证与偏好加载的中间件并不完全相同。

响应包装与渠道差异

启用原生响应偏好时，成功返回外层 ResponseMetadata / Result：

{
  "ResponseMetadata": {
    "Action":"CreateAssetGroup",
    "Region":"cn-beijing",
    "RequestId":"request-example",
    "Service":"ark",
    "Version":"2024-01-01"
  },
  "Result":{"Id":"group-example"}
}

平台当前新用户默认偏好启用原生包装。既有用户或兼容配置可关闭 volcengine_asset_native_response_enabled，返回业务结果本身，例如 {"Id":"group-example"}。不能写成“所有账户始终有 Result”。下文均以原生包装为例。

兼容解析可先判断是否存在 Result，存在则取其值，否则取整个响应。但必须先检查 HTTP 状态及 Error，避免把错误当作素材。

当前 SE 渠道创建资产后会内部轮询，拿到资产 ID 后以 Id 返回，并统一资产状态。其他兼容渠道仍需按实际返回检查；不能由创建成功推断所有素材已 Active。

操作清单

所有操作均可使用两种入口，下面列的是 Action 名称：

Action	用途
CreateAssetGroup	创建资产组
ListAssetGroups	查询本用户的本地资产组列表
GetAssetGroup	查询指定资产组
UpdateAssetGroup	更新组信息
DeleteAssetGroup	删除组，能力和非空组规则依赖渠道
CreateAsset	创建资产
ListAssets	查询本用户的本地资产列表
GetAsset	查询素材及处理状态
UpdateAsset	更新素材信息
DeleteAsset	删除资产
CreateVisualValidateSession	创建真人认证会话
GetVisualValidateResult	获取认证结果并同步资产组

列表从本地数据库查询，并按用户及允许渠道过滤；并不是查询上游账号全部素材。已有资产/组的详情和维护还会校验本地归属。远端同步行为随渠道能力变化，不能保证每次操作均调用火山官方接口。

1. 创建资产组

curl --fail-with-body https://api.wisgate.cn/api/v3/open/CreateAssetGroup \
  -H "Authorization: Bearer $WISGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"Name":"product-demo","Description":"产品参考素材","GroupType":"AIGC","ProjectName":"default"}'

字段	类型	说明
Name	string	必填组名；火山流程上限为 64 字符，仍需遵守渠道限制
Description	string	可选；上限 300 字符
GroupType	string	普通 AI 素材示例使用 AIGC；真人授权组使用认证流程获得的 LivenessFace 组
ProjectName	string	示例显式使用 default

成功后从 Result.Id 读取组 ID。不要把 LivenessFace 当作绕过真人认证的创建选项。

2. 创建资产

curl --fail-with-body https://api.wisgate.cn/api/v3/open/CreateAsset \
  -H "Authorization: Bearer $WISGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "GroupId":"group-example",
    "URL":"https://example.com/product.png",
    "Name":"product-front",
    "AssetType":"Image",
    "ProjectName":"default"
  }'

字段	类型	说明
GroupId	string	推荐明确指定本用户拥有的组。火山标准流程需要组；平台某些模式可自动分组，不能当作通用省略规则
URL	string	可供上游访问的素材地址；此流程不用 Base64
Url	string	历史兼容拼写；不要同时传两者，本地非空 Url 优先
Name	string	推荐填写；长度和必填性有渠道差异，火山流程最多 64 字符，其他渠道需确认限制
AssetType	string	Image、Video 或 Audio，同时受组和渠道能力限制
ProjectName	string	与组使用相同项目

火山兼容成功业务结果示意：

{"Result":{"Id":"asset-example"},"ResponseMetadata":{"Action":"CreateAsset","RequestId":"request-example"}}

当前 SE 创建路径也将结果归一为 Id。客户端应先处理响应包装，再读取实际返回的 ID，不要固定读取顶层 AssetId。

3. 查询处理状态

curl --fail-with-body https://api.wisgate.cn/api/v3/open/GetAsset \
  -H "Authorization: Bearer $WISGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"Id":"asset-example","ProjectName":"default"}'

火山兼容业务结果示意（省略外层）：

{
  "Id":"asset-example",
  "Name":"product-front",
  "GroupId":"group-example",
  "AssetType":"Image",
  "Status":"Active",
  "URL":"https://example.com/product.png"
}

火山状态	行为
Processing	等待，稍后重查
Active	已就绪，可以引用
Failed	停止等待，排查 URL、格式、授权或上游错误

轮询设置间隔与总超时，超时后保留资产 ID；不要每次等待都重新 CreateAsset。当前 SE 状态也会映射到 Active/Processing/Failed，但公开 GetAsset 使用本地读取能力，不保证每次查询都会重新访问 SE；长时间未就绪时应排查平台记录与上游状态。

4. 查询列表

资产组列表：

curl --fail-with-body https://api.wisgate.cn/api/v3/open/ListAssetGroups \
  -H "Authorization: Bearer $WISGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"Filter":{"GroupType":"AIGC","Name":"product"},"PageNumber":1,"PageSize":20,"SortBy":"CreateTime","SortOrder":"Desc","ProjectName":"default"}'

资产列表：

curl --fail-with-body https://api.wisgate.cn/api/v3/open/ListAssets \
  -H "Authorization: Bearer $WISGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"Filter":{"GroupType":"AIGC","GroupIds":["group-example"],"Statuses":["Active","Processing"]},"PageNumber":1,"PageSize":20,"SortBy":"CreateTime","SortOrder":"Desc","ProjectName":"default"}'

参数	用途
Filter.Name	名称筛选
Filter.GroupIds	按组 ID 列表筛选
Filter.GroupType	按 AIGC / LivenessFace 等组类型筛选；本地接口未强制必填
Filter.Statuses	仅资产列表，状态数组
ProjectName	项目筛选
PageNumber	默认 1；小于 1 归一到 1
PageSize	默认 20；小于 1 用 20，大于 100 截到 100
SortBy / SortOrder	常用 CreateTime/UpdateTime 与 Desc/Asc；不使用未确认的任意列名

两个列表的业务结果均包含 Items、TotalCount、PageNumber、PageSize。第一页为空不等于上游无素材，可能是本地尚未同步、用户归属、渠道或筛选条件不同。

5. 详情、更新和删除

统一调用模板：将 ACTION 替换为下表 Action，将 JSON 替换为对应请求体。

curl --fail-with-body https://api.wisgate.cn/api/v3/open/ACTION \
  -H "Authorization: Bearer $WISGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"Id":"group-example"}'

Action	请求体示例	说明
GetAssetGroup	{"Id":"group-example","ProjectName":"default"}	读取组详情
UpdateAssetGroup	{"Id":"group-example","Name":"product-v2","Description":"更新描述"}	标准用法只更新名称/描述
UpdateAsset	{"Id":"asset-example","Name":"product-front-v2"}	标准用法只更新名称
DeleteAsset	{"Id":"asset-example","ProjectName":"default"}	删除指定资产
DeleteAssetGroup	{"Id":"group-example","ProjectName":"default"}	本地已注册；渠道可能不支持，非空组能否删除由实际返回决定

标准火山删除成功业务结果通常为 {}。不要假定删除组会自动级联删除所有素材；也不要将删除资产理解为取消已经创建的视频任务。后端接受更多维护字段不等于所有供应商允许修改这些字段。

6. 真人认证与 Group ID

真人授权流程要求渠道具备 VisualValidate 能力。当前火山/豆包适配器声明了该能力，SE/清程不能因此被视为等价支持。官方流程说明参考 真人人像素材使用。

第一步创建会话：

curl --fail-with-body https://api.wisgate.cn/api/v3/open/CreateVisualValidateSession \
  -H "Authorization: Bearer $WISGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"CallbackURL":"https://example.com/verification/callback","ProjectName":"default"}'

返回结构示意：

{
  "ResponseMetadata":{"Action":"CreateVisualValidateSession","RequestId":"request-example"},
  "Result":{
    "BytedToken":"BYTED_TOKEN_PLACEHOLDER",
    "CallbackURL":"https://example.com/verification/callback",
    "H5Link":"H5_LINK_RETURNED_BY_PROVIDER"
  }
}

让素材本人打开实际 H5Link 完成认证，服务端保存对应 BytedToken。认证回调成功后查询结果；回调参数不能独立作为最终授权依据，仍需服务端查询。

curl --fail-with-body https://api.wisgate.cn/api/v3/open/GetVisualValidateResult \
  -H "Authorization: Bearer $WISGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"BytedToken":"BYTED_TOKEN_PLACEHOLDER","ProjectName":"default"}'

成功得到 Result.GroupId。平台随后调用组详情同步完整数据，若同步失败，本次请求会报错，不能把半完成状态当成可用资产组。

BytedToken 和 H5 会话具有时效性，以认证服务当前返回及规则为准。请尽快完成认证并查询结果；过期后重新创建会话，不要假设会话与查询 Token 的有效期相同。

H5Link 可能含短期授权参数，只传给本次认证用户，不放入公开日志或示例。随后按上游规则在认证组中创建素材、等待就绪，再引用 asset://。认证组类型本身不证明任意 URL 都已获得授权。

7. 火山 SDK 接入约定

使用火山 Go SDK universal.DoCall 时：

SDK 项	设置
endpoint	https://api.wisgate.cn/api/v3/assets
Region	cn-beijing
ServiceName	ark
Version	2024-01-01
HttpMethod / ContentType	POST / JSON
扩展 HTTP 请求头	ApiKey: <WisGate API Key>
SDK credentials	使用非空占位 AK/SK 满足客户端构造；本次 ApiKey 模式不依赖占位签名认证

最终应发出类似请求：

POST /api/v3/assets?Action=GetAssetGroup&Version=2024-01-01
ApiKey: YOUR_API_KEY
Content-Type: application/json

{"Id":"group-example"}

SDK 自动生成 HMAC Authorization 时，平台 Query Action 认证优先使用显式 ApiKey。必须设置 ApiKey，仅填写占位 AK/SK 不构成有效鉴权。不同 SDK 版本的 endpoint 拼接方式可能不同，请检查最终请求路径。

8. 引用已就绪资产

{
  "model":"doubao-seedance-2-5",
  "omni_reference_task_type":"reference",
  "content":[
    {"type":"text","text":"保持参考商品的外观，生成简洁的产品展示镜头。"},
    {"type":"image_url","role":"reference_image","image_url":{"url":"asset://asset-example"}}
  ],
  "duration":5,
  "resolution":"720p",
  "ratio":"16:9"
}

资产 ID、组 ID 与任务 ID 是三种不同标识。只在媒体 URL 中使用 asset://，不要把组 ID 当作素材。

错误处理

资产接口错误示意：

{
  "ResponseMetadata":{"Action":"GetAsset","RequestId":"request-example"},
  "Error":{"Code":"InvalidRequest","Message":"asset not found"}
}

不要按成功响应的 Result 解析错误；鉴权中间件还可能使用另一种通用错误格式。

问题	排查
asset/group not found	核对用户归属、ID 和是否完成本地同步
URL 处理失败	核对公网可访问性、素材格式及链接有效期
unsupported action / capability	检查 Action 名称及所选渠道能力
组与渠道不匹配	使用原组所属渠道或在允许渠道创建新组
Result 不存在	检查响应偏好与错误体，不先认定服务异常
pending/Processing 长时间不变	保存 ID，有界轮询并排查供应商，不重复创建