f2dc8d4713
All checks were successful
Build and Deploy / build-and-deploy (push) Successful in 11m59s
之前 DELETE /api/v1/assets/groups/<id> 的做法是循环调 DeleteAsset 再
删本地记录，现在火山开放了 DeleteAssetGroup（文档明确级联删除组内所有
Asset），改为一次调用，原子、快、无半成功。
变更
- backend/utils/assets_client.py:
- ApiInfo 注册 DeleteAssetGroup
- 新增 delete_asset_group(group_id)
- backend/apps/generation/views.py:
- asset_group_detail_view DELETE 分支改为一次 delete_asset_group
- 加幂等保护: 火山返回 NotFound.group_id 时继续清本地, 修复场景为
用户在火山控制台手删素材组后本地 DB 出现孤儿, 再在前端点一次
"删除素材组"即可清掉本地残留
测试 (airlabs-test)
- assets_client 4 项 PASS: 创建 → 删除 → 验证 gone → 重删返回
NotFound.group_id → 纯假 id 同样 NotFound.group_id
- view 层 2 场景 PASS:
- A 火山+本地都在 → 都清空
- B 火山侧已手删, 本地还在 → 本地也能清
文档整理
- docs/API文档/about-Asset-素材组相关/ 新增 8 个火山最新 Asset API 文档
(CreateAsset/Group, List*, Get*, Update*, Delete*), 原"使用指南"移入
该目录归档
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
821 lines
34 KiB
Markdown
821 lines
34 KiB
Markdown
:::danger
|
||
* 仅限邀测用户阅读，请勿截图/分享给其他人员。
|
||
* 上传素材 （CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。
|
||
* 素材资产应为虚拟人像，非虚拟人像类素材无需入库。
|
||
* 您需确保上传的虚拟人像符合以下条件：
|
||
* 您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。
|
||
* 素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。
|
||
* 素材不包含违反法规、违背公序良俗、危害国家安全的内容。
|
||
:::
|
||
Seedance 2.0 系列模型具有完备的防范 Deepfake 和侵犯版权风险能力。在生成视频时，会对有风险的参考素材输入进行拦截，最大限度保证生成视频合规和安全性。
|
||
为确保创作者能充分利用 Seedance 2.0 强大的视频生成能力高效生成视频内容，同时规避 AI 生成内容的潜在风险，方舟推出了私域可信素材库。完成入库的可信素材将进入您的私域素材库，在视频生成中使用。
|
||
私域素材库使用流程如下：
|
||
<div style="text-align: center"><img src="https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/fa131ff017324d228b8a07c9bde49d4d~tplv-goo7wpa0wc-image.image" width="3866px" /></div>
|
||
|
||
<span id="2b7bf522"></span>
|
||
# 素材资产库结构说明
|
||
|
||
* **Asset Group（素材资产组合）**：单个素材文件为一个 Asset，每个 Asset 属于一个 Asset Group。
|
||
* 可以使用素材组自由管理素材，例如可将同一虚拟人物素材放入同一素材组合进行管理。
|
||
* **Asset（素材资产）**：一个素材文件（当前支持上传图像、视频、音频），是方舟 Seedance 2.0 系列模型可直接用于推理的可信资产。
|
||
|
||
:::tip
|
||
注意
|
||
|
||
* 仅需入库推理需使用的素材资产，不需使用的素材资产请勿入库。
|
||
* 仅可使用已入库素材资产的 Id (Asset ID) 进行视频生成，同一形象未入库素材无法使用。
|
||
* 每个上传的素材资产需经过预处理，可轮询调用 **GetAsset** 接口查询素材状态（对应参数为 **Status）**，仅当状态变为 `Active` 后，该素材资产方可用于后续推理使用；若状态为 `Failed` 则表示处理失败，无法用于后续推理使用。**详情可参考**[示例：上传素材并使用 GetAsset 获取素材信息](/docs/82379/2333565#5c0ee427)**。**
|
||
:::
|
||
**以图像资产上传为例：**
|
||
|
||
* **单张图片文件格式要求：**
|
||
* 格式：jpeg、png、webp、bmp、tiff、gif、heic/heif
|
||
* 宽高比（宽/高）： (0.4, 2.5)
|
||
* 宽高长度（px）：(300, 6000)
|
||
* 大小：单张图片小于 30 MB。
|
||
* 为保证上传的图片素材资产在后续生成视频时，**人物面部、服装细节等与上传的素材资产一致，**推荐按照如下规则及示例将同一人物的多个素材传入同一资产组合：
|
||
* **人像资产内容最佳实践：**
|
||
|
||
:::tip
|
||
**全身参考图要求**
|
||
|
||
* 板式：竖版
|
||
* 图片内容：人物全身正面图片
|
||
:::
|
||
<div style="text-align: center"><img src="https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/86fef6988c8449c2a3d9062b2fa50e96~tplv-goo7wpa0wc-image.image" width="333px" /></div>
|
||
|
||
:::tip
|
||
**人脸特写图要求**
|
||
|
||
* 板式： 竖版
|
||
* 图片内容：人物正面无表情特写，肩部以上，人物面部占画面2/3左右
|
||
:::
|
||
<div style="text-align: center"><img src="https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/6188f2b280eb43a3821644071a2c5485~tplv-goo7wpa0wc-image.image" width="272px" /></div>
|
||
|
||
|
||
<span id="d54e09a3"></span>
|
||
# 素材资产（Assets）API 接口功能
|
||
:::warning
|
||
调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考 [获取 API 访问密钥（AK/SK）](https://www.volcengine.com/docs/6257/64983?lang=zh)。
|
||
:::
|
||
<span id="85305caa"></span>
|
||
## 接口列表
|
||
<span id="72169511"></span>
|
||
## **Asset (Group) 创建接口**
|
||
|
||
1. [CreateAssetGroup](https://www.volcengine.com/docs/82379/2318270)：创建素材资产组合。**首次创建素材资产组合时需在控制台签署授权函，详情参考**[私域虚拟人像素材资产库使用指南（邀测用户版）](/docs/82379/2333565)
|
||
2. [CreateAsset](https://www.volcengine.com/docs/82379/2318271)：创建素材资产。该接口可用于上传个人素材资产，创建素材资产后可利用返回字段中的素材 **Id （需处于** **`Active` 状态）**用于 Seedance 2.0 系列模型生成视频。
|
||
|
||
<span id="5e9c0b10"></span>
|
||
## **Asset (Group) 管理接口**
|
||
|
||
* [ListAssetGroups](https://www.volcengine.com/docs/82379/2318272)：查询素材资产组合列表。
|
||
* [ListAssets](https://www.volcengine.com/docs/82379/2318273)：查询素材资产列表。
|
||
* [GetAsset](https://www.volcengine.com/docs/82379/2318274)：查询素材资产信息。
|
||
* [GetAssetGroup](https://www.volcengine.com/docs/82379/2318275)：查询素材资产组合信息。
|
||
* [UpdateAssetGroup](https://www.volcengine.com/docs/82379/2318276)：更新素材资产组合信息。
|
||
* [UpdateAsset](https://www.volcengine.com/docs/82379/2318277)：更新素材资产信息。
|
||
* [DeleteAsset](https://www.volcengine.com/docs/82379/2318278)：删除单个素材资产。
|
||
* [DeleteAssetGroup](https://www.volcengine.com/docs/82379/2341606): 删除指定素材组。
|
||
|
||
<span id="987b4caa"></span>
|
||
## 限流要求
|
||
:::tip
|
||
* **QPS**：API 接口**每秒**允许的请求总数上限，超出则请求报错。
|
||
* **QPM**：API 接口**每分钟**允许的请求总数上限，超出则请求报错。
|
||
:::
|
||
|
||
| | | \
|
||
|接口名 |账号维度的限流 |
|
||
|---|---|
|
||
| | | \
|
||
|CreateAssetGroup |10 QPS |
|
||
| | | \
|
||
|CreateAsset |300 QPM |
|
||
| | | \
|
||
|ListAssetGroups |10 QPS |
|
||
| | | \
|
||
|ListAssets |10 QPS |
|
||
| | | \
|
||
|GetAsset |100 QPS |
|
||
| | | \
|
||
|GetAssetGroup |10 QPS |
|
||
| | | \
|
||
|UpdateAsset |10 QPS |
|
||
| | | \
|
||
|UpdateAssetGroup |10 QPS |
|
||
| | | \
|
||
|DeleteAsset |10 QPS |
|
||
| | | \
|
||
|DeleteAssetGroup |5 QPS |
|
||
|
||
<span id="5d0da843"></span>
|
||
# 使用教程
|
||
<span id="b4a41fe1"></span>
|
||
## 上传素材至私域虚拟人像库 （API & 控制台）
|
||
您可将自有的虚拟形象上传至私域虚拟人像库。
|
||
:::danger
|
||
您需确保上传的虚拟人像符合以下条件：
|
||
您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。
|
||
素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。
|
||
素材不包含违反法规、违背公序良俗、危害国家安全的内容。
|
||
:::
|
||
方舟将对您上传的素材进行安全审核。审核通过后，即可在体验中心和 API 中使用素材生成视频。
|
||
您可使用 OpenAPI 或在体验中心上传虚拟素材。
|
||
<span id="65934594"></span>
|
||
### 阅读并同意协议
|
||
首次入库前，需打开 [控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new) > **开通管理** > **开通素材资产库权限，**阅读和同意相关规则和协议：
|
||
<div style="text-align: center"><img src="https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/4b083981c8ca48ddbcedd6e750061626~tplv-goo7wpa0wc-image.image" width="2938px" /></div>
|
||
|
||
先创建 Asset Group, 再向 Group 中添加虚拟人像素材。
|
||
:::tip
|
||
素材格式的具体要求，请参考[素材资产库结构说明](/docs/82379/2333565#2b7bf522)。
|
||
:::
|
||
<span id="f9a31891"></span>
|
||
### 使用控制台
|
||
|
||
1. 打开 [方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/experience/vision?modelId=doubao-seedance-2-0-260128&tab=GenVideo) > **我的** > **虚拟人像**。
|
||
|
||
|
||
|
||
2. 创建素材组合。
|
||
3. 向素材组合中上传素材。
|
||
|
||
<span id="f96dab35"></span>
|
||
### 使用 API
|
||
先调用 `CreateAssetGroup` 接口创建素材组合，再调用 `CreateAsset` 接口向组合中上传素材。请求示例：
|
||
|
||
1. **创建素材组合**
|
||
|
||
:::tip
|
||
**注意**：
|
||
|
||
* 调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考 [API访问密钥管理](https://www.volcengine.com/docs/6257/64983?lang=zh)。
|
||
* API 参数信息请参考[私域虚拟人像库 API 参考文档](/docs/82379/2333601)。
|
||
* **素材库**[项目](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)**（Project）隔离说明**
|
||
向指定的 Asset Group（素材资产组合）内创建或查询 Asset（素材资产）时，需保证两者的 **ProjectName** 一致
|
||
Asset（素材资产）所属的 **ProjectName** 需与调用视频生成 API 接口时使用的 API key 所属的 **ProjectName** 一致
|
||
:::
|
||
使用 **POST` `**`CreateAssetGroup` 接口创建素材组合。
|
||
在请求中传入：
|
||
|
||
* **Name**：素材组合的名称。
|
||
* **Description**: 素材组合的文字描述。
|
||
* **GroupType**: 选填，默认为 AIGC（虚拟人像素材）。
|
||
|
||
:::tip
|
||
当前仅支持 AIGC 类型。
|
||
:::
|
||
|
||
* **ProjectName**：选填，指定资源项目名称，默认为 default。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考[文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
|
||
|
||
:::tip
|
||
**注意**：
|
||
如果请求中不指定 **ProjectName**，默认将创建素材组至 **default** 项目中。
|
||
:::
|
||
请求示例：
|
||
**注意**：需使用 AK/SK 鉴权，详情参考 [API访问密钥管理](https://www.volcengine.com/docs/6257/64983?lang=zh)。
|
||
```Go
|
||
package main
|
||
|
||
import (
|
||
"fmt"
|
||
|
||
"github.com/bytedance/sonic"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/session"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/universal"
|
||
)
|
||
|
||
func main() {
|
||
config := volcengine.NewConfig().WithCredentials(credentials.NewStaticCredentials("<YOUR_AK>", "<YOUR_SK>", "")).WithRegion("cn-beijing")
|
||
sess, _ := session.NewSession(config)
|
||
resp, err := universal.New(sess).DoCall(
|
||
universal.RequestUniversal{
|
||
ServiceName: "ark",
|
||
Action: "CreateAssetGroup",
|
||
Version: "2024-01-01",
|
||
HttpMethod: universal.POST,
|
||
ContentType: universal.ApplicationJSON,
|
||
},
|
||
&map[string]any{
|
||
"Name": "figure_group_1",
|
||
"Description": "Figure group 1",
|
||
"ProjectName": "<PROJECT_NAME>",
|
||
},
|
||
)
|
||
if err != nil {
|
||
fmt.Printf("error: %v\n", err)
|
||
return
|
||
}
|
||
if resp == nil {
|
||
return
|
||
}
|
||
respData, err := sonic.Marshal(resp)
|
||
fmt.Println(string(respData))
|
||
}
|
||
```
|
||
|
||
返回示例：
|
||
```JSON
|
||
{
|
||
"Id":"group-20260318033332-*****"}
|
||
```
|
||
|
||
|
||
2. **上传素材**
|
||
|
||
:::danger
|
||
上传素材 （CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。
|
||
视频素材处理将耗费更长时间。
|
||
:::
|
||
使用 **POST** `CreateAsset`接口上传素材。
|
||
在请求中提供：
|
||
|
||
* **GroupId**：必填，素材组合 ID
|
||
* **URL**: 必填，图片/视频/音频可访问的 URL
|
||
* **AssetType**: 必填，支持上传图片/视频/音频类型素材，需指定为 **Image/Video/Audio。**素材文件的具体限制详见 [Assets API 参考文档](https://www.volcengine.com/docs/82379/2318271)**。**
|
||
* **Name**: 选填，素材名称，可用于管理素材，如素材文件名。
|
||
|
||
:::tip
|
||
该字段仅用于使用 ListAssets 接口时模糊搜索素材，不会被带入模型推理。关于如何使用素材生成视频，请参考[使用虚拟人像](/docs/82379/2291680#2bf01416) 和[3. 提示词（content.text）中应该如何准确指代参考素材？](/docs/82379/2333565#15e21eb8)。
|
||
:::
|
||
|
||
* **ProjectName**：选填，指定资源项目名称，默认为 **default**。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考[文档](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)。
|
||
|
||
:::tip
|
||
**注意**
|
||
如果请求中不指定 **ProjectName**，则默认上传素材至 **default** 项目中。您需使用该字段确保将素材上传至对应的项目中。
|
||
:::
|
||
**注意**：
|
||
|
||
* 每次请求上传一个素材文件。
|
||
* 该请求返回素材 ID，可使用 GetAsset API 查看是否上传成功。
|
||
|
||
```Go
|
||
package main
|
||
|
||
import (
|
||
"fmt"
|
||
|
||
"github.com/bytedance/sonic"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/session"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/universal"
|
||
)
|
||
|
||
func main() {
|
||
config := volcengine.NewConfig().WithCredentials(credentials.NewStaticCredentials("<YOUR_AK>", "<YOUR_SK>", "")).WithRegion("cn-beijing")
|
||
sess, _ := session.NewSession(config)
|
||
resp, err := universal.New(sess).DoCall(
|
||
universal.RequestUniversal{
|
||
ServiceName: "ark",
|
||
Action: "CreateAsset",
|
||
Version: "2024-01-01",
|
||
HttpMethod: universal.POST,
|
||
ContentType: universal.ApplicationJSON,
|
||
},
|
||
&map[string]any{
|
||
"GroupId": "group-20260318070359-*****",
|
||
"URL": "<IMAGE_URL>",
|
||
"AssetType": "Image",
|
||
"ProjectName": "<PROJECT_NAME>"
|
||
},
|
||
)
|
||
if err != nil {
|
||
fmt.Printf("error: %v\n", err)
|
||
return
|
||
}
|
||
if resp == nil {
|
||
return
|
||
}
|
||
respData, err := sonic.Marshal(resp)
|
||
fmt.Println(string(respData))
|
||
}
|
||
```
|
||
|
||
返回示例：
|
||
```JSON
|
||
{
|
||
"Id": "asset-20260318071009-*****"
|
||
}
|
||
```
|
||
|
||
<span id="cd721316"></span>
|
||
## 检索虚拟人像资产 （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` 查询素材组合信息
|
||
|
||
<span id="a32de856"></span>
|
||
### 获取单个素材信息
|
||
可使用 **POST** GetAsset 获取单个素材信息，指定素材资产 ID。
|
||
:::tip
|
||
要获取完整的 API 参数、限流等信息，请查看[私域虚拟人像库 API 参考文档](/docs/82379/2333601)。
|
||
:::
|
||
```Go
|
||
package main
|
||
|
||
import (
|
||
"fmt"
|
||
|
||
"github.com/bytedance/sonic"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/session"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/universal"
|
||
)
|
||
|
||
func main() {
|
||
config := volcengine.NewConfig().WithCredentials(credentials.NewStaticCredentials("your_ak", "your_sk", "")).WithRegion("cn-beijing")
|
||
sess, _ := session.NewSession(config)
|
||
resp, err := universal.New(sess).DoCall(
|
||
universal.RequestUniversal{
|
||
ServiceName: "ark",
|
||
Action: "GetAsset",
|
||
Version: "2024-01-01",
|
||
HttpMethod: universal.POST,
|
||
ContentType: universal.ApplicationJSON,
|
||
},
|
||
&map[string]any{
|
||
"Id": "asset-20260318070533-*****",
|
||
"ProjectName": "<PROJECT_NAME>", // 需确保填入素材所在项目的名称
|
||
},
|
||
)
|
||
if err != nil {
|
||
fmt.Printf("error: %v\n", err)
|
||
return
|
||
}
|
||
if resp == nil {
|
||
return
|
||
}
|
||
respData, err := sonic.Marshal(resp)
|
||
fmt.Println(string(respData))
|
||
}
|
||
```
|
||
|
||
返回示例：
|
||
```JSON
|
||
{
|
||
"GroupId": "group-20260318033332-*****",
|
||
"Status": "Active",
|
||
"CreateTime": "2026-03-18T03:57:10Z",
|
||
"AssetType": "Image",
|
||
"UpdateTime": "2026-03-18T03:57:14Z",
|
||
"ProjectName": "default",
|
||
"Id": "asset-20260318035710-*****",
|
||
"Name": "",
|
||
"URL": "https://ark-media-asset-stg.tos-cn-beijing.volces.com/2100000825/031807095608757847.jpg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=****&X-Tos-Expires=43200&X-Tos-Security-Token=****&X-Tos-Signature=****&X-Tos-SignedHeaders=host" // 有效期为 12 小时
|
||
}
|
||
```
|
||
|
||
|
||
<span id="8910c01c"></span>
|
||
### 查询素材资产
|
||
可使用 **POST** ListAssets 查询 Assets。
|
||
|
||
* 支持根据组合 ID (GroupId)、素材状态（Statuses）和素材名称（Name）查询。筛选出符合所有条件的素材。
|
||
* 支持使用 Name 进行模糊搜索，同时使用 GroupId 精确搜索，便于检索所需的素材。
|
||
|
||
支持使用 SortBy，SortOrder 对结果进行排序。
|
||
```Go
|
||
package main
|
||
|
||
import (
|
||
"fmt"
|
||
|
||
"github.com/bytedance/sonic"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/session"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/universal"
|
||
)
|
||
|
||
func main() {
|
||
config := volcengine.NewConfig().WithCredentials(credentials.NewStaticCredentials("<YOUR_AK>", "<YOUR_SK>", "")).WithRegion("cn-beijing")
|
||
sess, _ := session.NewSession(config)
|
||
resp, err := universal.New(sess).DoCall(
|
||
universal.RequestUniversal{
|
||
ServiceName: "ark",
|
||
Action: "ListAssets",
|
||
Version: "2024-01-01",
|
||
HttpMethod: universal.POST,
|
||
ContentType: universal.ApplicationJSON,
|
||
},
|
||
&map[string]any{
|
||
"Filter": map[string]any{
|
||
"GroupIds": []string{"group-20260318033332-*****"},
|
||
"GroupType": "AIGC",
|
||
"Statuses": []string{"Active", "Processing"}, // 支持 Active（素材上传成功，可使用Asset ID）, Processing（素材处理中）, Failed（素材上传失败）
|
||
"Name": "figure", // 支持模糊搜索
|
||
},
|
||
"PageNumber": 1,
|
||
"PageSize": 10,
|
||
"SortBy": "GroupId",
|
||
"SortOrder": "Asc",
|
||
},
|
||
)
|
||
if err != nil {
|
||
fmt.Printf("list assets error: %v\n", err)
|
||
return
|
||
}
|
||
if resp == nil {
|
||
return
|
||
}
|
||
respData, err := sonic.Marshal(resp)
|
||
fmt.Println(string(respData))
|
||
}
|
||
```
|
||
|
||
返回示例：
|
||
```JSON
|
||
"Items": [
|
||
{
|
||
"Id": "asset-20260318035710-kctzf",
|
||
"Name": "",
|
||
"AssetType": "Image",
|
||
"CreateTime": "2026-03-18T03:57:10Z",
|
||
"UpdateTime": "2026-03-18T03:57:14Z",
|
||
"ProjectName": "default",
|
||
"URL": "image_url", // 有效期为 12 小时
|
||
"GroupId": "group-20260318033332-*****",
|
||
"Status": "Active"
|
||
},
|
||
{
|
||
"GroupId": "group-20260318033332-*****",
|
||
"Status": "Active",
|
||
"Id": "asset-20260318034804-*****",
|
||
"Name": "",
|
||
"URL": "https://ark-media-asset-stg.tos-cn-beijing.volces.com/2100000825/031807095608757847.jpg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=****&X-Tos-Expires=43200&X-Tos-Security-Token=****&X-Tos-Signature=****&X-Tos-SignedHeaders=host",
|
||
"AssetType": "Image",
|
||
"CreateTime": "2026-03-18T03:48:04Z",
|
||
"UpdateTime": "2026-03-18T03:48:08Z",
|
||
"ProjectName": "default"
|
||
}
|
||
],
|
||
"TotalCount": 2,
|
||
"PageNumber": 1,
|
||
"PageSize": 10
|
||
```
|
||
|
||
<span id="f95b9753"></span>
|
||
### 查询素材组
|
||
使用 **POST** ListAssetGroups 查询素材组合信息。
|
||
支持模糊搜索素材组合名称（Name）或提供多个素材组合（GroupId）。
|
||
如有多个素材组，可使用 Name 字段进行模糊搜索。
|
||
:::tip
|
||
要获取完整的 API 参考文档，请查看[私域虚拟人像库 API 参考文档](/docs/82379/2333601)。
|
||
:::
|
||
```Go
|
||
package main
|
||
|
||
import (
|
||
"fmt"
|
||
|
||
"github.com/bytedance/sonic"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/session"
|
||
"github.com/volcengine/volcengine-go-sdk/volcengine/universal"
|
||
)
|
||
|
||
func main() {
|
||
config := volcengine.NewConfig().WithCredentials(credentials.NewStaticCredentials("<YOUR_AK>", "<YOUR_SK>", "")).WithRegion("cn-beijing")
|
||
sess, _ := session.NewSession(config)
|
||
resp, err := universal.New(sess).DoCall(
|
||
universal.RequestUniversal{
|
||
ServiceName: "ark",
|
||
Action: "ListAssetGroups",
|
||
Version: "2024-01-01",
|
||
HttpMethod: universal.POST,
|
||
ContentType: universal.ApplicationJSON,
|
||
},
|
||
&map[string]any{
|
||
"Filter": map[string]any{
|
||
"Name": "figure_group", // Support fuzzy search
|
||
"GroupIds": []string{"group-20260318033332-*****"},
|
||
"GroupType": "AIGC",
|
||
},
|
||
"PageNumber": 1,
|
||
"PageSize": 10,
|
||
},
|
||
)
|
||
if err != nil {
|
||
fmt.Printf("error: %v\n", err)
|
||
return
|
||
}
|
||
if resp == nil {
|
||
return
|
||
}
|
||
respData, err := sonic.Marshal(resp)
|
||
fmt.Println(string(respData))
|
||
}
|
||
```
|
||
|
||
返回示例：
|
||
```JSON
|
||
{
|
||
"TotalCount": 1,
|
||
"Items": [
|
||
{
|
||
"UpdateTime": "2026-03-18T03:33:32Z",
|
||
"Id": "group-20260318033332-*****",
|
||
"Name": "figure_group_1",
|
||
"Title": "figure_group_1",
|
||
"Description": "Figure group 1",
|
||
"GroupType": "AIGC",
|
||
"ProjectName": "default",
|
||
"CreateTime": "2026-03-18T03:33:32Z"
|
||
}
|
||
],
|
||
"PageNumber": 1,
|
||
"PageSize": 10
|
||
}
|
||
```
|
||
|
||
<span id="e545fe77"></span>
|
||
### 更新/删除素材和素材组
|
||
请参考: [私域虚拟人像库 API 参考文档](/docs/82379/2333601)。
|
||
<span id="5c0ee427"></span>
|
||
## 示例：上传素材并使用 GetAsset 获取素材信息
|
||
以下示例创建素材资产后，查询资产 Status 并根据状态，判断是否继续查询或返回对应结果。
|
||
代码执行以下逻辑：
|
||
|
||
1. createAsset： 上传资源，获取 AssetId
|
||
2. waitForAssetActive：开始查询，循环调用 getAssetStatus 查询当前资产状态
|
||
3. 根据 Status 判断
|
||
* Processing → 继续轮询
|
||
* Active → 返回 URL（结束）状态为 `Active` 后，可使用该素材 Asset ID (URI格式) 进行视频生成，如何使用人像素材生成视频，详见[使用虚拟人像](/docs/82379/2291680#2bf01416)。
|
||
* Failed → 返回错误（结束）
|
||
4. 返回结果并打印结果
|
||
|
||
<Attachment link="https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/2782fff499e24d2cbb7836229b428ab4~tplv-goo7wpa0wc-image.image" name="Upload_Asset_Get_Info.go" ></Attachment>
|
||
查询结果示意如下：
|
||
```JSON
|
||
asset status: Active
|
||
asset is active, URL = https://ark-media-asset-stg.tos-cn-beijing.volces.com/2100000825/031807095608757847.jpg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=****&X-Tos-Expires=43200&X-Tos-Security-Token=****&X-Tos-Signature=****&X-Tos-SignedHeaders=host
|
||
```
|
||
|
||
<span id="ca82b8d7"></span>
|
||
## 其他编程语言示例
|
||
查看更多语言的示例代码请下载：
|
||
<Attachment link="https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/bcc7d8a175744793a79b09027f0cf1ee~tplv-goo7wpa0wc-image.image" name="demo.zip" ></Attachment>
|
||
:::tip
|
||
注意替换 Demo 中的 AK与SK，若需调用其他接口如 ListAssets，需替换 ACTION 与对应请求参数。
|
||
:::
|
||
<span id="c78f9931"></span>
|
||
## 使用人像素材生成视频
|
||
在获取素材 Asset ID后，可使用私域人像素材生成视频。效果预览及使用方式请参考下文。
|
||
<span id="225e69c7"></span>
|
||
### 视频生成
|
||
在 Video Generation API 的 **content.<模态>_url.url** 字段中使用 素材 URI 生成视频。
|
||
:::tip
|
||
资产 URI 拼接方式：`asset://<asset_ID`**`>`**
|
||
:::
|
||
具体方式请参考 [Seedance 2.0 教程](https://www.volcengine.com/docs/82379/2291680?lang=zh) 和 [Seedance 2.0 API 参考](https://www.volcengine.com/docs/82379/1520757?lang=zh)。
|
||
:::tip
|
||
|
||
在传入给模型的 Prompt 中，需要使用**图片 1**、**视频 1** 的方式指代参考素材，素材序号为素材在请求体中的顺序。请勿直接在 Prompt 中直接使用 Asset ID。
|
||
例：“**图片1** 里的女孩身着**图片2**中的服装，正在整理柜台上的物品。**图片3**中的男孩是一位顾客，他走上前，想要向女孩索要联系方式。”
|
||
调用示例请参考[3. 提示词（content.text）中应该如何准确指代参考素材？](/docs/82379/2333565#15e21eb8)
|
||
:::
|
||
示例代码：
|
||
```Python
|
||
import os
|
||
import time
|
||
# Install SDK: pip install 'volcengine-python-sdk[ark]'
|
||
from volcenginesdkarkruntime import Ark
|
||
client = Ark(
|
||
# The base URL for model invocation
|
||
base_url='https://ark.cn-beijing.volces.com/api/v3',
|
||
# Get API Key：https://console.volcengine.com/ark/region:ark+cn-beijing/apikey
|
||
api_key=os.environ.get("ARK_API_KEY"),
|
||
)
|
||
if __name__ == "__main__":
|
||
print("----- create request -----")
|
||
create_result = client.content_generation.tasks.create(
|
||
model="doubao-seedance-2-0-260128", # Replace with Model ID
|
||
content=[
|
||
{
|
||
"type": "text",
|
||
"text": "图片1中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持图片2的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。"
|
||
},
|
||
{
|
||
"type": "image_url",
|
||
"image_url": {
|
||
"url": "asset://asset-20260224200602-qn7wr" # Asset ID
|
||
},
|
||
"role": "reference_image"
|
||
},
|
||
{
|
||
"type": "image_url",
|
||
"image_url": {
|
||
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_edit_pic1.jpg"
|
||
},
|
||
"role": "reference_image"
|
||
},
|
||
],
|
||
generate_audio=True,
|
||
ratio="16:9",
|
||
duration=11,
|
||
watermark=True,
|
||
)
|
||
print(create_result)
|
||
print("----- polling task status -----")
|
||
task_id = create_result.id
|
||
while True:
|
||
get_result = client.content_generation.tasks.get(task_id=task_id)
|
||
status = get_result.status
|
||
if status == "succeeded":
|
||
print("----- task succeeded -----")
|
||
print(get_result)
|
||
break
|
||
elif status == "failed":
|
||
print("----- task failed -----")
|
||
print(f"Error: {get_result.error}")
|
||
break
|
||
else:
|
||
print(f"Current status: {status}, Retrying after 30 seconds...")
|
||
time.sleep(30)
|
||
```
|
||
|
||
<span id="9f864be5"></span>
|
||
# 常见问题
|
||
<span id="cbc4063e"></span>
|
||
#### 1. 为什么素材上传成功后，无法使用素材生成视频或获取素材信息？
|
||
素材库按[项目](https://www.volcengine.com/docs/82379/1359411?lang=zh#03ec4a65)**（Project）隔离**。
|
||
|
||
* 在视频生成时，必须使用**素材所在项目**中的推理接入点进行推理。
|
||
* 如果素材上传成功，但使用获取素材接口获取素材失败，可能是因为调用上传素材(CreateAsset)和获取素材接口时传入了不同的 **ProjectName**。
|
||
* **ProjectName** 默认值为 `default`，即如果不指定该字段，则默认将资源创建至 `default` 项目中。
|
||
* 建议在同一个项目中管理素材。
|
||
|
||
<span id="617ff561"></span>
|
||
#### 2. 怎样管理用户对素材库的权限？
|
||
您可使用[访问控制](https://console.volcengine.com/iam/identitymanage/user) （IAM）精细化管理用户操作素材库的权限。可按以下方式设置：
|
||
|
||
1. **创建自定义策略**
|
||
1. 打开[访问控制](https://console.volcengine.com/iam/policymanage) > **新建自定义策略**
|
||
2. 输入策略名称。
|
||
3. 切换到 **JSON编辑器**，将下方自定义策略粘贴至编辑器中，点击 **提交** 保存。
|
||
|
||
<div style="text-align: center"><img src="https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/937e2b58f8294223a06f3860fc461f15~tplv-goo7wpa0wc-image.image" width="1125px" /></div>
|
||
|
||
```Python
|
||
|
||
{
|
||
"Statement": [
|
||
{
|
||
"Effect": "Allow",
|
||
"Action": [
|
||
"ark:*Asset*"
|
||
],
|
||
"Resource": [
|
||
"*"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
|
||
|
||
2. **为用户/用户组赋权**
|
||
1. 点击 **用户管理** > **用户**/**用户组**，选择需要赋权的用户或用户组，点击右侧的 **添加权限。**
|
||
2. 在 **授权策略** 中选择**步骤 1** 中创建的策略。
|
||
3. （可选）在 **限制到项目资源** 中选择策略应用的项目。
|
||
4. 点击 **提交。**
|
||
|
||
完成上述操作后，该用户/用户组即可在对应项目中管理素材。
|
||
关于 IAM 的更多信息，请参考[访问控制](http://volcengine.com/docs/6257?lang=zh)。
|
||
<span id="15e21eb8"></span>
|
||
#### 3. 提示词（content.**text**）中应该如何准确指代参考素材？
|
||
需在提示词输入中使用”**素材类型+序号**”格式引用素材，例如 **图片 1**、**视频 1**、**音频 1**。序号为请求体中该素材在同类素材中的排序。
|
||
**注意**：请勿在提示词中使用 Asset ID 指代素材。
|
||
例如，下方示例中包含 5 张参考图和 1 个参考音频，可参考示例提示词的写法引用素材。
|
||
|
||
* **参考：**
|
||
|
||
|
||
|
||
<div style="display: flex;">
|
||
<div style="flex-shrink: 0;width: calc((100% - 64px) * 0.2000);">
|
||
|
||
|
||
图片 1
|
||
|
||
|
||
</div>
|
||
<div style="flex-shrink: 0;width: calc((100% - 64px) * 0.2000);margin-left: 16px;">
|
||
|
||
|
||
|
||
图片 2
|
||
|
||
|
||
</div>
|
||
<div style="flex-shrink: 0;width: calc((100% - 64px) * 0.2000);margin-left: 16px;">
|
||
|
||
|
||
图片 3
|
||
|
||
|
||
</div>
|
||
<div style="flex-shrink: 0;width: calc((100% - 64px) * 0.2000);margin-left: 16px;">
|
||
|
||
|
||
|
||
图片 4
|
||
|
||
|
||
</div>
|
||
<div style="flex-shrink: 0;width: calc((100% - 64px) * 0.2000);margin-left: 16px;">
|
||
|
||
|
||
|
||
图片 5
|
||
|
||
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
* **提示词**
|
||
|
||
```Plain Text
|
||
清新奶油画风短剧，轻快吉他卡点快切，奶油白主色 + 蜜桃粉高光，画面柔和无特效，靠表情传情。0-2 秒：快切 2 镜图片 1中的霸总不小心撞到穿着图片 2的衣服的图片 3中的女主（两人错愕对视）+ 霸总扯下自己的西装外套披在女主身上（手部特写）」，背景吉他声起，咖啡杯掉落 / 衣服摩擦的轻柔音效；2-6 秒：快切 3 镜「女主穿霸总外套低头偷笑（脸颊泛红特写）+ 霸总看着女主背影嘴角微扬，说“我们一起走吧”参考音频 1（侧颜） + 两人在雨夜共撑一把黑伞，指尖相触快速收回（近景）」，雨天背景为图片 4，每镜卡点轻鼓重拍，配雨滴落地 / 伞骨撑开的音效，画面带轻微柔雾质感；6-8 秒：慢放两人对视笑眼，画面右下角出现图片 5的文字部分，左下角小字「NEW EP DAILY」，背景飘淡粉色花瓣（极简），BGM 落温柔尾音，画面定格两人同框侧脸。
|
||
```
|
||
|
||
|
||
* **示例代码**
|
||
|
||
```Bash
|
||
curl --location 'https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks' \
|
||
-X POST \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer $ARK_API_KEY"\
|
||
-d '{
|
||
"model": "doubao-seedance-2-0-260128",
|
||
"content": [
|
||
{
|
||
"type": "text",
|
||
"text": "清新奶油画风短剧，轻快吉他卡点快切，奶油白主色 + 蜜桃粉高光，画面柔和无特效，靠表情传情。0-2 秒：快切 2 镜图片 1中的霸总不小心撞到穿着图片 2的衣服的图片 3中的女主（两人错愕对视）+ 霸总扯下自己的西装外套披在女主身上（手部特写）」，背景吉他声起，咖啡杯掉落 / 衣服摩擦的轻柔音效；2-6 秒：快切 3 镜「女主穿霸总外套低头偷笑（脸颊泛红特写）+ 霸总看着女主背影嘴角微扬，说“我们一起走吧”参考音频 1（侧颜） + 两人在雨夜共撑一把黑伞，指尖相触快速收回（近景）」，雨天背景为图片 4，每镜卡点轻鼓重拍，配雨滴落地 / 伞骨撑开的音效，画面带轻微柔雾质感；6-8 秒：慢放两人对视笑眼，画面右下角出现图片 5的文字部分，左下角小字「NEW EP DAILY」，背景飘淡粉色花瓣（极简），BGM 落温柔尾音，画面定格两人同框侧脸。"
|
||
},
|
||
{
|
||
"type": "image_url",
|
||
"role": "reference_image",
|
||
"image_url": {
|
||
"url": "asset://asset-20260224185115-hnjhb"
|
||
}
|
||
},
|
||
{
|
||
"type": "image_url",
|
||
"role": "reference_image",
|
||
"image_url": {
|
||
"url": "asset://asset-20260224185115-8gghm"
|
||
}
|
||
},
|
||
{
|
||
"type": "image_url",
|
||
"role": "reference_image",
|
||
"image_url": {
|
||
"url": "asset://asset-20260224185115-cjkwr"
|
||
}
|
||
},
|
||
{
|
||
"type": "image_url",
|
||
"role": "reference_image",
|
||
"image_url": {
|
||
"url": "asset://asset-20260224185115-pxbk9"
|
||
}
|
||
},
|
||
{
|
||
"type": "image_url",
|
||
"role": "reference_image",
|
||
"image_url": {
|
||
"url": "asset://asset-20260224185115-2c698"
|
||
}
|
||
},
|
||
{
|
||
"type": "audio_url",
|
||
"role": "reference_audio",
|
||
"audio_url": {
|
||
"url": "asset://asset-20260224185115-dp9qm"
|
||
}
|
||
}
|
||
],
|
||
"generate_audio": true,
|
||
"ratio": "16:9",
|
||
"duration": 11,
|
||
"watermark": false
|
||
}'
|
||
```
|
||
|