# 拉起真人认证 H5

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volcengineapi.com/?Action=CreateVisualValidateSession&Version=2024-01-01`

拉起端上 H5 真人认证页链接。
终端客户使用 *H5Link* 完成真人认证，点击"完成"按钮后，将打开 *CallbackURL* 链接，您可通过解析 *CallbackURL* 地址后拼接的 *resultCode* 参数，获取真人认证结果。
终端客户通过真人认证（*resultCode* 为 `10000`）后，您可使用 API 返回的 *BytedToken* 查询该终端客户对应的 Asset Group ID。具体使用方式请参考 [拉起端上 H5 活体认证页](/docs/guide-preview#632b4d17)。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。

---

<span id="request-parameters"></span>
## 请求参数

### Body 参数

**CallbackURL** `string` `必选` | 回调 URL

用于认证结束后跳转的可访问 URL

**ProjectName** `string` `默认值 default` | 所属项目

资源所属的项目名称（大小写敏感）。若资源不在默认项目中，需填写正确的项目名称。

## 响应参数

**BytedToken** `string` | 认证凭证

本次认证的唯一凭证标识，用来在 *GetVisualValidateResult* 获取本次创建的 Group ID。

**注意**：byted_token 有效期为 30 分钟，请及时使用（仅支持认证一次，禁止重复认证）。

**CallbackURL** `string` | 回调 URL

用于认证结束后跳转的公网可访问 URL

> **说明**
>
> 终端客户使用 H5Link 完成真人认证，点击"完成"按钮后，将打开 CallbackURL 链接，您可解析 CallbackURL 链接后拼接的相关参数获取认证结果。
> * 拼接示例：
> `<CallbackURL>?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。

**H5Link** `string` | H5 认证链接

链接在使用后失效，再次检测需重新调用 *CreateVisualValidateSession* 生成链接。

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


## 代码示例

## 默认

### cURL

#### Request

```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'X-Date: <X-Date>' \
  -H 'X-Content-Sha256: <X-Content-Sha256>' \
  -H 'Authorization: HMAC-SHA256 Credential=<AK>/<X-Date>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<Signature>' \
  -d '{
    "CallbackURL": "https://your-domain.example.com/callback",
    "ProjectName": "default"
}
'
```

#### Response

```
{
    "ResponseMetadata": {
        "RequestId": "202405142130005E6F708192031A2B3C",
        "Action": "CreateVisualValidateSession",
        "Version": "2024-01-01",
        "Service": "ark",
        "Region": "cn-beijing"
    },
    "Result": {
        "BytedToken": "vvs-20240514212750-c8f2p",
        "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://your-domain.example.com/callback"
    }
}
```