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

私域素材库支持录入 真人人像 素材，通过 真人认证 从根源锁定肖像权归属，规避后续肖像权纠纷风险；终端客户仅需完成一次授权，后续新增妆造可向同一素材资产组上传同人资产，无需重复真人认证流程。

使用流程概述

真人人像素材库使用流程如下：

Step 1. 创建真人人像素材组（Asset Group）
1. 调用接口生成 H5 认证页链接。支持传入 CallbackURL 自定义回调页面链接
2. （终端用户）通过您自定义的方式访问 H5 认证页链接完成真人认证，点击“完成”按钮后，将打开 CallbackURL 链接。
3. 解析 CallbackURL 拼接参数，获取真人认证结果。如通过真人认证（ resultCode 为 10000 ），调用接口查询该终端客户对应的 Asset Group 的 ID。
Step 2. 上传/管理素材（创建 Assets）
- 素材资产（Assets）入库时，系统会将上传图像与真人认证采集的基准图像进行面部特征一致性比对，比对通过后方可入库。
- 可使用Assets API 检索素材 ID、更新素材信息或删除素材。
Step 3. 使用人像素材生成视频
- 基于校验通过（Active状态）的真人人像素材，使用Asset URI发起视频生成任务。

素材资产库结构说明

Asset（素材资产） ：一个素材文件（当前支持上传图像、视频、音频），是平台 Seedance 2.0 系列模型可直接用于推理的可信资产。
Asset Group（素材资产组合） ：每个 Asset Group 对应一个真人，该真人的单个素材文件为一个 Asset。

说明

每个Asset Group唯一绑定一个真实人像。素材资产（Assets）入库时，系统会将上传图像与真人认证采集的基准图像进行面部特征一致性比对，如判定素材非同一人物，将无法成功入库。
仅需入库推理需使用的素材资产，不需使用的素材资产请勿入库。
仅可使用已入库素材资产的 Id (Asset ID) 进行视频生成，同一形象未入库素材无法使用。
每个上传的素材资产需经过预处理，可轮询调用 GetAsset 接口查询素材状态（对应参数为 Status） ，仅当状态变为 Active 后，该素材资产方可用于后续推理使用；若状态为 Failed 则表示处理失败，无法用于后续推理使用。 详情可参考 ：私域真人人像素材资产使用指南。

真人人像素材资产 API 列表

注意

调用素材资产（Assets）API 接口需使用 Access Key 鉴权，详情参考获取 API 访问密钥（AK/SK）。
上传素材（CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。

真人认证及获取 Group ID 接口

CreateVisualValidateSession: 拉起端上 H5 活体认证页。
GetVisualValidateResult: 真人认证成功后，获取本次真人认证创建的 Asset Group ID。

Asset 创建接口

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

Asset (Group) 管理接口

ListAssetGroups：查询素材资产组合列表。
ListAssets：查询素材资产列表。
GetAsset：查询素材资产信息。
GetAssetGroup：查询素材资产组合信息。
UpdateAssetGroup：更新素材资产组合信息。
UpdateAsset：更新素材资产信息。
DeleteAsset：删除单个素材资产。
DeleteAssetGroup: 删除指定素材组。

说明

Asset (Group) 管理 API 仅可查询、更新或删除用户所在账户内的素材组/素材，其他账户授权使用的素材无法通过以上素材管理 API 进行查询、更新或删除操作。

限流说明

说明

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

接口名	账号维度的限流
CreateVisualValidateSession	3 QPS
GetVisualValidateResult	3 QPS
CreateAsset	不同权益用户限流不同，具体请联系销售。
ListAssetGroups	10 QPS
ListAssets	10 QPS
GetAsset	100 QPS
GetAssetGroup	10 QPS
UpdateAsset	10 QPS
UpdateAssetGroup	10 QPS
DeleteAsset	10 QPS
DeleteAssetGroup	5 QPS

使用教程

Step 1. 创建真人人像素材组（Asset Group）

拉起端上 H5 真人认证页

使用 POST CreateVisualValidateSession 接口拉起端上 H5 真人认证页。

终端客户使用H5Link完成真人认证，点击“完成”按钮后，将打开 CallbackURL 链接，您可通过解析 CallbackURL 地址后拼接的 resultCode 参数，获取真人认证结果。

终端客户通过真人认证（ resultCode 为 10000 ）后，您可使用 API 返回的 BytedToken 查询该终端客户对应的 Asset Group ID。

该 API 接口需使用 Access Key 鉴权，详情参考 API访问密钥管理。
Access Key 对应账号需具备对应 Project 的 ArkFullAccess 权限。

在请求中传入：

CallbackURL : 必填，检测结束后将自动跳转至该 URL，并带上真人认证结果信息，包括是否成功以及用于查询 Asset Group ID 的 BytedToken。
ProjectName ：指定资源项目名称，默认为 default 。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考文档。

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:      "CreateVisualValidateSession",
            Version:     "2024-01-01",
            HttpMethod:  universal.POST,
            ContentType: universal.ApplicationJSON,
        },
        &map[string]any{
            "CallbackURL": "<CALLBACK_URL>",
            "ProjectName": "default", // Asset Group 将创建在该项目内
        },
    )
    if err != nil {
        return
    }
    if resp == nil {
        return
    }
    respData, err := sonic.Marshal(resp)
    fmt.Println(string(respData))
}

返回示例：

JSON

{
    "BytedToken": "********22041234D89A4DDA08**************",
    "H5Link": "https://ark.volcengine.com/region:cn-beijing/mobile/livenees-face-manage/authorization?pl=******************-MHtzpZgfMzdQBr3o8weNgvI9Y9u5sak851FmXyXDqtR5UbeNikIKNi_fc8M7FhnT_zYm1XH0MqCdXPOySaaD23WYChutGBWrtTyB5Jo50j5LBNKqdLXi8WrxmiaW3H8cgP4eT2lfUgTjSAvcMaqLJLFcmYLVtGDea_lE__qd466BHHunNvT4zp9Az2eIUM47hyysass0c0twQ6Ld-Bxo0gp9Sac6v1whEDoaUZvcTYns6F129NjhFBNb-Twek0OnM4klo-G1sW2Uab6dGsM0g1Y4PN85sCYsb_3HCCIqsnkIjMxuK31waX-K7Y6R7gCyT3NuqSA7b1UJdsvGXWUrdlq4mUeDcwsyfKCZ9xf-Yj7qhCUyaUAG28jZPQH34oIc-T82_oxRKo3ZRr6BMWoUc18NSIUtyK48VLdFTr5PsjEFwdeuaTzA9PUhlNwC10_jb6SRhaocbI-Oke-BsiVTmqjVmlrK9q0BkmjGwLvjKSxU4_oMjoDWyy9h1nFabZOtHR9kyw6fe7Lf5bV9LvVGN1TXwQZ-o6EZR3K9ajMYgvao_l7w2gSttKCwK6k4eScTeCBMb3JR73xwEV0BMMSVF93ifdbEZS1WvPCA0F7wc_fxk97Q1JA_qLChsUKoJJ_ShN2Y4hqKCPElY9fmOYWzl1XOdx8E9nzFvN0sPd6O8LkrWMnFjPe8R3aHRMzvF4csL3nCQHoY5bWX2oOnPoYX7OHbn2tHT_KIoKQkFdQ************************&uid=2cff9805-****-****-****-c7f69dcf311d",
    "CallbackURL": "https://www.example.com/callback"
  }

说明

可通过 H5Link 链接后缀的 Ing 字段指定页面语言。目前支持简体中文 zh 、英文 en 和繁体 zh-Hant ，默认值为 zh。

使用 H5Link 链接完成真人认证，检测结束后，将跳转至 CallbackURL。

说明

注意

终端客户使用H5Link完成真人认证，点击“完成”按钮后，将打开 CallbackURL 链接，您可解析CallbackURL 链接后拼接的相关参数获取认证结果。

拼接示例：

<CallbackURL>?bytedToken=********&resultCode=10000&algorithmBaseRespCode=0&reqMeasureInfoValue=1&verify_type=real_time

详细后缀参数：
- bytedToken：本次认证的唯一凭证标识，用来在GetVisualValidateResult 获取本次创建的 Group ID。
- resultCode：
  - 当 resultCode 为 10000 时，检测成功 。
  - 更多错误码信息请参考真人认证相关错误码文档。
- algorithmBaseRespCode：服务端子错误码。建议resultCode为服务端错误码时，再检查该字段对应的错误类型。具体请参考真人认证相关错误码文档。
- reqMeasureInfoValue：本次操作是否计费，取值为0或1。0为不计费，1为计费。当前真人认证相关服务限时免费。
- verify_type：认证类型，当前为固定值 real_time。

说明

如果检测失败，H5 链接将失效，需再次调用 CreateVisualValidateSession 生成 H5 链接。

在 POSTGetVisualValidateResult 中使用 BytedToken 查询本次真人认证创建的 Asset Group ID。
真人认证利用图像生成大模型的身份认证能力，具体信息可参考相关文档。

使用 H5 完成真人认证

终端用户：打开 H5 链接，确认人脸信息授权主体与个人信息处理授权声明，进入后续真人认证。检测完成后，点击完成按钮，将打开拼接后缀参数的 CallbackURL 链接。

您：解析CallbackURL链接拼接参数后缀中的 resultCode 字段判断检测是否成功。当 resultCode 为 10000 时，真人认证成功。

更多错误码信息，请参考真人认证相关错误码文档。

视频

获取本次真人认证创建的 Asset Group ID

真人认证成功后，使用 POST GetVisualValidateResult 获取本次真人认证创建的Asset Group ID。

在请求中传入：

BytedToken : 本次认证的唯一凭证标识，从 POST CreateVisualValidateSession 的返回体中获取。

说明

BytedToken 有效时间 30 分钟 。

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

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:      "GetVisualValidateResult",
            Version:     "2024-01-01",
            HttpMethod:  universal.POST,
            ContentType: universal.ApplicationJSON,
        },
        &map[string]any{
            "BytedToken":  "20260331145619CA67F03F8F*********",
            "ProjectName": "default", // Group 将创建于该 project
        },
    )
    if err != nil {
        return
    }
    if resp == nil {
        return
    }
    respData, err := sonic.Marshal(resp)
    fmt.Println(string(respData))
}

返回示例：

json

{
    "GroupId": "group-20260331145705-*****"
  }

Step 2. 上传/管理素材

上传素材

使用 POST CreateAsset接口上传素材。

说明

注意

每个Asset Group唯一绑定一个真实人像。素材资产（Assets）入库时，系统会将上传图像与真人认证采集的基准图像进行面部特征一致性比对，如判定素材非同一人物，将无法成功入库。
当检测到素材中包含多个人脸时无法入库。
每个上传的素材资产需经过预处理，可轮询调用 GetAsset 接口查询素材状态（对应参数为 Status） ，仅当状态变为 Active 后，该素材资产方可用于后续推理使用；若状态为 Failed 则表示处理失败，无法用于后续推理使用。
上传素材（CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。

在请求中提供：

GroupId ：必填，素材组合 ID
URL : 必填，图片/视频/音频可访问的 URL。素材文件的具体限制详见 Assets API 参考文档。
- 以图像资产上传为例，人像资产内容最佳实践 ：

说明

全身参考图要求

板式：竖版
图片内容：人物全身正面图片

说明

人脸特写图要求

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

AssetType : 必填，支持上传图片/视频/音频类型素材，需指定为 Image/Video/Audio 。
Name : 选填，素材名称，可用于管理素材，如素材文件名。

说明

该字段仅可用于在 ListAssets 接口中模糊搜索素材，不会被带入模型推理。在生成视频时，请勿使用该字段指代素材，请使用“图片 N”、“视频 N”格式进行指代。N 为素材在请求体同类素材中的排序。

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

返回示例：

JSON

{
    "Id": "asset-20260318071009-*****"
}

检索素材（API & 控制台）

您可使用以下方式检索素材。

控制台 ：您可在平台控制台 > 我的 > 真人人像 中搜索和查看已上传的人像素材。
API ：
- POST GetAsset获取单个素材
- POST ListAssets 查询素材
- POST ListAssetGroups 查询素材组合信息

获取单个素材信息

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

说明

注意：要获取完整的 API 参数、限流等信息，请查看私域真人人像库 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:      "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",
    "Moderation": {            
        "Strategy": "Default"
    },
    "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 小时
  }

查询素材

可使用 POST ListAssets 查询 Assets。

支持根据组合 ID (GroupId)、素材状态（Statuses）和素材名称（Name）查询。筛选出符合所有条件的素材。
支持使用 Name 进行模糊搜索，同时使用 GroupId 精确搜索，便于检索所需的素材。

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

说明

获取完整的 API 参考文档，请查看私域虚拟人像库 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:      "ListAssets",
            Version:     "2024-01-01",
            HttpMethod:  universal.POST,
            ContentType: universal.ApplicationJSON,
        },
        &map[string]any{
            "Filter": map[string]any{
                "GroupIds":  []string{"group-20260318033332-*****"},
                "GroupType": "LivenessFace", // LivenessFace 为真人人像 Asset Group 类型
                "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",
        "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",
        "ProjectName": "default"
      }
    ],
    "TotalCount": 2,
    "PageNumber": 1,
    "PageSize": 10
}

查询素材组

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

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

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

说明

注意：要获取完整的 API 参考文档，请查看私域真人人像库 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:      "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": "LivenessFace",
            },
            "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": "LivenessFace",
        "ProjectName": "default",
        "CreateTime": "2026-03-18T03:33:32Z"
      }
    ],
    "PageNumber": 1,
    "PageSize": 10
}

更新/删除素材或素材组

具体信息请参考：私域真人人像库 API 参考文档

Step 3. 使用人像素材生成视频

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

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

说明

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

具体方式请参考 Seedance 2.0 教程和创建视频生成任务 API参考。

说明

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

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

示例代码：

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://art-api.yuyuflow.com/api/v3',
    # Get API Key: https://art-api.yuyuflow.com/dashboard/overview
    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)

示例代码

Step 1：生成真人认证链接并使用 GetVisualValidateResult 获取素材组 ID

请求 CreateVisualValidateSession
打印 H5 链接及 BytedToken
等待 3 minutes

说明

此处建议使用 CallbackURL 后缀参数获取真人验证结果；当 resultCode 为 10000 （真人认证通过）时，可使用GetVisualValidateResult获取本次真人认证创建的 Group ID。

轮询 GetVisualValidateResult
如返回 GroupId 则打印 ID 并退出
如返回错误，则打印错误

示例代码：

Generate_H5&Get_Group_ID.go

返回示例：

Plain

Validation Link: https://h5-v2.kych5.com?accessKeyId=AKTP0VkYjZ17vwn9YtWnXGUwwwZw5****************3&secretAccessKey=9xg5esjpC1pXpvujlC15**********************&sessionToken=************************UTV2.CiQKEE1YckFYRHRqNlZDNU1XaW4SEEHcTJvTcUFJqde5xDrvcnkQ7aGuzgYYkqmuzgYg6snC6QcoBDCz5IQvOiNSb2xlRm9yVmlzdWFsRmFjZS9Sb2xlRm9yVmlzdWFsRmFjZUIHYXJrX3N0Z1IRUm9sZUZvclZpc3VhbEZhY2VYA3oHYXJrX3N0Zw.QIChG571hccCiDOp0dvZ5NLd3MHDKGA4UEx8rYcpmKeVG1VHYDGCZM51nA1GQD1SJYUIHtERRlN-**************&configId=**********-c5ef-4935-8e98-e2013b7ba593&bytedToken=20260331171630CA67F03F8F85*********&lng=zh
BytedToken: 20260331171630CA67F03F8F8**********

Waiting 3m0s before polling validation result...

GetVisualValidateResult response: {"Result":{"GroupId":"group-20260331171719-*****"},"ResponseMetadata":{"Version":"2024-01-01","Service":"ark","Region":"cn-beijing","RequestId":"20260331171930804FBCAD6EBE0C*****","Action":"GetVisualValidateResult"}}
Validation succeeded, GroupId = group-20260331171719-*****

Step 2：上传素材并使用 GetAsset 获取素材信息

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

代码执行以下逻辑：

createAsset：上传资源，获取 AssetId
waitForAssetActive：开始查询，循环调用 getAssetStatus 查询当前资产状态
根据 Status 判断
- Processing → 继续轮询
- Active → 返回 URL（结束）状态为 Active 后，可使用该素材 Asset ID (URI格式) 进行视频生成。
- Failed → 返回错误（结束）
返回结果并打印结果

示例代码：

Upload_Asset&_Get_Asset_Info.go

查询结果示意如下：

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

其他编程语言示例代码

demo.zip

说明

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

常见问题

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

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

在视频生成时，必须使用 素材所在项目 中的推理接入点进行推理。
如果素材上传成功，但使用获取素材接口获取素材失败，可能是因为调用上传素材(CreateAsset)和获取素材接口时传入了不同的 ProjectName 。
- ProjectName 默认值为 default，即如果不指定该字段，则默认将资源创建至 default 项目中。
- 建议在同一个项目中管理素材。

使用流程概述​

素材资产库结构说明​

真人人像素材资产 API 列表​

真人认证及获取 Group ID 接口​

Asset 创建接口​

Asset (Group) 管理接口​

限流说明​

使用教程​

Step 1. 创建真人人像素材组（Asset Group）​

拉起端上 H5 真人认证页​

使用 H5 完成真人认证​

获取本次真人认证创建的 Asset Group ID​

Step 2. 上传/管理素材​

上传素材​

检索素材 （API & 控制台）​

获取单个素材信息​

查询素材​

查询素材组​

更新/删除素材或素材组​

Step 3. 使用人像素材生成视频​

示例代码​

Step 1：生成真人认证链接并使用 GetVisualValidateResult 获取素材组 ID​

Step 2：上传素材并使用 GetAsset 获取素材信息​

其他编程语言示例代码​

常见问题​

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

使用流程概述

素材资产库结构说明

真人人像素材资产 API 列表

真人认证及获取 Group ID 接口

Asset 创建接口

Asset (Group) 管理接口

限流说明

使用教程

Step 1. 创建真人人像素材组（Asset Group）

拉起端上 H5 真人认证页

使用 H5 完成真人认证

获取本次真人认证创建的 Asset Group ID

Step 2. 上传/管理素材

上传素材

检索素材（API & 控制台）

获取单个素材信息

查询素材

查询素材组

更新/删除素材或素材组

Step 3. 使用人像素材生成视频

示例代码

Step 1：生成真人认证链接并使用 GetVisualValidateResult 获取素材组 ID

Step 2：上传素材并使用 GetAsset 获取素材信息

其他编程语言示例代码

常见问题

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