面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/guide-preview.md，全部文档索引见 https://ark.volcengine.com/llms.txt。

私域真人人像素材资产使用指南

为确保创作者能充分利用 Seedance 2.0 和 Seedance 2.5 强大的视频生成能力高效生成视频内容，同时规避 AI 生成内容的潜在风险，方舟推出了私域可信素材库。完成入库的可信素材将进入您的私域素材库，在视频生成中使用。
私域素材库支持录入真人人像素材，通过真人认证从根源锁定肖像权归属，规避后续肖像权纠纷风险；终端客户仅需完成一次授权，后续新增妆造可向同一素材资产组上传同人资产，无需重复真人认证流程。

使用前准备#

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

使用流程概述#

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

  • 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。

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

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

Asset 创建接口#

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

Asset (Group) 管理接口#

限流说明#

接口名 账号维度的限流
CreateVisualValidateSession 3 QPS
GetVisualValidateResult 3 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

使用教程#

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

拉起端上 H5 真人认证页#

使用 POST CreateVisualValidateSession 接口拉起端上 H5 真人认证页。
终端客户使用H5Link完成真人认证，点击“完成”按钮后，将打开 CallbackURL 链接，您可通过解析 CallbackURL 地址后拼接的 resultCode 参数，获取真人认证结果。
终端客户通过真人认证（resultCode 为 10000）后，您可使用 API 返回的 BytedToken 查询该终端客户对应的 Asset Group ID。

在请求中传入：

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

返回示例：

{
    "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 链接完成真人认证，检测结束后，将跳转至 CallbackURL。
  • 在 POSTGetVisualValidateResult 中使用 BytedToken 查询本次真人认证创建的 Asset Group ID。
  • 真人认证利用图像生成大模型的身份认证能力，具体信息可参考 相关文档。

使用 H5 完成真人认证#

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

火山客户：解析CallbackURL链接拼接参数后缀中的 resultCode 字段判断检测是否成功。当 resultCode 为 10000 时，真人认证成功。
更多错误码信息，请参考真人认证相关 错误码 文档。

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

真人认证成功后，使用 POST GetVisualValidateResult 获取本次真人认证创建的Asset Group ID。
在请求中传入：

  • BytedToken: 本次认证的唯一凭证标识，从 POST CreateVisualValidateSession 的返回体中获取。
  • ProjectName：指定资源项目名称，默认为 default。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考 文档。
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:      "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))
}

返回示例：

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

Step 2. 上传/管理素材#

上传素材#

使用 POST CreateAsset接口上传素材。

在请求中提供：

  • GroupId：必填，素材组合 ID

  • URL: 必填，图片/视频/音频可访问的 URL。素材文件的具体限制详见 Assets API 参考文档。

    • 以图像资产上传为例，人像资产内容最佳实践：
  • AssetType: 必填，支持上传图片/视频/音频类型素材，需指定为 Image/Video/Audio。
  • Name: 选填，素材名称，可用于管理素材，如素材文件名。
  • 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))
}

返回示例：

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

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

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

  • 控制台：您可在 方舟控制台 > 我的 > 真人人像 中搜索和查看已上传的人像素材。

  • API：

    • POST GetAsset获取单个素材

    • POST ListAssets 查询素材

    • POST ListAssetGroups 查询素材组合信息

获取单个素材信息#

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

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-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 对结果进行排序

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": "LivenessFace", // LivenessFace 为真人人像 Asset Group 类型
                "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 字段进行模糊搜索。

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-*****", "group-20260318033410-*****"},
                "GroupType": "LivenessFace",
            },
            "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": "LivenessFace",
        "ProjectName": "default",
        "CreateTime": "2026-03-18T03:33:32Z"
      }
    ],
    "NextToken": "****bmNyeXB0ZWRfY3Vyc29yIjoiLi4****"
}

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

您可调用 UpdateAsset、UpdateAssetGroup、DeleteAsset 和 DeleteAssetGroup 更新或删除素材及素材组。具体信息请参考：真人人像素材资产 API 列表

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

删除真人人像素材组时，还需满足 DeleteAssetGroup 中关于授权状态的删除限制。

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

在获取素材 Asset ID后，可使用私域人像素材生成视频。效果预览及使用方式请参考下文。
在 Video Generation API 的 content.<模态>_url.url 字段中使用 素材 URI 生成视频。

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

示例代码：

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)

示例代码#

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

  1. 请求 CreateVisualValidateSession
  2. 打印 H5 链接及 BytedToken
  3. 等待 3 minutes
  1. 轮询 GetVisualValidateResult
  2. 如返回 GroupId 则打印 ID 并退出
  3. 如返回错误，则打印错误

示例代码：

Generate_H5&Get_Group_ID.go

返回示例：

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 并根据状态，判断是否继续查询或返回对应结果。
代码执行以下逻辑：

  1. createAsset： 上传资源，获取 AssetId

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

  3. 根据 Status 判断

    • Processing → 继续轮询

    • Active → 返回 URL（结束）状态为 Active 后，可使用该素材 Asset ID (URI格式) 进行视频生成。

    • Failed → 返回错误（结束）

  4. 返回结果并打印结果

示例代码：

Upload_Asset&_Get_Asset_Info.go

查询结果示意如下：

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

常见问题#

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

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

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

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

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

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