稳定、快速的API服务

活体检测H5_V4，我们致力于为用户提供专业的免费API数据接口服务

活体检测H5_V4 v1.0

最后更新: 2026-09-02 12:12:08

根据提示做出对应动作，在线进行实时动态检测，判断是否为活体真人，用户动作不匹配时不会立即失败，继续等待做出正确动作。

按次计费(¥0.15/次) 调用次数: 0 正常运行 响应速度: <100ms 需要传入API密钥

接口信息

接口地址：
https://api.shuliancloud.com/v4/liveness/h5/v4/token
请求方式： GET/POST
返回格式： JSON

调用统计

0
今日调用
0
总调用次数
请求示例 https://api.shuliancloud.com/v4/liveness/h5/v4/token

点击右侧按钮复制完整请求地址，参数值请替换为实际有效值

请求参数 （暂无请求参数）

参数名 是否必填 参数类型 参数说明
暂无请求参数信息

请求参数说明

# H5活体检测流程V4
####  获取token   --> 前端加载H5活体检测页面，检测完成跳转到回调页面 --> 查询活体检测结果

<a name="sign">

#### 签名算法说明：
######  服务商分配的appid、当前时间毫秒数timestamp、商户分配的app_security、 三者通过&符号拼接成字符串进行md5加密得到。
     如：appid=xyzxyzxyz，timestamp=1555378976238，app_security=efcefcefcefcefc ;
	 拼接后的字符串格式：str = appid的值&amptimestamp的值&app_security的值;
     拼接后的字符串：str = xyzxyzxyz&1555378976238&efcefcefcefcefc ;
     加密后得到sign = md5(str) = 4e7e1974b79f3656aeaf03f1158f5d5d ;
	 注：sign不满32位需补0
</a>

# 接口名称：1.获取token
#### 描述：通过该接口获取token凭证，用于后面活体检测和查询检测结果
请求地址 url：https://api.shuliancloud.com/v4/liveness/h5/v4/token
请求方式 method：get/post
参数（如body传参以表单方式提交，不要json方式）：

|  名称 |  类型 |是否必填   | 说明  |
| ------------ | ------------ | ------------ | ------------ |
| appid  |  varchar |  是 | 服务商分配的唯一标识  |
| timestamp |  number | 是  | 当前时间的毫秒数  |
| sign  | varchar  | 是  | 签名，<a href='#sign'>签名算法说明</a>  |
| returnUrl | varchar  | 是  | 活体检测成功后回调页面的url  |
| actionLiveParam | varchar  | 否  | 动作数组，用英文逗号分隔，例如：LookLeft,OpenMouth 默认不需要传，具体说明请查看"动作说明" |
| style  |varchar  | 否| 动作样式选择，目前支持1和2。 样式1：随机从摇头、点头、左转头、右 转头4个头部动作中选取一个动作，再随  机从眨眼和张嘴2个局部动作中选取一个 动作，然后随机组合这两个动作的顺序  样式2：随机从眨眼和张嘴2个局部动作中选取一个动作 |
| actionMutex  | Boolean  | 否 | 是否检查动作互斥，默认false(不检查动作互斥)。即动作不匹配时不会立即失败 |
| antiCameraHack| Boolean  | 否 |是否开启闪光防摄像头劫持检测，默认false。即随机性闪光检查视频是否为实时采集，对光线环境会有一定要求|
| foreLiveOn| Boolean  | 否 |是否开启前端小模型活体算法，资源消耗小，速度快，在客户端运行。默认true|
| backLiveOn| Boolean  | 否 |是否开启云端大模型活体算法，资源消耗大，速度慢，在服务器端运行。默认false|
| showSuccess| Boolean  | 否 |是否展示采集成功的结果页面。默认false|
| showFail| Boolean  | 否 |是否展示采集失败的结果页面，会显示失败的具体原因，有利于问题诊断。默认true|
| hideGuidePage| Boolean  | 否 |是否隐藏引导页，false为不隐藏，true为隐藏。默认false|
| title | varchar  | 否 |采集页面的标题文本，最长32个字符。默认"活体人脸采集"|
| enableH5CompatibleModel | Boolean  | 否| true表示H5环境不支持算法预检时将使用原生相机录制视频的方式 ，false表示H5环境不支持算法预检时将需要用户手动将采集URL复制到其他可用环境完成采集。默认true|


**动作说明：**
**actionLiveParam**：动作数组，默认不传，如果actionLiveParam和style都没传，将随机2个动作。如果传入指定动作，将会严格按照指定的顺序和动作类型进行采集，忽略style动作参数。动作参数如下：
NoOne：无需任何动作(静默刷脸)
LookLeft：向左（对于真实人的左边，而非镜像后的图像的左边）转头，要求动作不要很快，幅度适宜（30度左右）
LookRight：向右（对于真实人的右边，而非镜像后的图像的右边）转头，要求动作不要很快，幅度适宜（30度左右）
OpenMouth：张嘴，从闭嘴变为张开嘴巴，动作不要很快，幅度适宜（嘴唇距离双指以上）
BlinkEye：眨眼，由睁眼到闭眼，动作不要很快，眼睛睁开到紧闭
ShakeHead：摇头，向左右转头，动作不要很快，幅度适宜（30度左右）
NodHead：点头，上下转头，动作不要很快，幅度适宜（30度左右）

#### 正确返回：
```
{
    "msg": "成功",
    "success": true,
    "code": 200,
    "data": {
        "url": "https://livenessh5.shuliancloud.com/capture.html?token=0fc79b80371f45e2ac1c693ef9136b24",
        "token": "0fc79b80371f45e2ac1c693ef9136b24"
    }
}
```
#### 错误返回：
```
{
    "msg": "参数错误", 
    "success": false, 
    "code": 400, 
    "data": { }
}

```
#### 返回字段说明：

|  字段名 | 说明  |
| ------------ | ------------ |
| success  | 接口请求成功标识，true为成功，false为失败，失败情况下，会有对应描述和状态码  |
| code  |成功为200，其它为失败状态码   |
| msg  | code对应的说明描述   |
| data  |结果详细信息|
| token  | 采集及获取结果时所使用的凭证，有效期2个小时，在此时效内，应用侧可以发起采集请求（重复的采集所触发的结果会被忽略）和结果查询|
| url  | 采集所使用的地址，应用应引导前端程序跳转到此地址 |

# 2.请求H5活体检测页面
#### 描述：前端加载 获取token返回的检测url地址 ，检测完成后会跳转到第一步传入的returnUrl页面。


# 接口名称：3.查询活体检测结果
#### 描述：查询第二步活体检测结果
请求地址 url：https://api.shuliancloud.com/v4/liveness/h5/v4/result
请求方式 method：get/post
参数（如body传参以表单方式提交，不要json方式）：

|  名称 |  类型 |是否必填   | 说明  |
| ------------ | ------------ | ------------ | ------------ |
| appid  |  varchar |  是 | 服务商分配的唯一标识  |
| timestamp |  number | 是  | 当前时间的毫秒数  |
| sign  | varchar  | 是  | 签名，<a href='#sign'>签名算法说明</a>  |
| token | varchar  | 是  | token凭证  |

#### 活体检测通过：
```
{
    "msg": "成功",
    "success": true,
    "code": 200,
    "data": {
        "order_no": "037331695737768767",
        "result": 0,
        "codeDesc": "活体检测成功",
        "faceUrl": "https://img.shuliancloud.com//h5v4/2282987191.jpg",
    }
}

```

#### 活体检测不通过：
```
{
    "msg": "成功",
    "success": true,
    "code": 200,
    "data": {
        "order_no": "037331695737768767",
        "result": 1,
        "codeDesc": "活体动作与指令不匹配，请注意动作的速度和幅度成功"
    }
}

```

#### 错误返回：
```
{
    "msg": "参数错误",
    "success": false,
    "code": 400,
    "data": { }
}
```
#### 返回字段说明：

|  字段名 | 说明  |
| ------------ | ------------ |
| success  | 接口请求成功标识，true为成功，false为失败，失败情况下，会有对应描述和状态码  |
| code  |成功为200，其它为失败状态码   |
| msg  | code对应的说明描述   |
| data  | 验证结果详细信息|
| result  | 0-活体检测通过; 1-活体检测不通过；2-未找到活体检测结果； 0和1收费  |
|codeDesc|对应描述。不通过时可能返回以下描述：1.动作与指令不匹配，请注意动作的速度和幅度；2.未在等待时间内采集到正确动作；3.未能采集到质量合格的活体人脸照片；4.未通过前端活体检测算法；5.未通过后端活体检测算法|
| faceUrl |采集到活体人像裁剪后人脸的下载地址，内容是JPEG流，文件大小一般不超过50KB，有效期1个小时，需要保存请及时下载。注：只有活体检测通过才有人脸地址|








#### code错误码说明
|  code |  说明 |
| ------------ | ------------ |
| 200  | 成功  |
| 400  | 参数错误   |
| 404  | 请求资源不存在   |
| 500  | 系统内部错误，请联系服务商   |
| 501  |第三方服务异常
| 601  | 服务商未开通接口权限 |
| 602  | 账号停用 |
| 603  | 余额不足请充值 |
| 604  | 接口停用 |
| 605  | 次数不足，请购买套餐 |
|606 | 调用超限，请联系服务商
| 1001 | 其他，以实际返回为准

返回参数 （暂无返回参数）

参数名 参数类型 参数说明
暂无返回参数信息

返回参数说明

|  字段名 | 说明  |
| ------------ | ------------ |
| success  | 接口请求成功标识，true为成功，false为失败，失败情况下，会有对应描述和状态码  |
| code  |成功为200，其它为失败状态码   |
| msg  | code对应的说明描述   |
| data  |结果详细信息|
| token  | 采集及获取结果时所使用的凭证，有效期2个小时，在此时效内，应用侧可以发起采集请求（重复的采集所触发的结果会被忽略）和结果查询|
| url  | 采集所使用的地址，应用应引导前端程序跳转到此地址 |

# 2.请求H5活体检测页面
#### 描述：前端加载 获取token返回的检测url地址 ，检测完成后会跳转到第一步传入的returnUrl页面。


# 接口名称：3.查询活体检测结果
#### 描述：查询第二步活体检测结果
请求地址 url：https://api.shuliancloud.com/v4/liveness/h5/v4/result
请求方式 method：get/post
参数（如body传参以表单方式提交，不要json方式）：

|  名称 |  类型 |是否必填   | 说明  |
| ------------ | ------------ | ------------ | ------------ |
| appid  |  varchar |  是 | 服务商分配的唯一标识  |
| timestamp |  number | 是  | 当前时间的毫秒数  |
| sign  | varchar  | 是  | 签名，<a href='#sign'>签名算法说明</a>  |
| token | varchar  | 是  | token凭证  |

#### 活体检测通过：
```
{
    "msg": "成功",
    "success": true,
    "code": 200,
    "data": {
        "order_no": "037331695737768767",
        "result": 0,
        "codeDesc": "活体检测成功",
        "faceUrl": "https://img.shuliancloud.com//h5v4/2282987191.jpg",
    }
}

```

#### 活体检测不通过：
```
{
    "msg": "成功",
    "success": true,
    "code": 200,
    "data": {
        "order_no": "037331695737768767",
        "result": 1,
        "codeDesc": "活体动作与指令不匹配，请注意动作的速度和幅度成功"
    }
}

```

#### 错误返回：
```
{
    "msg": "参数错误",
    "success": false,
    "code": 400,
    "data": { }
}
```
#### 返回字段说明：

|  字段名 | 说明  |
| ------------ | ------------ |
| success  | 接口请求成功标识，true为成功，false为失败，失败情况下，会有对应描述和状态码  |
| code  |成功为200，其它为失败状态码   |
| msg  | code对应的说明描述   |
| data  | 验证结果详细信息|
| result  | 0-活体检测通过; 1-活体检测不通过；2-未找到活体检测结果； 0和1收费  |
|codeDesc|对应描述。不通过时可能返回以下描述：1.动作与指令不匹配，请注意动作的速度和幅度；2.未在等待时间内采集到正确动作；3.未能采集到质量合格的活体人脸照片；4.未通过前端活体检测算法；5.未通过后端活体检测算法|
| faceUrl |采集到活体人像裁剪后人脸的下载地址，内容是JPEG流，文件大小一般不超过50KB，有效期1个小时，需要保存请及时下载。注：只有活体检测通过才有人脸地址|

返回示例 

{
    "msg": "成功",
    "success": true,
    "code": 200,
    "data": {
        "url": "https:\/\/livenessh5.shuliancloud.com\/capture.html?token=0fc79b80371f45e2ac1c693ef9136b24",
        "token": "0fc79b80371f45e2ac1c693ef9136b24"
    }
}