315 lines
13 KiB
Markdown
315 lines
13 KiB
Markdown
# 「⚠️保密信息」【申请权限填客户名称】私域虚拟人像素材资产库使用指南（邀测用户版）
|
||
|
||
> 本文档仅限预览及邀测用户使用：
|
||
>
|
||
> * 不承诺正式 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 或在体验中心上传虚拟素材。
|
||
|
||
### 阅读并同意协议
|
||
|
||
首次入库前，需打开 [控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0\&briefType=introduce\&type=new) > **开通管理** > **开通素材资产库权限，**阅读和同意相关规则和协议：
|
||
|
||
|
||
|
||
先创建 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) > **我的素材资产** > **我的虚拟人像 > 添加虚拟人像**，或左上方 **我的资产**。
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
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**的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。 |  | |
|
||
|
||
### 视频生成
|
||
|
||
在 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. 为什么素材上传成功后，无法使用素材生成视频或获取素材信息？
|
||
|
||
素材库按**[项目](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) >** 新建自定义策略**
|
||
|
||
2. 输入策略名称。
|
||
|
||
3. 切换到 **JSON编辑器**，将下方自定义策略粘贴至编辑器中，点击 **提交** 保存。
|
||
|
||
|
||
|
||
* **为用户/用户组赋权**
|
||
|
||
1. 点击 **用户管理** > **用户**/**用户组**，选择需要赋权的用户或用户组，点击右侧的 **添加权限。**
|
||
|
||
2. 在 **授权策略** 中选择**步骤 1** 中创建的策略。
|
||
|
||
3. （可选）在 **限制到项目资源 **中选择策略应用的项目。
|
||
|
||
4. 点击 **提交。**
|
||
|
||
完成上述操作后，该用户/用户组即可在对应项目中管理素材。
|
||
|
||
关于 IAM 的更多信息，请参考[访问控制](http://volcengine.com/docs/6257?lang=zh)。
|
||
|
||
|
||
|