真人活体认证

真人活体认证用于拉起火山 H5 真人认证页，终端客户在 H5 页面完成活体校验后，平台据此创建可用的真人素材组。本服务由火山引擎提供，使用宁享Token API Key（Bearer Token）鉴权。

重要说明

拉起认证页，非提交素材检测：本接口创建一次 H5 真人认证会话，返回认证页链接 h5_link 与凭证 byted_token。终端客户打开 h5_link 在火山 H5 页面完成人脸识别，不是上传素材文件做检测。
活体认证由火山方提供。认证记录按 API Key 隔离。
认证成功 = 创建真人素材组：终端客户认证通过（回调 resultCode=10000）后，平台自动创建对应的真人素材组，组 ID 可在认证历史中查到。

Base URL

/  （部署域名，例如 https://your-domain.com）

创建认证会话

POST/api/assets/liveness/session

创建一次真人认证会话，返回 H5 认证页链接与凭证。

Bearer Token

请求参数

参数	类型	必填	默认值	描述
callback_url	string	否	平台默认回调	认证结束后跳转的公网可访问 URL。不传则用平台自带回调端点
model	string	否	-	指定认证结果要适配的模型

对齐火山 CreateVisualValidateSession：仅 callback_url 为业务参数。无需传素材文件——认证在火山 H5 页面进行。

请求示例

bash

curl -X POST /api/assets/liveness/session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callback_url": "https://your-domain.com/liveness/callback"}'

响应示例

成功响应

json

{
  "success": true,
  "data": {
    "byted_token": "********2204****DDA08****",
    "h5_link": "https://ark.volcengine.com/region:cn-beijing/mobile/livenees-face-manage/authorization?...",
    "history_id": 12,
    "suggest_model": "doubao-seedance-2-0",
    "liveness_group": "real"
  }
}

字段	说明
byted_token	本次认证唯一凭证，用于后续查询认证结果（有效期 30 分钟，仅支持认证一次）
h5_link	火山 H5 认证页链接，终端客户打开完成人脸识别（使用一次后失效）
history_id	本次认证在平台的历史记录 ID
suggest_model	本次认证适配的模型（可忽略）

认证流程

调用本接口获取 h5_link；
终端客户在浏览器打开 h5_link，在火山 H5 页面完成人脸识别；
客户点击「完成」后跳转到 callback_url，URL 后拼接 bytedToken / resultCode 等参数：
- resultCode=10000 表示认证成功；
认证成功后平台自动创建真人素材组，可在「认证历史」查询对应 group_id。

认证历史

GET/api/assets/liveness/history

获取当前 API Key 下的活体认证历史记录，支持过滤与分页。

Bearer Token

请求参数

参数	类型	必填	默认值	描述
group_id	string	否	-	按素材组 ID 过滤
status	string	否	-	按状态过滤：`pending` / `success` / `failed`
page	integer	否	1	页码，从 1 开始
page_size	integer	否	20	每页条数，1-100

请求示例

bash

curl "/api/assets/liveness/history?status=success&page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

成功响应

json

{
  "success": true,
  "data": [
    {
      "history_id": 12,
      "group_id": "mg-20260930120000-abcde",
      "status": "success",
      "result_code": 10000,
      "created_at": "2026-09-04T01:00:00+08:00",
      "updated_at": "2026-09-04T01:02:00+08:00"
    }
  ],
  "total": 15,
  "page": 1,
  "page_size": 20
}

字段	说明
status	`pending`（进行中）/ `success`（认证通过）/ `failed`（认证失败）
result_code	火山认证结果码，`10000` 表示成功
group_id	认证成功后创建的真人素材组 ID（pending/failed 时为空）

真人活体认证 ​

重要说明 ​

Base URL ​

创建认证会话 ​

请求参数 ​

请求示例 ​

响应示例 ​

认证流程 ​

认证历史 ​

请求参数 ​

请求示例 ​

响应示例 ​

相关文档 ​

真人活体认证

重要说明

Base URL

创建认证会话

请求参数

请求示例

响应示例

认证流程

认证历史

请求参数

请求示例

响应示例

相关文档