32 KiB
「⚠️保密信息」【申请权限填客户名称】Assets API 参考文档（邀测用户版）
| 文档变更说明 | 时间 |
|---|---|
| 2026.3.26 | |
| 2026.3.28 |
本文介绍素材资产（Assets）API 接口的参数。您可以使用以下 Assets API 接口创建、管理个人人像素材资产。
本文档仅限预览及邀测用户使用：
不承诺正式 API 上线100%一致。
仅限邀测用户阅读，请勿截图/分享给其他人员。
上传素材 （CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。
素材资产应为虚拟人像，非虚拟人像类素材无需入库。
您需确保上传的虚拟人像符合以下条件：
您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。
素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。
素材不包含违反法规、违背公序良俗、危害国家安全的内容。
素材资产库结构说明
-
Asset Group（素材资产组合）：单个素材文件为一个 Asset，每个 Asset 属于一个 Asset Group。
- 可以使用素材组自由管理素材，例如可将同一虚拟人物素材放入同一素材组合进行管理。
-
Asset（素材资产）：一个素材文件（当前支持上传图像、视频、音频），是方舟 Seedance 2.0 系列模型可直接用于推理的可信资产。
注意
仅需入库推理需使用的素材资产，不需使用的素材资产请勿入库。
仅可使用已入库素材资产的 Id (Asset ID) 进行视频生成，同一形象未入库素材无法使用。
每个上传的素材资产需经过预处理，可轮询调用 GetAsset 接口查询素材状态（对应参数为 Status），仅当状态变为
Active后，该素材资产方可用于后续推理使用；若状态为Failed则表示处理失败，无法用于后续推理使用。详情可参考：上传素材资产并获取素材资产信息代码示例。
素材资产（Assets）API 接口功能
Asset (Group) 创建接口：
-
CreateAssetGroup：创建素材资产组合。首次创建素材资产组合时需在控制台签署授权函，详情参考 私域虚拟人像素材库 (WIP)
-
CreateAsset：创建素材资产。该接口可用于上传个人素材资产，创建素材资产后可利用返回字段中的素材 Id （需处于
Active状态）用于 Seedance 2.0 系列模型生成视频。
Asset (Group) 管理接口：
-
ListAssetGroups：查询素材资产组合列表。
-
ListAssets：查询素材资产列表。
-
GetAsset：查询素材资产信息。
-
GetAssetGroup：查询素材资产组合信息。
-
UpdateAssetGroup：更新素材资产组合信息。
-
UpdateAsset：更新素材资产信息。
-
DeleteAsset：删除单个素材资产。
鉴权方式
调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考 获取 API 访问密钥（AK/SK）。
限流要求
- QPS 限流： API接口每秒查询请求的总数上限。超过此限制的查询请求会报错。
| 接口名 | 账号维度的 QPS 限流 |
|---|---|
| CreateAssetGroup | 30 |
| CreateAsset | 1 |
| ListAssetGroups | 30 |
| ListAssets | 30 |
| GetAsset | 100 |
| GetAssetGroup | 100 |
| UpdateAsset | 30 |
| UpdateAssetGroup | 30 |
CreateAssetGroup
POST /open/CreateAssetGroup
创建 Asset Group（素材资产组合）组合，用作素材资产管理。
首次创建 Asset Group（素材资产组合）需在控制台签署授权函，详情参考 私域虚拟人像素材库 (WIP)
请求参数
Name string 必填
Asset Group（素材资产组合）的名称，上限为 64 字符。
Description string
Asset Group（素材资产组合）的描述，上限为 300 字符。
GroupType string
Asset Group（素材资产组合）的类型。可选值：
- AIGC：虚拟人像。
当前仅支持 AIGC 类型。
ProjectName string
资源所属的项目名称，默认值为default。
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 文档。
返回参数
Id string
Asset Group（素材资产组合）的 Id。
返回示例：
CreateAsset
POST /open/CreateAsset
向指定的Asset Group（素材资产组合）内创建Asset（素材资产）。
上传素材 （CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。
请求参数
GroupId string 必填
Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。
URL string 必填
传入的Asset（素材资产）的公共可访问地址。
Name string
Asset（素材资产）的名称，上限为64个字符。
该字段仅用于使用 ListAssets 接口时模糊搜索素材，不会被带入模型推理。关于如何使用素材生成视频，请参考使用人像素材生成视频和常见问题 4。
AssetType string 必填
Asset（素材资产）的类型，支持传入图像、音频、视频。可选值：
-
Image：Asset（素材资产）的类型为图像。
-
Video：Asset（素材资产）的类型为视频。
-
Audio：Asset（素材资产）的类型为音频。
传入图像、音频、视频素材时，仅支持上传 URL ，不支持 base64。
传入单个图像要求
格式：jpeg、png、webp、bmp、tiff、gif、heic/heif
宽高比（宽/高）： (0.4, 2.5)
宽高长度（px）：(300, 6000)
大小：单张图片小于 30 MB
传入单个视频要求
格式：mp4、mov
分辨率：480p、720p
时长：单个视频时长 [2, 15] s
尺寸：
宽高比（宽/高）：[0.4, 2.5]
宽高长度（px）：[300, 6000]
总像素数：[640×640=409600, 834×1112=927408]，即宽和高的乘积符合 [409600, 927408] 的区间要求。
大小：单个视频不超过 50 MB
帧率 (FPS)：[24, 60]
传入单个音频要求
格式：wav、mp3
时长：单个音频时长 [2, 15] s
大小：单个音频不超过 15 MB
ProjectName string
资源所属的项目名称，默认值为default。
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 文档。
需要和待传入的 Asset Group（素材资产组合）的 ProjectName 保持一致。
返回参数
Id string
Asset（素材资产）的 Id。
返回示例：
ListAssets
POST /open/ListAssets
查询符合筛选条件的 Assets（素材资产）列表。
请求参数
Filter object 必填
搜索的过滤条件。
Filter.GroupIds array
Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。
Filter.GroupType string 必填
Asset Group（素材资产组合）的类型。可选值：
- AIGC：虚拟人像。
Filter.Statuses array
任务状态。
-
Active：素材资产（Asset）已处理完毕，可以使用。
-
Processing：素材资产（Asset）正在预处理，无法使用。
-
Failed：素材资产（Asset）处理失败。
Filter.Name string
Asset（素材资产）的名称，上限为64个字符。
PageNumber int (i64) 必填
搜索页码，可用于列表分页功能，从 1 开始。例如："page_number": 1，即返回第一页的搜索结果。
PageSize int (i64) 必填
每页搜索结果的数量，上限为100。
SortBy string
用于排序的字段名称，默认值 createTime。支持以下类型：
-
CreateTime：根据创建时间排序。
-
UpdateTime：根据更新时间排序。
-
GroupId：根据资产素材组的 Id 排序。
SortOrder string
排序顺序，默认值 Desc。可选值：
-
Desc：降序
-
Asc：升序
ProjectName string
资源所属的项目名称，默认值为default。
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 文档。
返回参数
Items array[]
符合筛选条件的Asset（素材资产）数组。
Items.Id string
Asset（素材资产）的 Id。
Items.name string
Asset（素材资产）的名称，上限为64个字符。
Items.URL string
Asset（素材资产）的公共可访问地址。有效期为12小时，请及时保存。
Items.GroupId string
Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。
Items.AssetType string
Asset（素材资产）的类型，支持传入图像、音频、视频。支持类型：
-
Image：Asset（素材资产）的类型为图像。
-
Video：Asset（素材资产）的类型为视频。
-
Audio：Asset（素材资产）的类型为音频。
Items.Status string
任务状态。
-
Active：素材资产（Asset）已处理完毕，可以使用。
-
Processing：素材资产（Asset）正在预处理，无法使用。
-
Failed：素材资产（Asset）处理失败。
Items.Error object
错误信息。
Items.Error.Code string
错误码。
Items.Error.Message string
错误信息。
Items.ProjectName string
资源所属的项目名称。
Items.CreateTime string
创建时间。
Items.UpdateTime string
更新时间。
TotalCount int (i64)
返回总数。
PageNumber int (i64)
返回的页数。
PageSize int (i64)
每页搜索结果的数量，上限为100。
ListAssetGroups
POST /open/ListAssetGroups
查询符合筛选条件的Asset Groups（素材资产组合）列表。
请求参数
Filter object 必填
搜索的过滤条件。
Filter.name string
Asset Group（素材资产组合）的名称，上限为64个字符。
Filter.GroupIds array
Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。
Filter.GroupType string 必填
Asset Group（素材资产组合）的类型。可选值：
- AIGC：虚拟人像。
PageNumber int (i64)
搜索页码，可用于列表分页功能，从 1 开始。例如："page_number": 1，即返回第一页的搜索结果。
PageSize int (i64)
每页搜索结果的数量，上限为100。
SortBy string
用于排序的字段名称，默认值 createTime。支持以下类型：
-
CreateTime：根据创建时间排序。
-
UpdateTime：根据更新时间排序。
SortOrder string
排序顺序，默认值 Desc。可选值：
-
Desc：降序
-
Asc：升序
ProjectName string
资源所属的项目名称，默认值为default。
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 文档。
返回参数
TotalCount int (i64)
返回的 Asset Group（素材资产组合）的总数。
Items array[]
符合筛选条件的 Asset Group（素材资产组合）数组。
Items.Id string
Asset Group（素材资产组合）的 Id。
Items.Name string
Asset Group（素材资产组合）的名称，上限为64个字符。
Items.Title string
Asset Group（素材资产组合）的标题。
已废弃，请直接使用参数 Name
Items.Description string
Asset Group（素材资产组合）的描述，上限为 300 字符。
Items.GroupType string
Asset Group（素材资产组合）的类型。
- AIGC：虚拟人像。
Items.ProjectName string
资源所属的项目名称。
Items.CreateTime string
创建时间。
Items.UpdateTime string
更新时间。
PageNumber int (i64)
返回的页数。
PageSize int (i64)
每页搜索结果的数量，上限为100。
GetAssetGroup
POST /open/GetAssetGroup
获取单个Asset Group（素材资产组合）信息。
请求参数
Id string 必填
Asset Group（素材资产组合）的 Id
ProjectName string
需要查询的 Asset Group（素材资产组合）所属的项目名称，默认值为default。
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 文档。
返回参数
Id string
Asset Group（素材资产组合）的 Id。
Name string
Asset Group（素材资产组合）的名称，上限为64个字符。
Title string
Asset Group（素材资产组合）的标题。
已废弃，请直接使用参数 Name
Description string
Asset Group（素材资产组合）的描述，上限为 300 字符。
GroupType string
Asset Group（素材资产组合）的类型。
- AIGC：虚拟人像
ProjectName string
资源所属的项目名称。
CreateTime string
创建时间。
UpdateTime string
更新时间。
GetAsset
POST /open/GetAsset
获取单个Asset（素材资产）信息。
请求参数
Id string 必填
Asset（素材资产）的 Id。
ProjectName string
需要查询的 Asset（素材资产）所属的项目名称，默认值为default。
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 文档。
返回参数
Id string
Asset（素材资产）的 Id。
Name string
Asset（素材资产）的名称，上限为64个字符。
URL string
Asset（素材资产）的访问地址。有效期为12小时，请及时保存。
AssetType string
Asset（素材资产）的类型，支持传入图像、音频、视频。支持类型：
-
Image：Asset（素材资产）的类型为图像。
-
Video：Asset（素材资产）的类型为视频。
-
Audio：Asset（素材资产）的类型为音频。
GroupId string
Asset（素材资产）所属的 Asset Group（素材资产组合）的 Id。
Status string
任务状态。
-
Active：素材资产（Asset）已处理完毕，可以使用。
-
Processing：素材资产（Asset）正在预处理，无法使用。
-
Failed：素材资产（Asset）处理失败。
Error object
错误信息。
Error.Code string
错误码。
Error.Message string
错误信息。
CreateTime string
创建时间。
UpdateTime string
更新时间。
ProjectName string
资源所属的项目名称。
UpdateAssetGroup
POST /open/UpdateAssetGroup
更新单个 Asset Group（素材资产组合）信息。当前仅支持更新 Asset Group（素材资产组合）的 Name 和 Description。
请求参数
Id string 必填
需要更新的 Asset Group（素材资产组合）的 Id。
Name string
需要更新的 Asset Group（素材资产组合）的新名称，上限为64个字符。
Description string
需要更新的 Asset Group（素材资产组合）的新描述，上限为 300 字符。
ProjectName string
需要更新的 Asset Group（素材资产组合）所属的项目名称，默认值为default。
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 文档。
返回参数
Id string
Asset Group（素材资产组合）的 Id。
UpdateAsset
POST /open/UpdateAsset
更新单个Asset（素材资产）信息。当前仅支持更新Asset（素材资产）的 Name。
请求参数
Id string 必填
需要更新的 Asset（素材资产）的 Id。
Name string
需要更新的 Asset（素材资产）的新名称，上限为64个字符。
ProjectName string
需要更新的 Asset（素材资产）所属的项目名称，默认值为default。
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 文档。
返回参数
Id string
Asset（素材资产）的 Id。
DeleteAsset
POST /open/DeleteAsset
删除单个 Asset（素材资产）。
请求参数
Id string 必填
需要删除的 Asset（素材资产）的 Id。
ProjectName string
需要删除的 Asset（素材资产）所属的项目名称，默认值为default。
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 文档。
返回参数
本接口无返回参数。
代码示例：
以下示例为使用 Asset API 创建素材资产并用于视频生成的使用链路：
创建素材资产组合：调用 CreateAssetGroup 接口创建一个素材资产组合（Asset Group），用于对同一项目或人物的素材进行统一管理。首次创建时需在控制台签署授权函。
上传素材资产并等待预处理完成：调用 CreateAsset 接口上传图片/视频/音频素材，传入素材的公共访问URL及所属的Group ID，获得素材资产ID（Asset ID）。 由于上传的素材资产需经过预处理后才能使用，可轮询调用 GetAsset 接口查询素材状态，直至状态变为
Active。若状态为Failed则表示处理失败，无法用于后续推理使用。在视频生成 API 中使用素材：当素材资产状态为
Active后，将素材ID按asset://<asset_ID>的格式拼接成URL，在视频生成API（如Seedance 2.0系列模型）的请求中，将该URL作为参考图片/视频/音频的image_url传入，即可使用该素材资产生成视频。API 鉴权方式区别说明
Asset API：Access Key 鉴权，详情参考 获取 API 访问密钥（AK/SK）。
视频生成 API：API Key 鉴权，详情参考 管理 API Key。
素材库项目（Project）隔离说明
向指定的 Asset Group（素材资产组合）内创建或查询 Asset（素材资产）时，需保证两者的 ProjectName 一致
Asset（素材资产）所属的 ProjectName 需与调用视频生成 API 接口时使用的 API key 所属的 ProjectName 一致
1. 创建素材资产组合
返回示例
2. 上传素材资产并获取素材资产信息
返回示例
更多语言的示例代码详见：
注意替换 Demo 中的 AK与SK，若需调用其他接口如 ListAssets，需替换 ACTION 与对应请求参数。
| Python | 创建素材资产组合： 上传素材资产并获取素材资产信息： |
|---|---|
| Java | 创建素材资产组合： 上传素材资产并获取素材资产信息： |
| PHP | 创建素材资产组合： 上传素材资产： |
3. 素材资产用于视频生成
注意： 在传入给模型的 Prompt 中，需要使用图片 1、视频 1 的方式指代参考素材，素材序号为素材在请求体中的顺序。请勿直接在 Prompt 中直接使用 Asset ID。 例：“图片1 里的女孩身着图片2中的服装，正在整理柜台上的物品。图片3中的男孩是一位顾客，他走上前，想要向女孩索要联系方式。”
调用示例请参考常见问题 4
当上传的素材资产状态为 Active 时，可将素材 Id 按 asset: //<asset_Id> 的规则拼接 URL，以在 视频生成 API 中使用对应的素材资产生成视频：
使用素材资产生成视频的具体调用方式请参考 【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）。
最佳实践--私域素材资产上传最佳案例
在上传素材资产时，若将目标人脸图、全身参考图及细节参考图合并为同一张图片，可能导致各参考元素在画面中占比较小，从而增加模型识别难度，造成生成视频中的人物形象与所上传素材资产出现偏差，或造成生成视频中素人脸被误识别为明星脸而触发风控拦截。
建议在上传素材资产时，将人物面部特写、服装细节等关键内容独立分割为单独的图片进行上传。具体可参考如下规则及示例：
| 应该 | 不应该 | ||
|---|---|---|---|
| 输入内容 | 给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词   |
给出背景参考图、人物妆造三视图、提示词  |
|
| 输出内容 | |||
| 总结 | 同样是古风打斗剧情：左边输入内容包括：背景参考图、人物妆造三视图、人物面部无表情特写图、提示词；中间输入内容包括：背景参考图、人物妆造三视图、提示词；右边输入内容包括：背景参考图、人物妆造正视图、提示词。左边的输出视频更加还原人物面部特征；右边的人物面部特征一致性遵循不佳。 | ||
| 输入内容 | 给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词     |
给出背景参考图、人物妆造三视图、提示词   |
给出背景参考图、人物妆造正视图、提示词   |
| 输出内容 | |||
| 总结 | 同样是温馨亲子剧情：左边输入内容包括：背景参考图、人物妆造三视图、人物面部无表情特写图、提示词；中间输入内容包括：背景参考图、人物妆造三视图、提示词；右边输入内容包括：背景参考图、人物妆造正面图、提示词。左边的输出视频更加还原人物面部特征；中间的输出视频人物面部特征一致性遵循不佳；右边人物妆造、面部特征一致性遵循不佳。 |