交互式活体检测(H5页面接入)
2025.12.08 18:12:21
一、接入流程

二、获取 authToken 和认证页面地址接口
接口说明
网易易盾信息认证服务使用签名方法对接口进行鉴权,所有接口每一次请求都需要包含签名信息(signature参数),以验证用户身份,防止信息被恶意篡改。目前支持MD5,SHA1,SHA256,SM3几种加密算法,详细信息,请参见接口鉴权
请求地址
| 名称 | 值 |
|---|---|
| HTTP URL | https://verify.dun.163.com/v1/face/liveness/h5/auth |
| HTTP Method | POST |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Content-Type | String | 是 | 固定值:"application/x-www-form-urlencoded" |
请求参数
请求参数由请求公共参数和请求业务参数两部分组成,通用参数见请求通用字段
| 名称 | 类 型 | 必填 | 最大长度 | 描述 |
|---|---|---|---|---|
| redirectUrl | String | 是 | 512 | 认证成功后,重定向的URL,如果是小程序填写示例为:/pages/index/index |
| callBackUrl | String | 否 | 512 | 结果回调通知URL,回调请求方式默认为GET,回调地址必须以https开头。平台在完成认证后会回调该地址,并自动添加taskid、status字段,status字段值返回的是subcode值。示例:https://www.163.com?authToken=1000004826&taskld=shaxxxx&status=1 |
| retry | String | 否 | 8 | 认证失败是否重试 0不重试、1重试 为空默认重试 |
| dataId | String | 否 | 64 | 数据标识 可传⼊⽤户标识等数据 便于数据查询 |
| callbackValidate | String | 否 | 64 | 安全校验,由您⾃⾏⽣成,⽤于防重复、 防篡改校验。 如果设置了该值会在回调地址中显示callbackValidate字段 |
响应返回码
响应返回码见:响应返回码
响应结果
响应字段如下,响应通用字段已省略,详细见响应公共字段
| 参数名称 | 类型 | 必须返回 | 描述 |
|---|---|---|---|
| authUrl | String | 是 | 认证地址 |
| authToken | String | 是 | 认证 Token,有效期30分钟 |
响应结果示例
当认证成功时,输出示例如下:
{
"code": 200,
"msg": "ok",
"result": {
"authUrl": "xxx",
"authToken": "xxx "
}
}
三、authToken 校验接口
接口说明
网易易盾信息认证服务使用签名方法对接口进行鉴权,所有接口每一次请求都需要包含签名信息(signature参数),以验证用户身份,防止信息被恶意篡改。目前支持MD5,SHA1,SHA256,SM3几种加密算法,详细信息,请参见接口鉴权
请求地址
| 名称 | 值 |
|---|---|
| HTTP URL | http://verify.dun.163.com/v1/face/liveness/h5/recheck |
| HTTP Method | POST |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Content-Type | String | 是 | 固定值:"application/x-www-form-urlencoded" |
请求参数
请求参数由请求公共参数和请求业务参数两部分组成,通用参数见请求通用字段
| 名称 | 类 型 | 必填 | 最大长度 | 描述 |
|---|---|---|---|---|
| authToken | String | 是 | 32 | 认证 Token,有效期30分钟 |
响应返回码
响应返回码见:响应返回码
响应结果
响应字段如下,响应通用字段已省略,详细见响应公共字段
响应结果示例
活体检测:详情参考活体检测接口: 认证成功时,输出示例如下:
{
"code": 200,
"msg": "ok",
"result": {
"taskId": "527a0ba75d564320b71d85eee6a5bc7b",
"picType": 1,
"avatar": null,
"lpCheckStatus": 1,
"reasonType": 1,
"isPayed": 1,
"faceAttributeInfo": null
}
}
四、前端重定向参数
认证成功后,跳转到重定向地址时会携带以下参数
| 名称 | 类 型 | 必填 | 描述 |
|---|---|---|---|
| authToken | String | 是 | 认证 token,有效期30分钟 |
| code | String | 否 | 验证结果码,0 表示成功,当 retry 为 0 时才会返回,其他错误代码见下表 |
| success | String | 否 | 验证结果,当 retry 为 0 时才会返回,true 表示验证成功,false 表示验证失败 |
| callbackValidate | String | 否 | 安全校验值,只有当 callbackValiate 不为空时返回 |
SDK 错误码
| 错误码 | 说明 | 用户提示 |
|---|---|---|
| 10001 | 网络错误 | 前方拥堵,请重新尝试 |
| 11000 | 相机权限获取失败 | 无法获取相机权限 |
| 11001 | 认证失败 | 前方拥堵,请重新尝试 |
| 11002 | 浏览器不兼容 | 浏览器不兼容 |
| 11003 | 相机权限被拒绝 | 无法获取相机权限 |
| 11004 | 未找到摄像头 | 无法读取摄像头 |
| 11005 | 摄像头硬件错误 | 无法读取摄像头 |
| 11006 | 摄像头分辨率过低 | 摄像头分辨率过低 |
| 11007 | 摄像头未知错误 | 无法读取摄像头 |
| 11008 | 炫瞳检测失败 | 炫瞳检测失败 |
活体检测服务端错误码
| 错误码 | 说明 | 用户提示 |
|---|---|---|
| 1 | 活体检测成功 | - |
| 2 | 活体检测失败 | 活体检测不通过 |
| 4 | 云端检测超时 | 前方拥堵,请重新尝试 |
| 5 | 图片上传失败 | 前方拥堵,请重新尝试 |
| 7 | 检测超时 | 前方拥堵,请重新尝试 |
| 10 | 疑似攻击 | 活体检测不通过 |
| 11 | 疑似未成年人 | 识别到疑似未成年人 |
| 13 | 人脸被遮挡 | 活体检测不通过 |
