?bytedToken=********&resultCode=10000&algorithmBaseRespCode=0&reqMeasureInfoValue=1&verify_type=real_time`
> * 详细后缀参数：
>
> * bytedToken：本次认证的唯一凭证标识，用来在`GetVisualValidateResult` 获取本次创建的 Group ID。
>
> * resultCode：
>
> * **当 resultCode 为** **`10000`** **时，检测成功**。
>
> * 更多错误码信息请参考真人认证相关 [错误码](https://docs.volcengine.com/docs/86081/1660367?lang=zh) 文档。
>
> * algorithmBaseRespCode：服务端子错误码。建议resultCode为服务端错误码时，再检查该字段对应的错误类型。具体请参考真人认证相关 [错误码](https://docs.volcengine.com/docs/86081/1660367?lang=zh) 文档。
>
> * reqMeasureInfoValue：本次操作是否计费，取值为0或1。0为不计费，1为计费。当前真人认证相关服务限时免费。
>
> * verify_type：认证类型，当前为固定值 `real_time`。
> **说明**
>
> 如果检测失败，H5 链接将失效，需再次调用 `CreateVisualValidateSession` 生成 H5 链接。
* 在 POST`GetVisualValidateResult` 中使用 BytedToken 查询本次真人认证创建的 Asset Group ID。
* 真人认证利用图像生成大模型的身份认证能力，具体信息可参考 [相关文档](https://docs.volcengine.com/docs/86081/1660369?lang=zh)。
### 使用 H5 完成真人认证
终端用户：打开 H5 链接，确认人脸信息授权主体与个人信息处理授权声明，进入后续真人认证。检测完成后，点击 **完成** 按钮，将打开拼接后缀参数的 CallbackURL 链接。
火山客户：解析CallbackURL链接拼接参数后缀中的 resultCode 字段判断检测是否成功。当 **resultCode** 为 **10000** 时，真人认证成功。
更多错误码信息，请参考真人认证相关 [错误码](https://docs.volcengine.com/docs/86081/1660367?lang=zh) 文档。
[视频](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/b57e6f903d8f4a9b9900591146e321e2)
### 获取本次真人认证创建的 Asset Group ID
真人认证成功后，使用 POST `GetVisualValidateResult` 获取本次真人认证创建的Asset Group ID。
在请求中传入：
* **BytedToken**: 本次认证的唯一凭证标识，从 POST `CreateVisualValidateSession` 的返回体中获取。
> **说明**
>
> **BytedToken 有效时间 30 分钟**。
* **ProjectName**：指定资源项目名称，默认为 **default**。一个项目中的资源仅可被该项目下的推理接入点使用，获取项目名称请参考 [文档](/docs/modelark-faq#03ec4a65)。
```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: "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`接口上传素材。
> **说明**
>
> * 每个Asset Group唯一绑定一个真实人像。素材资产（Assets）入库时，系统会将上传图像与真人认证采集的基准图像进行面部特征一致性比对，如判定素材非同一人物，将无法成功入库。
> * 当检测到素材中包含多个人脸时无法入库。
> * 每个上传的素材资产需经过预处理，可轮询调用 **GetAsset** 接口查询素材状态（对应参数为 **Status）**，仅当状态变为 `Active` 后，该素材资产方可用于后续推理使用；若状态为 `Failed` 则表示处理失败，无法用于后续推理使用。
> * 上传素材 （CreateAsset） API 为异步接口，系统处理可能出现排队，导致入库时间增加。不承诺上传时间 SLA。
在请求中提供：
* **GroupId**：必填，素材组合 ID
* **URL**: 必填，图片/视频/音频可访问的 URL。素材文件的具体限制详见 [Assets API 参考文档](/docs/create-asset-api)。
* **以图像资产上传为例，人像资产内容最佳实践**：
> **说明**
>
> **全身参考图要求**
> * 板式：竖版
> * 图片内容：人物全身正面图片
> **说明**
>
> **人脸特写图要求**
> * 板式： 竖版
> * 图片内容：人物正面无表情特写，肩部以上，人物面部占画面2/3左右
* **AssetType**: 必填，支持上传图片/视频/音频类型素材，需指定为 **Image/Video/Audio**。
* **Name**: 选填，素材名称，可用于管理素材，如素材文件名。
> **说明**
>
> 不同模型支持的输入音视频时长不同。建议在上传前记录上传音视频的时长，方便终端客户区分哪些素材可以在 Seedance 2.0 系列模型中使用。
> **说明**
>
> 该字段仅可用于在 ListAssets 接口中模糊搜索素材，不会被带入模型推理。在生成视频时，请勿使用该字段指代素材，请使用“图片 N”、“视频 N”格式进行指代。N 为素材在请求体同类素材中的排序。
* **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/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": "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 字段进行模糊搜索。
> **说明**
>
> 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": "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 列表](/docs/guide-preview#d6724da7)
建议定期通过 `GetAsset` 或 `ListAssets` 查看 `LastInferenceTime`，并通过 `DeleteAsset` 主动删除确认不再使用的素材。若整个素材组均不再需要，可调用 `DeleteAssetGroup`。未返回 `LastInferenceTime` 仅表示素材在 2026 年 7 月 24 日后没有调用记录，不能据此判断素材从未使用。删除前请结合自身业务记录确认，删除操作不可恢复。
删除真人人像素材组时，还需满足 `DeleteAssetGroup` 中关于授权状态的删除限制。
## Step 3. 使用人像素材生成视频
在获取素材 Asset ID后，可使用私域人像素材生成视频。效果预览及使用方式请参考下文。
在 Video Generation API 的 **content.<模态>_url.url** 字段中使用 素材 URI 生成视频。
> **说明**
>
> 资产 URI 拼接方式：`asset:// `
具体方式请参考 [Seedance 2.0 教程](/docs/seedance-2-0) 和 [创建视频生成任务 API参考](/docs/create-video-generation-task-api)。
> **说明**
>
> 在传入给模型的 Prompt 中，需要使用**图片 1**、**视频 1** 的方式指代参考素材，素材序号为素材在请求体中的顺序。请勿直接在 Prompt 中直接使用 Asset ID。
> 例：“**图片1** 里的女孩身着**图片2**中的服装，正在整理柜台上的物品。**图片3**中的男孩是一位顾客，他走上前，想要向女孩索要联系方式。”
示例代码：
```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**
> **说明**
>
> 此处建议使用 CallbackURL 后缀参数获取真人验证结果；当 **resultCode** 为 **10000**（真人认证通过）时，可使用`GetVisualValidateResult`获取本次真人认证创建的 Group ID。
4. 轮询 `GetVisualValidateResult`
5. 如返回 `GroupId` 则打印 ID 并退出
6. 如返回错误，则打印错误
示例代码：
[Generate_H5&Get_Group_ID.go](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/a6717347bf404eaab92d4f115f7b4e30~tplv-goo7wpa0wc-image.image)
返回示例：
```
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](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/268a0560a533491bb10df1eeeffa979e~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/de915358f2114603a4d425195cca8835~tplv-goo7wpa0wc-image.image)
> **说明**
>
> 注意替换 Demo 中的 AK与SK，若需调用其他接口如 ListAssets，需替换 ACTION 与对应请求参数。
# 常见问题
### 为什么素材上传成功后，无法使用素材生成视频或获取素材信息？
素材库按 [**项目**](/docs/modelark-faq#03ec4a65)**（Project）隔离**。
* 在视频生成时，必须使用**素材所在项目**中的推理接入点进行推理。
* 如果素材上传成功，但使用获取素材接口获取素材失败，可能是因为调用上传素材(CreateAsset)和获取素材接口时传入了不同的 **ProjectName**。
* **ProjectName** 默认值为 `default`，即如果不指定该字段，则默认将资源创建至 `default` 项目中。
* 建议在同一个项目中管理素材。