# 私域虚拟人像素材资产库使用指南 > 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。 > **警告** > > * 上传素材 （CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。 > * 素材资产应为虚拟人像，非虚拟人像类素材无需入库。 > * 您需确保上传的虚拟人像符合以下条件： > > * 您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。 > > * 素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。 > > * 素材不包含违反法规、违背公序良俗、危害国家安全的内容。 Seedance 2.0 和 Seedance 2.5 系列模型具有完备的防范 Deepfake 和侵犯版权风险能力。在生成视频时，会对有风险的参考素材输入进行拦截，最大限度保证生成视频合规和安全性。 为确保创作者能充分利用 Seedance 强大的视频生成能力高效生成视频内容，同时规避 AI 生成内容的潜在风险，方舟推出了私域可信素材库。完成入库的可信素材将进入您的私域素材库，在视频生成中使用。 私域素材库使用流程如下：
![](https://arkdocs.tos-cn-beijing.volces.com/images/video-generation/volc_advanced_creative_packs.png)
# 使用前准备 要使用私域素材库的全部功能，您需开通高级创作权益包。私域虚拟素材库与真人人像素材库共享容量。具体信息请参考 [Seedance 高级创作权益包购买说明](/docs/seedance-2-0-purchase-guide)。 # 素材资产库结构说明 * **Asset Group（素材资产组合）**：单个素材文件为一个 Asset，每个 Asset 属于一个 Asset Group。 * 可以使用素材组自由管理素材，例如可将同一虚拟人物素材放入同一素材组合进行管理。 * **Asset（素材资产）**：一个素材文件（当前支持上传图像、视频、音频），是方舟 Seedance 2.0 系列模型可直接用于推理的可信资产。 > **说明** > > * 仅需入库推理需使用的素材资产，不需使用的素材资产请勿入库。 > * 仅可使用已入库素材资产的 Id (Asset ID) 进行视频生成，同一形象未入库素材无法使用。 > * 每个上传的素材资产需经过预处理，可轮询调用 **GetAsset** 接口查询素材状态（对应参数为 **Status）**，仅当状态变为 `Active` 后，该素材资产方可用于后续推理使用；若状态为 `Failed` 则表示处理失败，无法用于后续推理使用。**详情可参考**[示例：上传素材并使用 GetAsset 获取素材信息](/docs/private-virtual-avatar-library-guide-preview#5c0ee427)**。** **以图像资产上传为例**： * **单张图片文件格式要求**： * 格式：jpeg、png、webp、tiff、gif、heic/heif * 宽高比（宽/高）： (0.4, 2.5) * 宽高长度（px）：(300, 6000) * 大小：单张图片小于 30 MB。 * 为保证上传的图片素材资产在后续生成视频时，**人物面部、服装细节等与上传的素材资产一致，** 推荐按照如下规则及示例将同一人物的多个素材传入同一资产组合： * **人像资产内容最佳实践**： > **说明** > > **全身参考图要求** > * 版式：竖版 > * 图片内容：人物全身正面图片
![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/86fef6988c8449c2a3d9062b2fa50e96~tplv-goo7wpa0wc-image.image)
> **说明** > > **人脸特写图要求** > * 版式：竖版 > * 图片内容：人物正面无表情特写，肩部以上，人物面部占画面2/3左右
![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/6188f2b280eb43a3821644071a2c5485~tplv-goo7wpa0wc-image.image)
# 素材资产（Assets）API 接口功能 ## 权限要求 > **注意** > > 调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考 [获取 API 访问密钥（AK/SK）](https://docs.volcengine.com/docs/6257/64983?lang=zh)。 > 用户需具备相应的 IAM 权限，具体权限信息请参考[怎样管理用户对素材库的权限？](/docs/private-virtual-avatar-library-guide-preview#617ff561) ## 接口列表 ### **Asset (Group) 创建接口** 1. [CreateAssetGroup](/docs/create-asset-group-api)：创建素材资产组合。 2. [CreateAsset](/docs/create-asset-api)：创建素材资产。该接口可用于上传个人素材资产，创建素材资产后可利用返回字段中的素材 Id （需处于 `Active` 状态）用于 Seedance 2.0 和 Seedance 2.5 模型生成视频。 ### **Asset (Group) 管理接口** * [ListAssetGroups](/docs/list-asset-groups-api)：查询素材资产组合列表。 * [ListAssets](/docs/list-assets-api)：查询素材资产列表。 * [GetAsset](/docs/get-asset-api)：查询素材资产信息。 * [GetAssetGroup](/docs/get-asset-group-api)：查询素材资产组合信息。 * [UpdateAssetGroup](/docs/update-asset-group-api)：更新素材资产组合信息。 * [UpdateAsset](/docs/update-asset-api)：更新素材资产信息。 * [DeleteAsset](/docs/delete-asset-api)：删除单个素材资产。 * [DeleteAssetGroup](/docs/delete-asset-group-api): 删除指定素材组。 ## 限流要求 > **说明** > > * **QPS**：API 接口**每秒**允许的请求总数上限，超出则请求报错。 > * **QPM**：API 接口**每分钟**允许的请求总数上限，超出则请求报错。 |接口名 |账号维度的限流 | |---|---| |CreateAssetGroup |10 QPS | |CreateAsset |不同权益用户限流不同，具体请参见 [Seedance 高级创作权益包购买说明](/docs/seedance-2-0-purchase-guide)。 | |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 或在体验中心上传虚拟素材。 ### 使用控制台 > 素材格式的具体要求，请参考[素材资产库结构说明](/docs/private-virtual-avatar-library-guide-preview#2b7bf522)。 1. 打开 [方舟控制台](https://ark.volcengine.com/region:cn-beijing/experience/gen_video?model=doubao-seedance-2-0-260128) > **我的** > **虚拟人像**。 ![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/b1152a6834bc4a7e8f5137474bf34391~tplv-goo7wpa0wc-image.image) 2. 创建素材组合。 3. 向素材组合中上传素材。 ### 使用 API 先调用 `CreateAssetGroup` 接口创建素材组合，再调用 `CreateAsset` 接口向组合中上传素材。请求示例： 1. **创建素材组合** > **说明** > > * 调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考 [API访问密钥管理](https://docs.volcengine.com/docs/6257/64983?lang=zh)。 > * API 参数信息请参考[私域虚拟人像素材资产库使用指南](/docs/private-virtual-avatar-library-guide-preview)。 > * **素材库**[**项目**](/docs/modelark-faq#03ec4a65)**（Project）隔离说明** > > 在指定的 Asset Group 内创建或查询 Asset 时，需保证两者的 **ProjectName** 一致。 > > Asset（素材资产）所属的 **ProjectName** 需与调用视频生成 API 接口时使用的 API key 所属的 **ProjectName** 一致。 使用 **POST` `**`CreateAssetGroup` 接口创建素材组合。 在请求中传入： * **Name**：素材组合的名称。 * **Description**: 素材组合的文字描述。 * **GroupType**: 选填，默认为 AIGC（虚拟人像素材）。 > **说明** > > 当前仅支持 AIGC 类型。 * **ProjectName**：选填，指定资源项目名称，默认为 default。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考 [文档](/docs/modelark-faq#03ec4a65)。 > **说明** > > 如果请求中不指定 **ProjectName**，默认将创建素材组至 **default** 项目中。 请求示例： **注意**：需使用 AK/SK 鉴权，详情参考 [API访问密钥管理](https://docs.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("", "", "")).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": "", }, ) 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-*****" } ``` 2. **上传素材** > **警告** > > 上传素材 （CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。 > 视频素材处理将耗费更长时间。 使用 **POST** `CreateAsset`接口上传素材。 在请求中提供： * **GroupId**：必填，素材组合 ID * **URL**: 必填，图片/视频/音频可访问的 URL * **AssetType**: 必填，支持上传图片/视频/音频类型素材，需指定为 **Image/Video/Audio**。素材文件的具体限制详见 [**Assets API 参考文档**](/docs/create-asset-api)**。** * **Name**: 选填，素材名称，可用于管理素材，如素材文件名。 > **说明** > > 不同模型支持的输入音视频时长不同。建议在上传前记录上传音视频的时长，方便终端客户区分哪些素材可以在 Seedance 2.0 系列模型中使用。 > **说明** > > 该字段仅用于使用 ListAssets 接口时模糊搜索素材，不会被带入模型推理。关于如何使用素材生成视频，请参考[使用预置虚拟人像](/docs/seedance-portrait-asset-guide#preset-avatar) 和[提示词（content.text）中应该如何准确指代参考素材？](/docs/private-virtual-avatar-library-guide-preview#15e21eb8)。 * **ProjectName**：选填，指定资源项目名称，默认为 **default**。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考 [文档](/docs/modelark-faq#03ec4a65)。 > **说明** > > 如果请求中不指定 **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("", "", "")).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": "", "AssetType": "Image", "ProjectName": "" }, ) 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 & 控制台） 您可使用以下方式检索虚拟人像资产。 * **控制台**：您可在 [方舟控制台](https://ark.volcengine.com/region:cn-beijing/experience/gen_video?model=doubao-seedance-2-0-260128) > **我的** > **虚拟人像** 中搜索和查看已上传的虚拟人像资产。 * **API**： * **POST** `GetAsset `获取单个素材 * **POST** `ListAssets` 查询素材 * **POST** `ListAssetGroups` 查询素材组合信息 ### 获取单个素材信息 可使用 **POST** GetAsset 获取单个素材信息，指定素材资产 ID。 > **说明** > > 要获取完整的 API 参数、限流等信息，请查看[私域虚拟人像素材资产库使用指南](/docs/private-virtual-avatar-library-guide-preview)。 ```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("", "", "")).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": "", // 需确保填入素材所在项目的名称 }, ) 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" } ``` > **说明** > > `LastInferenceTime` 表示素材最近一次被用于提交视频生成任务的时间，以用户提交任务的时间为准。详细信息请参考 [GetAsset API 参考文档](/docs/get-asset-api)。 ### 查询素材资产 可使用 **POST** ListAssets 查询 Assets。 * 支持根据组合 ID (GroupId)、素材状态（Statuses）和素材名称（Name）查询。筛选出符合所有条件的素材。 * 支持使用 Name 进行模糊搜索，同时使用 GroupId 精确搜索，便于检索所需的素材。 支持使用 SortBy，SortOrder 对结果进行排序。 > **说明** > > ListAssets 支持 NextToken 分页和页码分页。分页方式、参数用法及使用限制，请参见 [ListAssets API 参考文档](/docs/list-assets-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("", "", "")).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 字段进行模糊搜索。 > **说明** > > ListAssetGroups 支持 NextToken 分页和页码分页。分页方式、参数用法及使用限制，请参见 [ListAssetGroups API 参考文档](/docs/list-asset-groups-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("", "", "")).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` 更新或删除素材及素材组。具体信息请参考：[私域虚拟人像素材资产库使用指南](/docs/private-virtual-avatar-library-guide-preview)。 建议定期通过 `GetAsset` 或 `ListAssets` 查看 `LastInferenceTime`，并通过 `DeleteAsset` 主动删除确认不再使用的素材。若整个素材组均不再需要，可调用 `DeleteAssetGroup`。未返回 `LastInferenceTime` 仅表示素材在 2026 年 7 月 24 日后没有调用记录，不能据此判断素材从未使用。删除前请结合自身业务记录确认，删除操作不可恢复。 ## 示例：上传素材并使用 GetAsset 获取素材信息 以下示例创建素材资产后，查询资产 Status 并根据状态，判断是否继续查询或返回对应结果。 代码执行以下逻辑： 1. createAsset： 上传资源，获取 AssetId 2. waitForAssetActive：开始查询，循环调用 getAssetStatus 查询当前资产状态 3. 根据 Status 判断 * Processing → 继续轮询 * Active → 返回 URL（结束）状态为 `Active` 后，可使用该素材 Asset ID (URI格式) 进行视频生成，如何使用人像素材生成视频，详见[使用预置虚拟人像](/docs/seedance-portrait-asset-guide#preset-avatar)。 * Failed → 返回错误（结束） 4. 返回结果并打印结果 [Upload_Asset_Get_Info.go](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/2782fff499e24d2cbb7836229b428ab4~tplv-goo7wpa0wc-image.image) 查询结果示意如下： ```text 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 ``` ## 其他编程语言示例 查看更多语言的示例代码请下载： [demo.zip](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/bcc7d8a175744793a79b09027f0cf1ee~tplv-goo7wpa0wc-image.image) > **说明** > > 注意替换 Demo 中的 AK与SK，若需调用其他接口如 ListAssets，需替换 ACTION 与对应请求参数。 ## 使用人像素材生成视频 在获取素材 Asset ID后，可使用私域人像素材生成视频。效果预览及使用方式请参考下文。 ### 视频生成 在 Video Generation API 的 **content.<模态>_url.url** 字段中使用 素材 URI 生成视频。 > **说明** > > 资产 URI 拼接方式：`asset://` 具体方式请参考 [Seedance 2.0 教程](/docs/seedance-2-0) 和 [Seedance 2.0 API 参考](/docs/create-video-generation-task-api)。 > **说明** > > 在传入给模型的 Prompt 中，需要使用**图片 1**、**视频 1** 的方式指代参考素材，素材序号为素材在请求体中的顺序。请勿直接在 Prompt 中直接使用 Asset ID。 > 例：“**图片1** 里的女孩身着**图片2**中的服装，正在整理柜台上的物品。**图片3**中的男孩是一位顾客，他走上前，想要向女孩索要联系方式。” > 调用示例请参考[提示词（content.text）中应该如何准确指代参考素材？](/docs/private-virtual-avatar-library-guide-preview#15e21eb8) 示例代码： ```Python 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) ``` # 常见问题 ## 为什么素材上传成功后，无法使用素材生成视频或获取素材信息？ 素材库按 [**项目**](/docs/modelark-faq#03ec4a65)**（Project）隔离**。 * 在视频生成时，必须使用**素材所在项目**中的推理接入点进行推理。 * 如果素材上传成功，但使用获取素材接口获取素材失败，可能是因为调用上传素材(CreateAsset)和获取素材接口时传入了不同的 **ProjectName**。 * **ProjectName** 默认值为 `default`，即如果不指定该字段，则默认将资源创建至 `default` 项目中。 * 建议在同一个项目中管理素材。 ## 怎样管理用户对素材库的权限？ 您可使用 [访问控制](https://console.volcengine.com/iam/identitymanage/user) （IAM）精细化管理用户操作素材库的权限。可按以下方式设置： 1. **创建自定义策略** 1. 打开 [访问控制](https://console.volcengine.com/iam/policymanage) > **新建自定义策略** 2. 输入策略名称。 3. 切换到 **JSON编辑器**，将下方自定义策略粘贴至编辑器中，点击 **提交** 保存。
![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/937e2b58f8294223a06f3860fc461f15~tplv-goo7wpa0wc-image.image)
```JSON { "Statement": [ { "Effect": "Allow", "Action": [ "ark:*Asset*" ], "Resource": [ "*" ] } ] } ``` 2. **为用户/用户组赋权** 1. 点击 **用户管理** > **用户**/**用户组**，选择需要赋权的用户或用户组，点击右侧的 **添加权限**。 2. 在 **授权策略** 中选择**步骤 1** 中创建的策略。 3. （可选）在 **限制到项目资源** 中选择策略应用的项目。 4. 点击 **提交**。 完成上述操作后，该用户/用户组即可在对应项目中管理素材。 关于 IAM 的更多信息，请参考 [访问控制](https://www.volcengine.com/docs/6257?lang=zh)。 ## 提示词（content.**text**）中应该如何准确指代参考素材？ 需在提示词输入中使用”**素材类型+序号**”格式引用素材，例如 **图片 1**、**视频 1**、**音频 1**。序号为请求体中该素材在同类素材中的排序。 **注意**：请勿在提示词中使用 Asset ID 指代素材。 例如，下方示例中包含 5 张参考图和 1 个参考音频，可参考示例提示词的写法引用素材。 * **参考**： |图片1 |图片2 |图片3 |图片4 |图片5 | |---|---|---|---|---| |![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/bc3f0a1951c94cd282c690d2f8a938e0~tplv-goo7wpa0wc-image.image) |![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/c9b934d1e50246cdb840318f59e4f00a~tplv-goo7wpa0wc-image.image) |![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/e987f41012a24a6fa8e746126916a933~tplv-goo7wpa0wc-image.image) |![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/f74e55364f664c67885761a1a02648ae~tplv-goo7wpa0wc-image.image) |![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/1ed8333cf28649e9a6efdef54529e436~tplv-goo7wpa0wc-image.image) | * **提示词** ```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": true }' ```