Seedance 2.0 私域虚拟人像素材使用
火山方舟私域虚拟人像素材资产库 使用指南
概览
接入规则
鉴权方式
路径规则
/volc/openapi 路径下，通过 Query 参数 Action 区分具体操作：POST /volc/openapi?Action=<ActionName>&Version=2024-01-01注意事项
POST 方法，请求体为 JSON 格式。ProjectName 字段无需传入，网关会自动注入为 default。CreateAsset 为异步接口，上传后需轮询 GetAsset 直到 Status 变为 Active 才可使用。Active 后，可通过 asset://<asset_id> 格式在视频生成接口中引用。能力清单
| 接口名 | Action | 说明 |
|---|---|---|
| 创建素材组 | CreateAssetGroup | 创建一个素材资产组合 |
| 上传素材 | CreateAsset | 向素材组上传图片/视频/音频素材 |
| 查询素材 | GetAsset | 查询单个素材的状态和信息 |
| 查询素材组 | GetAssetGroup | 查询单个素材组信息 |
| 查询素材列表 | ListAssets | 批量查询素材，支持过滤和分页 |
| 查询素材组列表 | ListAssetGroups | 批量查询素材组，支持过滤和分页 |
| 更新素材 | UpdateAsset | 更新素材名称或描述 |
| 更新素材组 | UpdateAssetGroup | 更新素材组名称或描述 |
| 删除素材 | DeleteAsset | 删除单个素材 |
| 删除素材组 | DeleteAssetGroup | 删除指定素材组 |
典型使用流程
CreateAssetGroup → CreateAsset → 轮询 GetAsset（等待 Active）→ 视频生成中使用 asset://<asset_id>接口详情
https://api.onelinkai.cloud 作为示例网关地址，实际调用时请替换为你的真实接入地址和有效的 ApiKey。创建素材组
CreateAssetGroup| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Name | string | 是 | 素材组名称 |
| Description | string | 否 | 素材组描述 |
| GroupType | string | 否 | 素材组类型，默认 AIGC，当前仅支持 AIGC |
{
"ResponseMetadata": { "...": "..." },
"Result": {
"Id": "group-20260511142859-k55n6"
}
}上传素材
CreateAsset| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| GroupId | string | 是 | 素材组 ID |
| URL | string | 是 | 素材的公网可访问 URL |
| AssetType | string | 是 | 素材类型：Image / Video / Audio |
| Name | string | 否 | 素材名称，用于 ListAssets 模糊搜索 |
{
"ResponseMetadata": { "...": "..." },
"Result": {
"Id": "asset-20260511142915-hc7q6"
}
}查询素材状态
GetAssetStatus 变为 Active。| Status 值 | 说明 |
|---|---|
| Processing | 处理中，继续轮询 |
| Active | 处理完成，可用于视频生成 |
| Failed | 处理失败，无法使用 |
{
"ResponseMetadata": { "...": "..." },
"Result": {
"Id": "asset-20260511142915-hc7q6",
"Name": "avatar_fullbody",
"AssetType": "Image",
"GroupId": "group-20260511142859-k55n6",
"Status": "Active",
"URL": "https://...",
"CreateTime": "2026-05-11T06:29:15Z",
"UpdateTime": "2026-05-11T06:29:18Z",
"ProjectName": "default"
}
}查询素材列表
ListAssets| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Filter.GroupIds | array | 否 | 按素材组 ID 过滤 |
| Filter.GroupType | string | 是 | 素材组类型，固定传 AIGC |
| Filter.Statuses | array | 否 | 按状态过滤：Active / Processing / Failed |
| Filter.Name | string | 否 | 按素材名称模糊搜索 |
| PageNumber | integer | 否 | 页码，默认 1 |
| PageSize | integer | 否 | 每页数量，默认 10 |
| SortBy | string | 否 | 排序字段，如 GroupId |
| SortOrder | string | 否 | 排序 方向：Asc / Desc |
查询素材组
GetAssetGroup查询素材组列表
ListAssetGroups| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Filter.GroupIds | array | 否 | 按素材组 ID 过滤 |
| Filter.GroupType | string | 是 | 素材组类型，固定传 AIGC |
| Filter.Name | string | 否 | 按素材组名称模糊搜索 |
| PageNumber | integer | 否 | 页码，默认 1 |
| PageSize | integer | 否 | 每页数量，默认 10 |
更新素材
UpdateAsset更新素材组
UpdateAssetGroup删除素材
DeleteAsset删除素材组
DeleteAssetGroup在视频生成中使用素材
Status 变为 Active 后，在视频生成接口的 content 中通过 asset://<asset_id> 格式引用：在提示词中使用图片 1、图片 2 等方式引用素材，序号对应 content数组中同类素材的顺序。请勿在提示词中直接使用 Asset ID。
使用建议
CreateAsset 为异步接口，建议轮询间隔不低于 5 秒。修改于 2026-05-13 02:18:04