文档中心

火山方舟

私域虚拟人像库

私域虚拟人像素材资产库使用指南

警告

上传素材（CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。

素材资产应为虚拟人像，非虚拟人像类素材无需入库。

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

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

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

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

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

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

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

使用前准备

要使用私域素材库的全部功能，您需开通高级创作权益包。私域虚拟素材库与真人人像素材库共享容量。具体信息请参考 Seedance 高级创作权益包购买说明。

素材资产库结构说明

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

可以使用素材组自由管理素材，例如可将同一虚拟人物素材放入同一素材组合进行管理。

Asset（素材资产）：一个素材文件（当前支持上传图像、视频、音频），是方舟 Seedance 2.0 系列模型可直接用于推理的可信资产。

说明

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

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

每个上传的素材资产需经过预处理，可轮询调用 GetAsset 接口查询素材状态（对应参数为 Status），仅当状态变为 Active 后，该素材资产方可用于后续推理使用；若状态为 Failed 则表示处理失败，无法用于后续推理使用。详情可参考示例：上传素材并使用 GetAsset 获取素材信息。

以图像资产上传为例：

单张图片文件格式要求：

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

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

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

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

为保证上传的图片素材资产在后续生成视频时，人物面部、服装细节等与上传的素材资产一致，推荐按照如下规则及示例将同一人物的多个素材传入同一资产组合：

人像资产内容最佳实践：

说明

全身参考图要求

版式：竖版

图片内容：人物全身正面图片

说明

人脸特写图要求

版式：竖版

图片内容：人物正面无表情特写，肩部以上，人物面部占画面2/3左右

素材资产（Assets）API 接口功能

权限要求

注意

调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考获取 API 访问密钥（AK/SK）。

用户需具备相应的 IAM 权限，具体权限信息请参考怎样管理用户对素材库的权限？

接口列表

Asset (Group) 创建接口

CreateAssetGroup：创建素材资产组合。

CreateAsset：创建素材资产。该接口可用于上传个人素材资产，创建素材资产后可利用返回字段中的素材 Id （需处于 Active 状态）用于 Seedance 2.0 和 Seedance 2.5 模型生成视频。

Asset (Group) 管理接口

ListAssetGroups：查询素材资产组合列表。

ListAssets：查询素材资产列表。

GetAsset：查询素材资产信息。

GetAssetGroup：查询素材资产组合信息。

UpdateAssetGroup：更新素材资产组合信息。

UpdateAsset：更新素材资产信息。

DeleteAsset：删除单个素材资产。

DeleteAssetGroup: 删除指定素材组。

限流要求

说明

QPS：API 接口每秒允许的请求总数上限，超出则请求报错。

QPM：API 接口每分钟允许的请求总数上限，超出则请求报错。

接口名	账号维度的限流
CreateAssetGroup	10 QPS
CreateAsset	不同权益用户限流不同，具体请参见 Seedance 高级创作权益包购买说明。
ListAssetGroups	10 QPS
ListAssets	10 QPS
GetAsset	100 QPS
GetAssetGroup	10 QPS
UpdateAsset	10 QPS
UpdateAssetGroup	10 QPS
DeleteAsset	10 QPS
DeleteAssetGroup	5 QPS

使用教程

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

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

警告

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

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

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

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

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

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

使用控制台

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

打开方舟控制台 > 我的 > 虚拟人像。

创建素材组合。

向素材组合中上传素材。

使用 API

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

创建素材组合

说明

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

API 参数信息请参考私域虚拟人像库 API 参考文档。

素材库项目（Project）隔离说明

在指定的 Asset Group 内创建或查询 Asset 时，需保证两者的 ProjectName 一致。

Asset（素材资产）所属的 ProjectName 需与调用视频生成 API 接口时使用的 API key 所属的 ProjectName 一致。

使用 POSTCreateAssetGroup 接口创建素材组合。

在请求中传入：

Name：素材组合的名称。

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

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

说明

当前仅支持 AIGC 类型。

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

说明

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

请求示例：

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

返回示例：

上传素材

警告

上传素材（CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。

视频素材处理将耗费更长时间。

使用 POST CreateAsset接口上传素材。

在请求中提供：

GroupId：必填，素材组合 ID

URL: 必填，图片/视频/音频可访问的 URL

AssetType: 必填，支持上传图片/视频/音频类型素材，需指定为 Image/Video/Audio。素材文件的具体限制详见 Assets API 参考文档。

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

说明

不同模型支持的输入音视频时长不同。建议在上传前记录上传音视频的时长，方便终端客户区分哪些素材可以在 Seedance 2.0 系列模型中使用。

说明

该字段仅用于使用 ListAssets 接口时模糊搜索素材，不会被带入模型推理。关于如何使用素材生成视频，请参考使用预置虚拟人像和提示词（content.text）中应该如何准确指代参考素材？。

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

说明

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

注意：

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

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

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))
}

返回示例：

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

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

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

API：

POST GetAsset获取单个素材

POST ListAssets 查询素材

POST ListAssetGroups 查询素材组合信息

获取单个素材信息

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

说明

要获取完整的 API 参数、限流等信息，请查看私域虚拟人像库 API 参考文档。

返回示例：

说明

LastInferenceTime 表示素材最近一次被用于提交视频生成任务的时间，以用户提交任务的时间为准。详细信息请参考 GetAsset API 参考文档。

查询素材资产

可使用 POST ListAssets 查询 Assets。

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

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

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

说明

ListAssets 支持 NextToken 分页和页码分页。分页方式、参数用法及使用限制，请参见 ListAssets API 参考文档。

返回示例：

查询素材组

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

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

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

说明

ListAssetGroups 支持 NextToken 分页和页码分页。分页方式、参数用法及使用限制，请参见 ListAssetGroups API 参考文档。

返回示例：

更新/删除素材和素材组

您可调用 UpdateAsset、UpdateAssetGroup、DeleteAsset 和 DeleteAssetGroup 更新或删除素材及素材组。具体信息请参考：私域虚拟人像库 API 参考文档。

建议定期通过 GetAsset 或 ListAssets 查看 LastInferenceTime，并通过 DeleteAsset 主动删除确认不再使用的素材。若整个素材组均不再需要，可调用 DeleteAssetGroup。未返回 LastInferenceTime 仅表示素材在 2026 年 7 月 24 日后没有调用记录，不能据此判断素材从未使用。删除前请结合自身业务记录确认，删除操作不可恢复。

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

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

代码执行以下逻辑：

createAsset：上传资源，获取 AssetId

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

根据 Status 判断

Processing → 继续轮询

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

Failed → 返回错误（结束）

返回结果并打印结果

Upload_Asset_Get_Info.go

查询结果示意如下：

其他编程语言示例

查看更多语言的示例代码请下载：

demo.zip

说明

注意替换 Demo 中的 AK与SK，若需调用其他接口如 ListAssets，需替换 ACTION 与对应请求参数。

使用人像素材生成视频

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

视频生成

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

说明

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

具体方式请参考 Seedance 2.0 教程和 Seedance 2.0 API 参考。

说明

在传入给模型的 Prompt 中，需要使用图片 1、视频 1 的方式指代参考素材，素材序号为素材在请求体中的顺序。请勿直接在 Prompt 中直接使用 Asset ID。

例：“图片1 里的女孩身着图片2中的服装，正在整理柜台上的物品。图片3中的男孩是一位顾客，他走上前，想要向女孩索要联系方式。”

调用示例请参考提示词（content.text）中应该如何准确指代参考素材？

示例代码：

常见问题

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

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

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

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

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

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

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

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

创建自定义策略

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

输入策略名称。

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

为用户/用户组赋权

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

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

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

点击提交。

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

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

提示词（content.text）中应该如何准确指代参考素材？

需在提示词输入中使用”素材类型+序号”格式引用素材，例如图片 1、视频 1、音频 1。序号为请求体中该素材在同类素材中的排序。

注意：请勿在提示词中使用 Asset ID 指代素材。

例如，下方示例中包含 5 张参考图和 1 个参考音频，可参考示例提示词的写法引用素材。

参考：

图片1	图片2	图片3	图片4	图片5

提示词

清新奶油画风短剧，轻快吉他卡点快切，奶油白主色 + 蜜桃粉高光，画面柔和无特效，靠表情传情。0-2 秒：快切 2 镜图片 1中的霸总不小心撞到穿着图片 2的衣服的图片 3中的女主（两人错愕对视）+ 霸总扯下自己的西装外套披在女主身上（手部特写）」，背景吉他声起，咖啡杯掉落 / 衣服摩擦的轻柔音效；2-6 秒：快切 3 镜「女主穿霸总外套低头偷笑（脸颊泛红特写）+ 霸总看着女主背影嘴角微扬，说“我们一起走吧”参考音频 1（侧颜） + 两人在雨夜共撑一把黑伞，指尖相触快速收回（近景）」，雨天背景为图片 4，每镜卡点轻鼓重拍，配雨滴落地 / 伞骨撑开的音效，画面带轻微柔雾质感；6-8 秒：慢放两人对视笑眼，画面右下角出现图片 5的文字部分，左下角小字「NEW EP DAILY」，背景飘淡粉色花瓣（极简），BGM 落温柔尾音，画面定格两人同框侧脸。

示例代码

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": true
}'

最近更新时间：2026.10.13 11:11:23

这个页面对您有帮助吗？

有用

无用