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

> 本文档仅限预览及邀测用户使用：
>
> * 不承诺正式 API 上线100%一致。
>
> * 仅限邀测用户阅读，请勿截图/分享给其他人员。
>
> * 您需确保上传的虚拟人像符合以下条件：
>
>   * 您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。
>
>   * 素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。
>
>   * 素材不包含违反法规、违背公序良俗、危害国家安全的内容。

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

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

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

![Image Token: CWyVbkJYSoxmeExAhjCcYDOOnPe](images/CWyVbkJYSoxmeExAhjCcYDOOnPe.png)

## 素材资产库结构说明

> 单个素材文件为一个 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`

![Image Token: NfNnbPdRUoLmRdxjoIUcwMvOnAf](images/NfNnbPdRUoLmRdxjoIUcwMvOnAf.png)

* 素材资产组：

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

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

  * 示例：

![Image Token: E58BbrAcoo1E68xdZPecGDQgn1c](images/E58BbrAcoo1E68xdZPecGDQgn1c.jpeg)

![Image Token: YX14bprrpoxvgXxHoABczW8EnNb](images/YX14bprrpoxvgXxHoABczW8EnNb.jpeg)

![Image Token: YoLEbaqR6oic3mx2Ow6cQ1j2nnf](images/YoLEbaqR6oic3mx2Ow6cQ1j2nnf.jpeg)



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

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

> **警告：**
>
> 您需确保上传的虚拟人像符合以下条件：
>
> * 您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。
>
> * 素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。
>
> * 素材不包含违反法规、违背公序良俗、危害国家安全的内容。

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

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

### 阅读并同意协议

首次入库前，需打开 [控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0\&briefType=introduce\&type=new) > **开通管理** > **开通素材资产库权限，**阅读和同意相关规则和协议：

![Image Token: ZR4SbE6GColaYKxVTFZcSW1LnFc](images/ZR4SbE6GColaYKxVTFZcSW1LnFc.png)

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

> 素材格式的具体要求，请参考[素材库结构说明](https://bytedance.larkoffice.com/docx/MpHOdxYbwobmIWxk5rucBLranJb#share-V4mMdM92woylBlxML62c5Aelneh)。

### 使用控制台

1. 打开 [方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo) > **我的素材资产** > **我的虚拟人像 > 添加虚拟人像**，或左上方 **我的资产**。

   ![Image Token: VolnbkTKkoQ81kxcksWc3Ts6nDf](images/VolnbkTKkoQ81kxcksWc3Ts6nDf.png)

   ![Image Token: R5wRbFyexonHeRxbIK1cs3ScnAd](images/R5wRbFyexonHeRxbIK1cs3ScnAd.png)



2. 创建素材组合。

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

### 使用 API

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

1. **创建素材组合**

> **注意**：
>
> * 调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考 [API访问密钥管理](https://www.volcengine.com/docs/6257/64983?lang=zh)。
>
> * API 参数信息请参考[ Asset API 参考 （WIP） 副本](https://bytedance.larkoffice.com/wiki/FtqVwjinYisraGkT5uncWyd0nEb)。

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

在请求中传入：

* **Name**：素材组合的名称。

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

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

* **ProjectName**：选填，指定资源项目名称，默认为 default。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考[文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。

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

请求示例：

**注意**：需使用 AK/SK 鉴权，详情参考 [API访问密钥管理](https://www.volcengine.com/docs/6257/64983?lang=zh)。

返回示例：

* **上传素材**

使用 **POST **`CreateAsset`接口上传素材。

在请求中提供：

* **GroupId**：必填，素材组合 ID

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

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

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

* **ProjectName**：选填，指定资源项目名称，默认为 **default**。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考[文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。

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

**注意**：

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

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

返回示例：

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

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

* **控制台**：您可在 [方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128\&tab=GenVideo) >** 我的** > **我的虚拟人像 **中搜索和查看已上传的虚拟人像资产。

* **API**：

  * **POST **`GetAsset `获取单个素材

  * **POST **`ListAssets` 查询素材

  * **POST **`ListAssetGroups` 查询素材组合信息



### 获取单个素材信息

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

> **注意**：要获取完整的 API 参数、限流等信息，请查看[ Asset API 参考 （WIP） 副本](https://bytedance.larkoffice.com/docx/DZdUd9J3lo6JTGxDrjscv1g9nVg)。

返回示例：

### 查询素材资产

可使用 **POST **ListAssets 查询 Assets。

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

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

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

> **注意**：获取完整的 API 参考文档，请查看[ Asset API 参考 （WIP） 副本](https://bytedance.larkoffice.com/docx/DZdUd9J3lo6JTGxDrjscv1g9nVg)。

返回示例：

### 查询素材组

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

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

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

> **注意**：要获取完整的 API 参考文档，请查看[ Asset API 参考 （WIP） 副本](https://bytedance.larkoffice.com/docx/DZdUd9J3lo6JTGxDrjscv1g9nVg)。

返回示例：

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

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

代码执行以下逻辑：

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

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

3. 根据 Status 判断

   * Processing → 继续轮询

   * Active → 返回 URL（结束）状态为 **Active** 后，可使用该素材 Asset ID (URI格式) 进行视频生成，如何使用人像素材生成视频，详见[下文](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe#share-GrbXdVvYjonbMkxQWHEcGf2Inlf)。

   * Failed → 返回错误（结束）

4. 返回结果并打印结果

查询结果示意如下：



## 使用人像素材生成视频

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

### 效果预览

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

### 视频生成

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

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

具体方式请参考[ 【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）](https://bytedance.larkoffice.com/wiki/SANpwJ9bgiKgrykLaMTcAB0InWc#share-ONSwd51ezoXCJqxkAm2cIC61nMX)。

示例代码：

## 常见问题

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

素材库&#x6309;**[项目](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)（Project）隔离**。

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

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

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

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

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

您可使用[访问控制](https://console.volcengine.com/iam/identitymanage/user) （IAM）精细化管理用户操作素材库的权限。可按以下方式设置：

1. **创建自定义策略**

   1. 打开[访问控制](https://console.volcengine.com/iam/policymanage) >**&#x20;新建自定义策略**

   2. 输入策略名称。

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

![Image Token: F0bnb6AanolkCVxjbTdcKMOenkh](images/F0bnb6AanolkCVxjbTdcKMOenkh.png)

* **为用户/用户组赋权**

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

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

  3. （可选）在 **限制到项目资源&#x20;**&#x4E2D;选择策略应用的项目。

  4. 点击 **提交。**

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

关于 IAM 的更多信息，请参考[访问控制](http://volcengine.com/docs/6257?lang=zh)。