拉起真人认证 H5

Authorization

AuthorizationBearer <token>

兼容网关 API Key，例如 sk-...。

In: header

Query Parameters

Action*string

Default"CreateVisualValidateSession"

Version*string

Default"2024-01-01"

Header Parameters

X-Date?string

使用 HMAC-SHA256 时必填，格式为 YYYYMMDDTHHMMSSZ。

X-Content-Sha256?string

使用 HMAC-SHA256 时必填，请求体 SHA-256 小写十六进制。

Request Body

application/json

CallbackURL*string

火山原始接口要求必填的认证完成跳转地址。界云兼容层不处理真实回调，建议固定传入 https://callback.default，平台会原样返回；认证结果请使用 BytedToken 调用 GetVisualValidateResult 主动查询。

Formaturi

Lengthlength <= 2048

ProjectName?string

资源所属项目名称，大小写敏感。省略时使用 default。

Default"default"

Response Body

application/json

curl -X POST "https://jieyun.cc/?Action=CreateVisualValidateSession&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "CallbackURL": "https://callback.default",
    "ProjectName": "default"
  }'

curl -X POST "https://jieyun.cc/?Action=CreateVisualValidateSession&Version=2024-01-01" \  -H "Content-Type: application/json" \  -d '{    "CallbackURL": "https://callback.default",    "ProjectName": "default"  }'

{
  "ResponseMetadata": {
    "RequestId": "20260721000000000000000000000000",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "BytedToken": "20260721120000-example-token",
    "H5Link": "https://ark.volcengine.com/region:cn-beijing/mobile/livenees-face-manage/authorization?pl=example",
    "CallbackURL": "https://callback.default"
  }
}

{
  "ResponseMetadata": {
    "RequestId": "string",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "Code": "string",
      "Message": "string"
    }
  }
}

Empty

接口说明

调用 CreateVisualValidateSession 创建一次性真人认证会话。终端用户打开返回的 H5Link 完成认证后，使用同一响应中的 BytedToken 调用 GetVisualValidateResult 获取本次创建的真人素材组 ID。

本文档已按火山引擎官方接口说明校对。鉴权方式参见素材库认证与签名。

接口地址

POST https://jieyun.cc/?Action=CreateVisualValidateSession&Version=2024-01-01

界云兼容层不处理真实 CallbackURL

CallbackURL 是火山原始接口的必填字段，但当前界云兼容层不依赖该地址接收认证结果。建议固定传入 https://callback.default，平台会在响应中原样返回。终端用户完成 H5 认证后，请使用 BytedToken 主动调用 GetVisualValidateResult 查询结果。

请求参数字段

字段	类型	必选	中文描述
`CallbackURL`	string	必选	认证结束后的跳转地址。界云兼容层建议固定传入 `https://callback.default`；不要依赖该地址接收认证结果。最大长度为 2048。
`ProjectName`	string	可选	资源所属项目名称，默认值为 `default`，大小写敏感。资源不在默认项目中时，必须填写正确的项目名称。

请求体示例：

{
  "CallbackURL": "https://callback.default",
  "ProjectName": "default"
}

响应参数字段

字段	类型	必选	中文描述
`BytedToken`	string	可选	本次认证的唯一凭证，用于调用 `GetVisualValidateResult` 获取本次创建的 `GroupId`。有效期为 30 分钟，仅支持完成一次认证，禁止重复使用。
`H5Link`	string	可选	终端用户打开的真人认证页面链接。链接使用后失效；再次认证必须重新调用本接口生成。可通过 `lng` 参数指定页面语言。
`CallbackURL`	string	可选	返回请求中携带的回调地址。界云兼容层会原样返回该字段。

H5Link 页面语言

在 H5Link 后附加 lng 参数可以指定认证页面语言：

`lng`	页面语言
`zh`	简体中文，默认值
`en`	英文
`zh-Hant`	繁体中文

示例：

<H5Link>&lng=en

火山原始接口的 CallbackURL 行为

火山原始接口地址为：

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

直接调用火山原始接口时，终端用户点击 H5 页面的“完成”按钮后，会打开 CallbackURL，并在地址后拼接以下查询参数：

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

参数	说明
`bytedToken`	本次认证的唯一凭证，可用于调用 `GetVisualValidateResult`。
`resultCode`	`10000` 表示检测成功；其他值请结合真人认证错误码处理。
`algorithmBaseRespCode`	服务端子错误码，建议在 `resultCode` 表示服务端错误时进一步检查。
`reqMeasureInfoValue`	本次操作是否计费，`0` 表示不计费，`1` 表示计费。当前真人认证相关服务限时免费。
`verify_type`	认证类型，当前固定为 `real_time`。

即使直接使用火山原始回调，也应在认证成功后使用 BytedToken 调用 GetVisualValidateResult，获取终端用户对应的素材组 ID。界云兼容层请遵循上方“推荐调用流程”，不要依赖这些回调参数。

200application/json

400application/json

401

403

404

503

application/json

application/json