> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance 真人素材验证 API

> 创建火山 H5 真人认证会话，获取 Asset Group ID，并将真人素材上传到对应素材组供 Seedance 工作流使用

## 概览

当您需要将真人肖像素材上传到 Seedance 私域素材组时，请使用此流程。真人认证会创建一个绑定单个真实人脸的 `Asset Group ID`。获取
`GroupId` 后，调用 [Seedance 素材上传 API](/zh/models/seedance/asset-upload) 并传入 `group_id`
，即可把该真人对应的图片、视频或音频素材上传到同一个素材组。

## 流程

1. 调用 `POST /api/v1/client/job/visual-validate-session`，传入您的 `callback_url`。
2. 将返回的 `H5Link` 打开给终端用户，让用户完成真人人脸验证。
3. 验证结束后，H5 页面会跳转到您的 `callback_url`，并在 URL 参数中携带 `bytedToken`、`resultCode` 等验证结果。
4. 当 `resultCode` 为 `10000` 时，调用 `GET /api/v1/client/job/visual-validate-result`，传入 `byted_token` 获取 `GroupId`。
5. 调用 [Seedance 素材上传 API](/zh/models/seedance/asset-upload)，将返回的 `GroupId` 作为 `group_id`
   传入。之后的上传流程与普通素材上传一致。
6. 通过 [Seedance 素材信息 API](/zh/models/seedance/asset-info) 轮询素材状态，直到 `Status` 变为 `Active`，再在 Seedance
   生成请求中使用返回的 `AssetId`。

<Note>
  H5 真人认证链接有效期为 120 秒。如果验证失败或链接过期，需要重新创建认证会话。
</Note>

<Tip>
  可通过在 `H5Link` 后缀追加或修改 `lng` 参数指定页面语言。目前支持简体中文 `zh`、英文 `en` 和繁体中文 `zh-Hant`，默认值为 `zh`。
</Tip>

## 步骤 1：创建认证会话

调用此接口创建火山 H5 真人认证链接。

### 请求体

<ParamField body="callback_url" type="string" required>
  终端用户完成 H5 认证页面后打开的回调 URL。验证结果参数会追加到该回调地址后。
</ParamField>

### 请求示例

```json theme={null}
{
  "callback_url": "https://example.com/callback/seedance-visual-validation"
}
```

### 响应示例

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "BytedToken": "202603311449168C23BA26**************",
    "H5Link": "https://visual.volcengine.com/validate?...&bytedToken=202603311449168C23BA26**************&lng=zh",
    "CallbackURL": "https://example.com/callback/seedance-visual-validation"
  }
}
```

## 回调参数

用户完成验证后，H5 页面会跳转到您的回调地址。成功验证的回调通常如下：

```text theme={null}
https://example.com/callback/seedance-visual-validation?bytedToken=********&resultCode=10000&algorithmBaseRespCode=0&reqMeasureInfoValue=1&verify_type=real_time
```

| 参数                      | 说明                                      |
| ----------------------- | --------------------------------------- |
| `bytedToken`            | 本次认证的唯一凭证。查询认证结果时作为 `byted_token` 传入。   |
| `resultCode`            | 认证结果。`10000` 表示认证通过。                    |
| `algorithmBaseRespCode` | 服务端子错误码。建议在 `resultCode` 表示服务端错误时检查该字段。 |
| `verify_type`           | 认证类型，当前固定为 `real_time`。                 |

## 步骤 2：获取认证结果

当回调显示认证通过后，调用此接口获取该真人对应的 `GroupId`。

### 查询参数

<ParamField query="byted_token" type="string" required>
  创建认证会话接口返回的 `BytedToken`，或回调 URL 中收到的 `bytedToken`。
</ParamField>

### 请求示例

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl -X GET "https://api.crun.ai/api/v1/client/job/visual-validate-result?byted_token=202603311449168C23BA26**************" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null} theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"

  response = requests.get(
      "https://api.crun.ai/api/v1/client/job/visual-validate-result",
      params={"byted_token": "202603311449168C23BA26**************"},
      headers={"X-API-KEY": API_KEY},
  )

  print(response.json())
  ```
</CodeGroup>

### 响应示例

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "GroupId": "group-20260331145705-*****"
  }
}
```

## 步骤 3：上传素材到素材组

上传素材时，将返回的 `GroupId` 作为 `group_id` 传入：

```json theme={null}
{
  "name": "fashion-model-front",
  "asset_type": "Image",
  "asset_url": "https://example.com/assets/fashion-model-front.jpg",
  "group_id": "group-20260331145705-*****"
}
```

每个真人 `Asset Group` 唯一绑定一个真实人脸。素材上传到该组时，上游服务会将上传素材中的人脸与真人认证采集的基准人脸进行一致性比对。如果不是同一人，或素材中检测到多个人脸，入库可能失败。

## 相关资源

<CardGroup cols={2}>
  <Card title="素材上传" icon="upload" href="/zh/models/seedance/asset-upload">
    上传图片、视频和音频素材，也可传入 `group_id` 上传真人素材
  </Card>

  <Card title="素材信息" icon="magnifying-glass" href="/zh/models/seedance/asset-info">
    查询上传状态，并等待素材变为可用
  </Card>
</CardGroup>


## OpenAPI

````yaml zh/models/seedance/visual-validate.json post /api/v1/client/job/visual-validate-session
openapi: 3.0.0
info:
  title: Seedance 真人素材验证 API
  description: 用于创建真人认证会话并获取 Seedance 真人素材上传所需 Asset Group ID 的 API 文档
  version: 1.0.0
  contact:
    name: Technical Support
    email: support@crun.ai
servers:
  - url: https://api.crun.ai
    description: API 服务器
security:
  - ApiKeyAuth: []
paths:
  /api/v1/client/job/visual-validate-session:
    post:
      summary: 创建真人 H5 认证会话
      description: >-
        创建火山 H5 真人认证链接。将返回的 `H5Link` 打开给终端用户；验证通过后，使用接口返回或回调中的 `BytedToken` 查询
        Asset Group ID。
      operationId: seedance/visual-validate-session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - callback_url
              properties:
                callback_url:
                  type: string
                  format: uri
                  description: >-
                    终端用户完成 H5 认证后打开的回调 URL。验证结果参数会追加到该地址后，例如 `bytedToken` 和
                    `resultCode`。
                  example: https://example.com/callback/seedance-visual-validation
            example:
              callback_url: https://example.com/callback/seedance-visual-validation
      responses:
        '200':
          description: 认证会话创建成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          BytedToken:
                            type: string
                            description: 认证凭证。用于查询认证结果和 Asset Group ID。
                            example: 202603311449168C23BA26**************
                          H5Link:
                            type: string
                            format: uri
                            description: >-
                              H5 真人认证链接，有效期为 120 秒。可通过 `lng` 参数指定页面语言：`zh`、`en`
                              或 `zh-Hant`，默认值为 `zh`。
                            example: >-
                              https://visual.volcengine.com/validate?...&bytedToken=202603311449168C23BA26**************&lng=zh
                          CallbackURL:
                            type: string
                            format: uri
                            description: 本次认证会话使用的回调 URL。
                            example: >-
                              https://example.com/callback/seedance-visual-validation
              example:
                code: 200
                message: success
                data:
                  BytedToken: 202603311449168C23BA26**************
                  H5Link: >-
                    https://visual.volcengine.com/validate?...&bytedToken=202603311449168C23BA26**************&lng=zh
                  CallbackURL: https://example.com/callback/seedance-visual-validation
        '422':
          description: 参数校验错误
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          enum:
            - 200
            - 401
            - 402
            - 404
            - 422
            - 429
            - 455
            - 500
            - 501
            - 505
          description: |-
            响应状态码

            - **200**：成功，请求已成功处理
            - **401**：未授权，缺少认证信息或认证无效
            - **402**：额度不足，账户额度不足以完成本次操作
            - **404**：资源不存在，请求的资源或接口不存在
            - **422**：参数校验错误，请求参数未通过校验
            - **429**：请求过于频繁，已超出当前资源的调用限制
            - **455**：服务不可用，系统当前正在维护中
            - **500**：服务器错误，处理请求时发生了意外错误
            - **501**：生成失败，内容生成任务执行失败
            - **505**：功能已禁用，请求的功能当前不可用
        message:
          type: string
          description: 响应消息；失败时为错误说明
          example: success
  responses:
    Error:
      description: 服务器错误
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |-
        所有接口均需通过 API Key 进行认证。

        获取 API Key：
        1. 访问 [API Key 管理页面](https://crun.ai/zh/user-api-key) 获取你的 API Key

        使用方式：
        在请求头中添加：

        x-api-key: YOUR_API_KEY

        注意事项：
        - 请妥善保管你的 API Key，不要泄露给他人
        - 如果怀疑 API Key 已泄露，请立即在管理页面中重置

````