video-shuoshan/docs/API文档/「保密信息」【申请权限填客户名称】私域虚拟人像素材资产库使用指南（邀测用户版）.md

「⚠️保密信息」【申请权限填客户名称】私域虚拟人像素材资产库使用指南（邀测用户版）

本文档仅限预览及邀测用户使用：

• 不承诺正式 API 上线100%一致。

• 仅限邀测用户阅读，请勿截图/分享给其他人员。

• 您需确保上传的虚拟人像符合以下条件：

  • 您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。

  • 素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。

  • 素材不包含违反法规、违背公序良俗、危害国家安全的内容。

Seedance 2.0 系列模型具有完备的防范 Deepfake 和侵犯版权风险能力。在生成视频时，会对有风险的参考素材输入进行拦截，最大限度保证生成视频合规和安全性。

为确保创作者能充分利用 Seedance 2.0 强大的视频生成能力高效生成视频内容，同时规避 AI 生成内容的潜在风险，方舟推出了私域可信素材库。完成入库的可信素材将进入您的私域素材库，在视频生成中使用。

私域素材库使用流程如下：

素材资产库结构说明

单个素材文件为一个 Asset（素材资产），每个 Asset 属于一个 Group（素材组合）。

• 可使用素材组自由管理素材。例如，可将同一人物、工作室或项目组的素材放入一个素材组合进行管理。

• 仅可使用已入库素材的 ID (Asset ID)进行视频生成，同一形象未入库素材无法使用。

• 仅需入库推理需使用的素材，不需使用的素材请勿入库。

以单人物形象为一素材组合为例：

• 素材资产：一个素材文件（图片），是方舟 Seedance 2.0 系列模型可直接用于推理的可信资产。

  • 举例：一张人物装造。

  • 文件类型：图片

  单张图片要求

  • 格式：jpeg、png、webp、bmp、tiff、gif、heic/heif

  • 宽高比（宽/高）： (0.4, 2.5)

  • 宽高长度（px）：(300, 6000)

  • 大小：单张图片小于 30 MB。

  • 资产 ID 示例：asset-20260310035119-h8tq4

• 素材资产组：

  • 可自由组合素材，以人物、工作室、项目组等维度将素材进行分组管理。

  • Group ID 示例：group-20260310035119-*****

  • 示例：

上传素材至私域虚拟人像库 （API & 控制台）

您可将自有的虚拟形象上传至私域虚拟人像库。

警告：

您需确保上传的虚拟人像符合以下条件：

• 您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。

• 素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。

• 素材不包含违反法规、违背公序良俗、危害国家安全的内容。

方舟将对您上传的素材进行安全审核。审核通过后，即可在体验中心和 API 中使用素材生成视频。

您可使用 OpenAPI 或在体验中心上传虚拟素材。

阅读并同意协议

首次入库前，需打开 控制台 > 开通管理 > 开通素材资产库权限，阅读和同意相关规则和协议：

先创建 Asset Group, 再向 Group 中添加虚拟人像素材。

素材格式的具体要求，请参考素材库结构说明。

使用控制台

1. 打开 方舟控制台 > 我的素材资产 > 我的虚拟人像 > 添加虚拟人像，或左上方 我的资产。

   

   

2. 创建素材组合。

3. 向素材组合中上传素材。

使用 API

先使用 CreateAssetGroup API 创建素材组合，再使用 CreateAsset API 向组合中上传素材。请求示例：

1. 创建素材组合

注意：

• 调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考 API访问密钥管理。

• API 参数信息请参考 Asset API 参考 （WIP） 副本。

使用 POST CreateAssetGroup 接口创建素材组合。

在请求中传入：

• Name：素材组合的名称。

• Description: 素材组合的文字描述。

• GroupType: 选填，默认为 AIGC（虚拟人像素材）。

• ProjectName：选填，指定资源项目名称，默认为 default。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考文档。

注意

如果请求中不指定 ProjectName，默认将创建素材组至 default 项目中。

请求示例：

注意：需使用 AK/SK 鉴权，详情参考 API访问密钥管理。

返回示例：

• 上传素材

使用 POST CreateAsset接口上传素材。

在请求中提供：

• GroupId：必填，素材组合 ID

• URL: 必填，图片可访问的 URL

• AssetType: 必填，仅支持上传图片类型素材，需指定为 Image

• Name: 选填，素材名称，可用于管理素材，如素材文件名。

• ProjectName：选填，指定资源项目名称，默认为 default。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考文档。

注意

如果请求中不指定 ProjectName，则默认上传素材至 default 项目中。您需使用该字段确保将素材上传至对应的项目中。

注意：

• 每次请求上传一个素材文件。

• 该请求返回素材 ID，可使用 GetAsset API 查看是否上传成功。

返回示例：

检索虚拟人像资产 （API & 控制台）

您可使用以下方式检索虚拟人像资产。

• 控制台：您可在 方舟控制台 > 我的 > 我的虚拟人像 中搜索和查看已上传的虚拟人像资产。

• API：

  • POST GetAsset 获取单个素材

  • POST ListAssets 查询素材

  • POST ListAssetGroups 查询素材组合信息

获取单个素材信息

可使用 POST GetAsset 获取单个素材信息，指定素材资产 ID。

注意：要获取完整的 API 参数、限流等信息，请查看 Asset API 参考 （WIP） 副本。

返回示例：

查询素材资产

可使用 POST ListAssets 查询 Assets。

• 支持根据组合 ID (GroupId)、素材状态（Statuses）和素材名称（Name）查询。筛选出符合所有条件的素材。

• 支持使用 Name 进行模糊搜索，同时使用 GroupId 精确搜索，便于检索所需的素材。

支持使用 SortBy，SortOrder 对结果进行排序

注意：获取完整的 API 参考文档，请查看 Asset API 参考 （WIP） 副本。

返回示例：

查询素材组

使用 POST ListAssetGroups 查询素材组合信息。

支持模糊搜索素材组合名称（Name）或提供多个素材组合（GroupId）。

如有多个素材组，可使用 Name 字段进行模糊搜索。

注意：要获取完整的 API 参考文档，请查看 Asset API 参考 （WIP） 副本。

返回示例：

示例：上传素材并使用 GetAsset 获取素材信息

以下示例创建素材资产后，查询资产 Status 并根据状态，判断是否继续查询或返回对应结果。

代码执行以下逻辑：

1. createAsset： 上传资源，获取 AssetId

2. waitForAssetActive：开始查询，循环调用 getAssetStatus 查询当前资产状态

3. 根据 Status 判断

   • Processing → 继续轮询

   • Active → 返回 URL（结束）状态为 Active 后，可使用该素材 Asset ID (URI格式) 进行视频生成，如何使用人像素材生成视频，详见下文。

   • Failed → 返回错误（结束）

4. 返回结果并打印结果

查询结果示意如下：

使用人像素材生成视频

在获取素材 Asset ID后，可使用私域人像素材生成视频。效果预览及使用方式请参考下文。

效果预览

输入：文本	输入：虚拟人像、图片	输出
图片1中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持图片2的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。

视频生成

在 Video Generation API 的 content.<模态>_url.url 字段中使用 素材 URI 生成视频。

资产 URI 拼接方式：Asset://<asset_ID>

具体方式请参考 【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）。

示例代码：

常见问题

1. 为什么素材上传成功后，无法使用素材生成视频或获取素材信息？

素材库按项目（Project）隔离。

• 在视频生成时，必须使用素材所在项目中的推理接入点进行推理。

• 如果素材上传成功，但使用获取素材接口获取素材失败，可能是因为调用上传素材(CreateAsset)和获取素材接口时传入了不同的 ProjectName。

  • ProjectName 默认值为 default，即如果不指定该字段，则默认将资源创建至 default 项目中。

  • 建议在同一个项目中管理素材。

2. 怎样管理用户对素材库的权限？

您可使用访问控制 （IAM）精细化管理用户操作素材库的权限。可按以下方式设置：

1. 创建自定义策略

   1. 打开访问控制 > 新建自定义策略

   2. 输入策略名称。

   3. 切换到 JSON编辑器，将下方自定义策略粘贴至编辑器中，点击 提交 保存。

• 为用户/用户组赋权

  1. 点击 用户管理 > 用户/用户组，选择需要赋权的用户或用户组，点击右侧的 添加权限。

  2. 在 授权策略 中选择步骤 1 中创建的策略。

  3. （可选）在 限制到项目资源 中选择策略应用的项目。

  4. 点击 提交。

完成上述操作后，该用户/用户组即可在对应项目中管理素材。

关于 IAM 的更多信息，请参考访问控制。