Seedance 素材资产 API 使用文档

面向接入方的素材库使用指南。素材用于 Seedance 2.0 系列模型生成视频时引用。

一、开始之前

1.1 认证

所有素材接口(回调除外)都需要在请求头带平台分发的 Token:

Authorization: Bearer <你的平台Token>
Content-Type: application/json

1.2 接口形态

素材接口统一是一个网关地址,靠 URL 上的 Action 参数区分动作,全部 POST:

POST {平台域名}/v1/volc/ark/?Action=<动作名>&Version=2024-01-01

每个请求固定带 Version=2024-01-01。

如果你已有基于火山官方 Go SDK 的代码,可不改调用逻辑、只换接入地址直接复用,详见「七、使用官方 SDK 接入」。

1.3 资源 ID 规则(重要)

你只会接触平台 ID,永远不要使用真实 ID:

资源	平台 ID 格式	示例
素材	`hb-` 前缀	`hb-MnP48NWmWCa3S3zYJNZ9`
分组	`hbg-` 前缀	`hbg-3V1lztXLe9Wzj399OyLm`

请求里凡是填资源 ID 的地方,都填 hb-/hbg-。

响应里返回的资源 ID 也都是 hb-/hbg-。

数组类字段(如 Filter.GroupIds)里的每个元素同样只能是平台 ID。

填入非 hb-/hbg- 的裸 ID 会被拒绝(返回「asset not found or access denied」)。

1.4 平台托管字段(不可传入)

以下字段由平台按渠道/访问域名自动生成与注入,不对外开放、不在请求参数中列出,传入会被忽略:

ProjectName:由平台按渠道配置注入(火山 IAM 按 project 维度鉴权)。

CallbackURL(真人认证):由平台按你的访问域名服务端生成,内含一次性 session_id。

二、两条主流程

2.1 虚拟人像(AIGC)

直接建组,无需人脸认证:

① CreateAssetGroup(GroupType=AIGC)        → 拿到 hbg- 分组 id
② CreateAsset(GroupId=hbg-, URL, ...)      → 拿到 hb- 素材 id(状态 Processing)
③ 轮询 GetAsset(Id=hb-) 直到 Status=Active  → 可用于视频生成
④ 视频生成请求里引用 asset://hb-xxxx

2.2 真人人像(LivenessFace)

必须先做 H5 人脸认证才能建组:

① CreateVisualValidateSession              → 拿到 H5Link + session_id
② 终端用户在 H5Link 完成人脸认证(手机端操作)
③ 认证完成后浏览器自动跳转回调               → 平台落库,拿到 hbg- 分组 id
④ CreateAsset(GroupId=hbg-, URL, ...)      → 上传该真人素材(会做人脸比对)
⑤ 轮询 GetAsset 直到 Active
⑥ 视频生成里引用 asset://hb-xxxx

同一个真人后续追加素材,复用同一个 hbg- 分组,无需重复认证。
真人组上传素材时火山会做人脸一致性比对,不一致则该素材 Status=Failed。

状态会自动同步:素材入库后状态为 Processing,平台后台会自动轮询同步到 Active/Failed,你也可以主动调 GetAsset 查询。

三、接口明细

3.1 CreateAssetGroup — 创建素材分组(虚拟人像)

POST /v1/volc/ark/?Action=CreateAssetGroup&Version=2024-01-01

请求:

{
  "Name": "美妆博主A",
  "Description": "美妆类素材",
  "GroupType": "AIGC"
}

字段	必填	说明
Name	是	分组名,上限 64 字符
Description	否	描述,上限 300 字符
GroupType	否	当前仅支持 `AIGC`

响应:Result.GroupId 为平台分组 id(hbg-)。

3.2 CreateAsset — 上传素材(异步)

POST /v1/volc/ark/?Action=CreateAsset&Version=2024-01-01

请求:

{
  "GroupId": "hbg-xxxxxxxx",
  "URL": "https://example.com/face.jpg",
  "AssetType": "Image",
  "Name": "正脸照"
}

字段	必填	说明
GroupId	是	平台分组 id(`hbg-`)
URL	是	素材公网可访问 URL(可访问性与时效由你保证,平台不转存)
AssetType	是	`Image` / `Video` / `Audio`
Name	否	备注名,仅供检索,不进推理

响应:

{ "Result": { "Id": "hb-yyyyyyyy" } }

Id 为平台素材 id,初始状态 Processing,需轮询至 Active 才能用于视频生成。

3.3 GetAsset — 查询素材信息

POST /v1/volc/ark/?Action=GetAsset&Version=2024-01-01

请求:

{ "Id": "hb-yyyyyyyy" }

响应:

{
  "Result": {
    "Id": "hb-yyyyyyyy",
    "GroupId": "hbg-xxxxxxxx",
    "AssetType": "Image",
    "Status": "Active",
    "Name": "人脸照",
    "URL": "https://...",
    "Error": { "Code": "", "Message": "" },
    "CreateTime": "2026-06-22T08:06:23Z",
    "UpdateTime": "2026-06-22T08:06:26Z"
  }
}

字段	说明
Status	`Processing` / `Active` / `Failed`,仅 `Active` 可用于推理
URL	火山 12 小时预览地址,平台不持久化(仅预览用)
Error	仅入库失败(如真人比对不通过)时返回原因

3.4 ListAssets — 查询素材列表

POST /v1/volc/ark/?Action=ListAssets&Version=2024-01-01

请求(过滤条件统一放进 Filter 对象):

{
  "Filter": {
    "GroupIds": ["hbg-xxxxxxxx"],
    "GroupType": "LivenessFace",
    "Statuses": ["Active", "Processing"],
    "Name": "figure"
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "GroupId",
  "SortOrder": "Asc"
}

字段	必填	说明
Filter	是	过滤条件对象
Filter.GroupIds	否	平台分组 id 数组(`hbg-`)
Filter.GroupType	否	`LivenessFace`(真人)/ `AIGC`(虚拟)
Filter.Statuses	否	`Active` / `Processing` / `Failed`
Filter.Name	否	按名称模糊搜索
PageNumber / PageSize	否	分页
SortBy / SortOrder	否	排序字段 / `Asc`、`Desc`

注意:过滤条件必须放在 Filter 里,直接在顶层传 GroupId 会报 MissingParameter.Filter。

响应:Result.Items[],每条结构同 GetAsset(Id/GroupId 均为平台 id);另有 PageNumber/PageSize/TotalCount。

3.5 UpdateAsset — 更新素材

POST /v1/volc/ark/?Action=UpdateAsset&Version=2024-01-01

请求:

{ "Id": "hb-yyyyyyyy", "Name": "新备注名" }

响应:Result.Id(平台素材 id)。

3.6 DeleteAsset — 删除素材

POST /v1/volc/ark/?Action=DeleteAsset&Version=2024-01-01

请求:

{ "Id": "hb-yyyyyyyy" }

响应:Result 为空对象 {}。

3.7 DeleteAssetGroup — 删除分组

POST /v1/volc/ark/?Action=DeleteAssetGroup&Version=2024-01-01

请求:

{ "GroupId": "hbg-xxxxxxxx" }

响应:Result 为空对象 {}。

3.8 GetAssetGroup — 查询单个分组

POST /v1/volc/ark/?Action=GetAssetGroup&Version=2024-01-01

请求:

{ "Id": "hbg-xxxxxxxx" }

响应:

{
  "Result": {
    "Id": "hbg-xxxxxxxx",
    "Name": "美妆博主A",
    "Description": "美妆类素材",
    "GroupType": "AIGC",
    "CreateTime": "2026-03-28T00:00:00Z",
    "UpdateTime": "2026-03-28T00:00:00Z"
  }
}

字段	说明
Id	平台分组 id(hbg-)
GroupType	`AIGC`(虚拟)/ `LivenessFace`(真人)

3.9 UpdateAssetGroup — 更新分组(名称/描述)

POST /v1/volc/ark/?Action=UpdateAssetGroup&Version=2024-01-01

当前仅支持更新分组的 Name 和 Description。请求:

{ "Id": "hbg-xxxxxxxx", "Name": "新名称", "Description": "新描述" }

字段	必填	说明
Id	是	平台分组 id(hbg-)
Name	否	新名称,上限 64 字符
Description	否	新描述,上限 300 字符

响应:Result.Id(平台分组 id)。

3.10 CreateVisualValidateSession — 发起真人认证

POST /v1/volc/ark/?Action=CreateVisualValidateSession&Version=2024-01-01

请求:

{}

CallbackURL 由平台服务端生成,无需传。

响应:返回 H5Link(把它给终端用户跳转/扫码完成人脸认证)+ session_id。

3.11 真人认证回调(无需手动调用)

GET {平台域名}/v1/volc/ark/liveness/callback?resultCode=10000&session_id=vls-xxxx

终端用户在 H5 完成认证后,浏览器自动跳转命中此地址。平台校验通过后落库,返回:

{ "group_id": "hbg-xxxx", "message": "ok" }

拿到 group_id 后即可用它上传真人素材。

四、视频生成时引用素材

在视频生成请求的内容里,用 asset:// + 平台素材 id 引用(素材须为 Active):

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "使用图1的角色生成视频" },
    {
      "type": "image_url",
      "image_url": { "url": "asset://hb-yyyyyyyy" },
      "role": "reference_image"
    }
  ],
  "ratio": "16:9",
  "duration": 11
}

同一次生成请求里引用的多个素材必须属于同一渠道,否则报「素材不可跨渠道混用」。

五、错误说明

场景	HTTP	提示
素材不存在 / 无权访问 / 填了裸真实 ID	400	asset not found or access denied
不支持的 Action	400	unsupported action
请求体格式错误	400	invalid request body
上游素材服务故障	502	asset service unavailable
素材未就绪(视频生成时引用了非 Active 素材)	400	素材未就绪
真人认证会话失效	400	validation session expired, please retry

六、暂不支持的接口

暂无

七、使用官方 SDK 接入

如果你已有基于火山官方 Go SDK(volcengine-go-sdk)的素材管理代码,无需改写调用逻辑,只需调整 SDK 的初始化配置即可指向本平台。

7.1 三处改动

配置项	改成	说明
`WithCredentials`	任意非空占位值	AK/SK 不参与平台鉴权,但 SDK 要求非空,填 `"unused"` 即可
`WithEndpoint`	`https://{平台域名}/v1/volc/ark`	把请求打到本平台网关,而非火山官方地址
`WithExtendHttpRequest`	注入 `x-api-key` 头	用该头携带平台 Token(真正的鉴权)

{平台域名} 填你登录平台所用的域名(与控制台一致)。

7.2 为什么 Token 放在 `x-api-key` 而不是 `Authorization`

官方 SDK 会用本地 AK/SK 算一份 V4 签名写进 Authorization 头,该头被 SDK 占用、无法承载平台 Token。SDK 通过 WithExtendHttpRequest 注入的自定义头(x-api-key)不会被覆盖,因此平台 Token 放在 x-api-key 上。网关收到后会以 x-api-key 为准完成鉴权。

直接用 HTTP 客户端(非 SDK)调用时,仍按「一、认证」用 Authorization: Bearer <Token> 即可,两种方式共用同一网关地址。

7.3 示例

7.4 注意事项

资源 ID 仍只用 hb-/hbg- 平台 ID(见「1.3」),SDK 接入不改变这一约束。

ProjectName / CallbackURL 仍由平台托管(见「1.4」),即使 SDK 请求体里带了也会被忽略/覆盖。

Action 白名单一致:ListAssetGroups 等未开放接口经 SDK 调用同样返回 unsupported action(见「六」)。

Seedance SDK 接入示例

Seedance 素材资产 API 使用文档#

一、开始之前#

1.1 认证#

1.2 接口形态#

1.3 资源 ID 规则(重要)#

1.4 平台托管字段(不可传入)#

二、两条主流程#

2.1 虚拟人像(AIGC)#

2.2 真人人像(LivenessFace)#

三、接口明细#

3.1 CreateAssetGroup — 创建素材分组(虚拟人像)#

3.2 CreateAsset — 上传素材(异步)#

3.3 GetAsset — 查询素材信息#

3.4 ListAssets — 查询素材列表#

3.5 UpdateAsset — 更新素材#

3.6 DeleteAsset — 删除素材#

3.7 DeleteAssetGroup — 删除分组#

3.8 GetAssetGroup — 查询单个分组#

3.9 UpdateAssetGroup — 更新分组(名称/描述)#

3.10 CreateVisualValidateSession — 发起真人认证#

3.11 真人认证回调(无需手动调用)#

四、视频生成时引用素材#

五、错误说明#

六、暂不支持的接口#

七、使用官方 SDK 接入#

7.1 三处改动#

7.2 为什么 Token 放在 x-api-key 而不是 Authorization#

7.3 示例#

7.4 注意事项#