Seedance 2.0 和 Seedance 2.5 系列模型具有完备的防范 Deepfake 和侵犯版权风险能力。在生成视频时,会对有风险的参考素材输入进行拦截,最大限度保证生成视频合规和安全性。
为确保创作者能充分利用 Seedance 强大的视频生成能力高效生成视频内容,同时规避 AI 生成内容的潜在风险,方舟推出了私域可信素材库。完成入库的可信素材将进入您的私域素材库,在视频生成中使用。
私域素材库使用流程如下:

使用前准备#
要使用私域素材库的全部功能,您需开通高级创作权益包。私域虚拟素材库与真人人像素材库共享容量。具体信息请参考 Seedance 高级创作权益包购买说明。
素材资产库结构说明#
-
Asset Group(素材资产组合):单个素材文件为一个 Asset,每个 Asset 属于一个 Asset Group。
- 可以使用素材组自由管理素材,例如可将同一虚拟人物素材放入同一素材组合进行管理。
-
Asset(素材资产):一个素材文件(当前支持上传图像、视频、音频),是方舟 Seedance 2.0 系列模型可直接用于推理的可信资产。
以图像资产上传为例:
-
单张图片文件格式要求:
-
格式:jpeg、png、webp、tiff、gif、heic/heif
-
宽高比(宽/高): (0.4, 2.5)
-
宽高长度(px):(300, 6000)
-
大小:单张图片小于 30 MB。
-
-
为保证上传的图片素材资产在后续生成视频时,人物面部、服装细节等与上传的素材资产一致, 推荐按照如下规则及示例将同一人物的多个素材传入同一资产组合:
- 人像资产内容最佳实践:
素材资产(Assets)API 接口功能#
权限要求#
接口列表#
Asset (Group) 创建接口#
- CreateAssetGroup:创建素材资产组合。
- CreateAsset:创建素材资产。该接口可用于上传个人素材资产,创建素材资产后可利用返回字段中的素材 Id (需处于
Active状态)用于 Seedance 2.0 和 Seedance 2.5 模型生成视频。
Asset (Group) 管理接口#
- ListAssetGroups:查询素材资产组合列表。
- ListAssets:查询素材资产列表。
- GetAsset:查询素材资产信息。
- GetAssetGroup:查询素材资产组合信息。
- UpdateAssetGroup:更新素材资产组合信息。
- UpdateAsset:更新素材资产信息。
- DeleteAsset:删除单个素材资产。
- DeleteAssetGroup: 删除指定素材组。
限流要求#
| 接口名 | 账号维度的限流 |
|---|---|
| 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 接口向组合中上传素材。请求示例:
- 创建素材组合
使用 POST CreateAssetGroup 接口创建素材组合。
在请求中传入:
- Name:素材组合的名称。
- Description: 素材组合的文字描述。
- GroupType: 选填,默认为 AIGC(虚拟人像素材)。
- ProjectName:选填,指定资源项目名称,默认为 default。一个项目中的资源仅可被该项目下的推理接入点使用,获取项目名称请参考 文档。
请求示例:
注意:需使用 AK/SK 鉴权,详情参考 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: "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))
}
返回示例:
{
"Id":"group-20260318033332-*****"
}
- 上传素材
使用 POST CreateAsset接口上传素材。
在请求中提供:
- GroupId:必填,素材组合 ID
- URL: 必填,图片/视频/音频可访问的 URL
- AssetType: 必填,支持上传图片/视频/音频类型素材,需指定为 Image/Video/Audio。素材文件的具体限制详见 Assets API 参考文档。
- Name: 选填,素材名称,可用于管理素材,如素材文件名。
- 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)) }
返回示例:
{
"Id": "asset-20260318071009-*****"
}
检索虚拟人像资产 (API & 控制台)#
您可使用以下方式检索虚拟人像资产。
-
控制台:您可在 方舟控制台 > 我的 > 虚拟人像 中搜索和查看已上传的虚拟人像资产。
-
API:
-
POST
GetAsset获取单个素材 -
POST
ListAssets查询素材 -
POST
ListAssetGroups查询素材组合信息
-
获取单个素材信息#
可使用 POST GetAsset 获取单个素材信息,指定素材资产 ID。
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-20260318035710-*****",
"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))
}
返回示例:
{
"GroupId": "group-20260318033332-*****",
"Status": "Active",
"Moderation": {
"Strategy": "Default"
},
"CreateTime": "2026-03-18T03:57:10Z",
"AssetType": "Image",
"UpdateTime": "2026-03-18T03:57:14Z",
"LastInferenceTime": "2026-07-24T10:08:49+08:00",
"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"
}
查询素材资产#
可使用 POST ListAssets 查询 Assets。
- 支持根据组合 ID (GroupId)、素材状态(Statuses)和素材名称(Name)查询。筛选出符合所有条件的素材。
- 支持使用 Name 进行模糊搜索,同时使用 GroupId 精确搜索,便于检索所需的素材。
支持使用 SortBy,SortOrder 对结果进行排序。
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(素材上传失败)
},
"MaxResults": 2,
"SortBy": "CreateTime",
"SortOrder": "Desc",
},
)
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))
}
返回示例:
{
"Items": [
{
"Id": "asset-20260318035710-kctzf",
"Name": "",
"AssetType": "Image",
"CreateTime": "2026-03-18T03:57:10Z",
"UpdateTime": "2026-03-18T03:57:14Z",
"LastInferenceTime": "2026-07-24T10:08:49+08:00",
"ProjectName": "default",
"URL": "image_url",
"GroupId": "group-20260318033332-*****",
"Status": "Active",
"Moderation": {
"Strategy": "Default"
}
},
{
"GroupId": "group-20260318033332-*****",
"Status": "Active",
"Moderation": {
"Strategy": "Default"
},
"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",
"LastInferenceTime": "2026-07-24T02:08:49Z",
"ProjectName": "default"
}
],
"NextToken": "****bmNyeXB0ZWRfY3Vyc29yIjoiLi4****"
}
查询素材组#
使用 POST ListAssetGroups 查询素材组合信息。
支持模糊搜索素材组合名称(Name)或提供多个素材组合(GroupId)。
如有多个素材组,可使用 Name 字段进行模糊搜索。
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-*****", "group-20260318033410-*****"},
"GroupType": "AIGC",
},
"MaxResults": 1,
"SortBy": "CreateTime",
"SortOrder": "Desc",
},
)
if err != nil {
fmt.Printf("error: %v\n", err)
return
}
if resp == nil {
return
}
respData, err := sonic.Marshal(resp)
fmt.Println(string(respData))
}
返回示例:
{
"Items": [
{
"UpdateTime": "2026-03-18T03:33:32Z",
"Id": "group-20260318033332-*****",
"Name": "figure_group_1",
"Description": "Figure group 1",
"GroupType": "AIGC",
"ProjectName": "default",
"CreateTime": "2026-03-18T03:33:32Z"
}
],
"NextToken": "****bmNyeXB0ZWRfY3Vyc29yIjoiLi4****"
}
更新/删除素材和素材组#
您可调用 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 → 返回错误(结束)
-
-
返回结果并打印结果
查询结果示意如下:
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
其他编程语言示例#
查看更多语言的示例代码请下载:
使用人像素材生成视频#
在获取素材 Asset ID后,可使用私域人像素材生成视频。效果预览及使用方式请参考下文。
视频生成#
在 Video Generation API 的 content.<模态>_url.url 字段中使用 素材 URI 生成视频。
具体方式请参考 Seedance 2.0 教程 和 Seedance 2.0 API 参考。
示例代码:
import os
import time
# Install SDK: python -m pip install --upgrade arkruntime
from arkruntime import Ark
client = Ark(
# The base URL for model invocation
base_url='https://ark.cn-beijing.volces.com/api/v3',
# Get API Key: https://ark.volcengine.com/region: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://arkdocs.tos-cn-beijing.volces.com/images/video-generation/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)
常见问题#
为什么素材上传成功后,无法使用素材生成视频或获取素材信息?#
素材库按 项目(Project)隔离。
-
在视频生成时,必须使用素材所在项目中的推理接入点进行推理。
-
如果素材上传成功,但使用获取素材接口获取素材失败,可能是因为调用上传素材(CreateAsset)和获取素材接口时传入了不同的 ProjectName。
-
ProjectName 默认值为
default,即如果不指定该字段,则默认将资源创建至default项目中。 -
建议在同一个项目中管理素材。
-
怎样管理用户对素材库的权限?#
您可使用 访问控制 (IAM)精细化管理用户操作素材库的权限。可按以下方式设置:
-
创建自定义策略
-
打开 访问控制 > 新建自定义策略
-
输入策略名称。
-
切换到 JSON编辑器,将下方自定义策略粘贴至编辑器中,点击 提交 保存。
-
{
"Statement": [
{
"Effect": "Allow",
"Action": [
"ark:*Asset*"
],
"Resource": [
"*"
]
}
]
}
-
为用户/用户组赋权
-
点击 用户管理 > 用户/用户组,选择需要赋权的用户或用户组,点击右侧的 添加权限。
-
在 授权策略 中选择步骤 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 }'