1006 lines
32 KiB
Markdown
1006 lines
32 KiB
Markdown
# 「⚠️保密信息」【申请权限填客户名称】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` 则表示处理失败，无法用于后续推理使用。**详情可参考：[上传素材资产并获取素材资产信息代码示例](https://bytedance.larkoffice.com/wiki/FtqVwjinYisraGkT5uncWyd0nEb#share-U55kdtSMVowUy9xkpJBcEazonpe)。**
|
||
|
||
|
||
|
||
# 素材资产（Assets）API 接口功能
|
||
|
||
## **Asset (Group) 创建接口：**
|
||
|
||
1. CreateAssetGroup：创建素材资产组合。**首次创建素材资产组合时需在控制台签署授权函，详情参考 [ 私域虚拟人像素材库 (WIP)](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe)**
|
||
|
||
2. CreateAsset：创建素材资产。该接口可用于上传个人素材资产，创建素材资产后可利用返回字段中的素材 **Id （需处于 `Active` 状态）**用于 Seedance 2.0 系列模型生成视频。
|
||
|
||
|
||
|
||
## **Asset (Group) 管理接口：**
|
||
|
||
* ListAssetGroups：查询素材资产组合列表。
|
||
|
||
* ListAssets：查询素材资产列表。
|
||
|
||
* GetAsset：查询素材资产信息。
|
||
|
||
* GetAssetGroup：查询素材资产组合信息。
|
||
|
||
* UpdateAssetGroup：更新素材资产组合信息。
|
||
|
||
* UpdateAsset：更新素材资产信息。
|
||
|
||
* DeleteAsset：删除单个素材资产。
|
||
|
||
|
||
|
||
# 鉴权方式
|
||
|
||
调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考 [获取 API 访问密钥（AK/SK）](https://www.volcengine.com/docs/6257/64983?lang=zh)。
|
||
|
||
|
||
|
||
# 限流要求
|
||
|
||
* 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)](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe)**
|
||
|
||
## 请求参数
|
||
|
||
### **Name** `string` `必填`
|
||
|
||
Asset Group（素材资产组合）的名称，上限为 64 字符。
|
||
|
||
***
|
||
|
||
### **Description** `string`
|
||
|
||
Asset Group（素材资产组合）的描述，上限为 300 字符。
|
||
|
||
***
|
||
|
||
### **GroupType  **`string`
|
||
|
||
Asset Group（素材资产组合）的类型。可选值：
|
||
|
||
* AIGC：虚拟人像。
|
||
|
||
> 当前仅支持 AIGC 类型。
|
||
|
||
|
||
|
||
***
|
||
|
||
### **ProjectName **`string`** **
|
||
|
||
资源所属的项目名称，默认值为`default`。
|
||
|
||
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
|
||
|
||
***
|
||
|
||
|
||
|
||
## 返回参数
|
||
|
||
### **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 接口时模糊搜索素材，不会被带入模型推理。关于如何使用素材生成视频，请参考[使用人像素材生成视频](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe#share-QF2qdZE5HoRkRDxfs9bcmqECnDb)和[常见问题 4](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe#share-YOKvdYHjro8EjtxucWaczf6vneg)。
|
||
|
||
***
|
||
|
||
### **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`。
|
||
|
||
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
|
||
|
||
> 需要和待传入的 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`。
|
||
|
||
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
|
||
|
||
***
|
||
|
||
|
||
|
||
## 返回参数
|
||
|
||
### **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`。
|
||
|
||
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
|
||
|
||
***
|
||
|
||
|
||
|
||
## 返回参数
|
||
|
||
### **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`。
|
||
|
||
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
|
||
|
||
***
|
||
|
||
|
||
|
||
## 返回参数
|
||
|
||
### **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`。
|
||
|
||
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
|
||
|
||
***
|
||
|
||
|
||
|
||
## 返回参数
|
||
|
||
### **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`。
|
||
|
||
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
|
||
|
||
***
|
||
|
||
|
||
|
||
## 返回参数
|
||
|
||
### **Id** `string`
|
||
|
||
Asset Group（素材资产组合）的 Id。
|
||
|
||
***
|
||
|
||
|
||
|
||
|
||
|
||
# **UpdateAsset**
|
||
|
||
> **POST **/open/UpdateAsset
|
||
|
||
更新单个Asset（素材资产）信息。当前仅支持更新Asset（素材资产）的 Name。
|
||
|
||
## 请求参数
|
||
|
||
### **Id **`string` `必填`
|
||
|
||
需要更新的 Asset（素材资产）的 Id。
|
||
|
||
***
|
||
|
||
### **Name **`string` 
|
||
|
||
需要更新的 Asset（素材资产）的新名称，上限为64个字符。
|
||
|
||
***
|
||
|
||
### **ProjectName** `string`
|
||
|
||
需要更新的 Asset（素材资产）所属的项目名称，默认值为`default`。
|
||
|
||
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
|
||
|
||
***
|
||
|
||
|
||
|
||
## 返回参数
|
||
|
||
### **Id** `string`
|
||
|
||
Asset（素材资产）的 Id。
|
||
|
||
***
|
||
|
||
|
||
|
||
# **DeleteAsset**
|
||
|
||
> **POST **/open/DeleteAsset
|
||
|
||
删除单个 Asset（素材资产）。
|
||
|
||
## 请求参数
|
||
|
||
### **Id **`string` `必填`
|
||
|
||
需要删除的 Asset（素材资产）的 Id。
|
||
|
||
***
|
||
|
||
### **ProjectName** `string`
|
||
|
||
需要删除的 Asset（素材资产）所属的项目名称，默认值为`default`。
|
||
|
||
若资源不在默认项目中，需填写正确的项目名称，获取项目名称，请查看 [文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
|
||
|
||
***
|
||
|
||
|
||
|
||
## 返回参数
|
||
|
||
本接口无返回参数。
|
||
|
||
***
|
||
|
||
|
||
|
||
# 代码示例：
|
||
|
||
> **以下示例为使用 Asset API 创建素材资产并用于视频生成的使用链路：**
|
||
>
|
||
> 1. **创建素材资产组合：**调用 **CreateAssetGroup** 接口创建一个素材资产组合（Asset Group），用于对同一项目或人物的素材进行统一管理。首次创建时需在控制台签署授权函。
|
||
>
|
||
> 2. **上传素材资产并等待预处理完成：**调用 **CreateAsset** 接口上传图片/视频/音频素材，传入素材的公共访问URL及所属的Group ID，获得素材资产ID（Asset ID）。
|
||
> 由于上传的素材资产需经过预处理后才能使用，可轮询调用 **GetAsset** 接口查询素材状态，直至状态变为 `Active`。若状态为 `Failed` 则表示处理失败，无法用于后续推理使用。
|
||
>
|
||
> 3. **在视频生成 API 中使用素材：**当素材资产状态为 `Active` 后，将素材ID按 `asset://<asset_ID`**`>`** 的格式拼接成URL，在视频生成API（如Seedance 2.0系列模型）的请求中，将该URL作为参考图片/视频/音频的 `image_url` 传入，即可使用该素材资产生成视频。
|
||
>
|
||
> **API 鉴权方式区别说明**
|
||
>
|
||
> * **Asset API：**Access Key 鉴权，详情参考 [获取 API 访问密钥（AK/SK）](https://www.volcengine.com/docs/6257/64983?lang=zh)。
|
||
>
|
||
> * **视频生成 API：**API Key 鉴权，详情参考 [管理 API Key](https://www.volcengine.com/docs/82379/1361424?lang=zh)。
|
||
>
|
||
> **素材库[项目](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)（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](https://bytedance.larkoffice.com/wiki/RtHgwpJgviwFXLkQ9hLcRooEnVe#share-YOKvdYHjro8EjtxucWaczf6vneg)
|
||
|
||
当上传的素材资产状态为 `Active` 时，可将素材 Id 按 `asset: //<asset_Id>` 的规则拼接 URL，以在 **视频生成 API **中使用对应的素材资产生成视频：
|
||
|
||
使用素材资产生成视频的具体调用方式请参考[ 【申请权限填客户名称】Seedance 2.0 & 2.0 fast API文档（邀测用户版）](https://bytedance.larkoffice.com/wiki/SANpwJ9bgiKgrykLaMTcAB0InWc#share-ONSwd51ezoXCJqxkAm2cIC61nMX)。
|
||
|
||
|
||
|
||
# 最佳实践--私域素材资产上传最佳案例
|
||
|
||
> 在上传素材资产时，**若将目标人脸图、全身参考图及细节参考图合并为同一张图片，可能导致各参考元素在画面中占比较小，从而增加模型识别难度**，造成生成视频中的人物形象与所上传素材资产出现偏差，或造成生成视频中素人脸被误识别为明星脸而触发风控拦截。
|
||
|
||
建议在上传素材资产时，将人物面部特写、服装细节等关键内容独立分割为单独的图片进行上传。具体可参考如下规则及示例：
|
||
|
||
| | 应该 | 不应该 | |
|
||
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 输入内容 | 给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词 | 给出背景参考图、人物妆造三视图、提示词 | |
|
||
| 输出内容 | | | |
|
||
| 总结 | 同样是古风打斗剧情：左边输入内容包括：背景参考图、**人物妆造三视图**、**人物面部无表情特写图**、提示词；中间输入内容包括：背景参考图、人物妆造三视图、提示词；右边输入内容包括：背景参考图、人物妆造正视图、提示词。左边的输出视频更加还原人物面部特征；右边的人物面部特征一致性遵循不佳。 | | |
|
||
| 输入内容 | 给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词 | 给出背景参考图、人物妆造三视图、提示词 | 给出背景参考图、人物妆造正视图、提示词 |
|
||
| 输出内容 | | | |
|
||
| 总结 | 同样是温馨亲子剧情：左边输入内容包括：背景参考图、**人物妆造三视图、人物面部无表情特写图**、提示词；中间输入内容包括：背景参考图、人物妆造三视图、提示词；右边输入内容包括：背景参考图、人物妆造正面图、提示词。左边的输出视频更加还原人物面部特征；中间的输出视频人物面部特征一致性遵循不佳；右边人物妆造、面部特征一致性遵循不佳。 | | |
|
||
|