【端云结合】活体检测H5 - API接入(H5、小程序、公众号、APP)

最近更新：2026-01-13

易顺达活体检测H5解决方案

接入类型	接入方式	用户认证流程	接入方传入材料	输出主要内容
PC或移动端H5网页小程序公众号 APP	纯服务端API接入	网页刷脸活体检测服务端活体检测	无	活体检测结果人脸认证图片人脸认证视频

1. 产品简介

什么是【端云结合】活体检测 - API接入

【端云结合】活体检测产品基于计算机视觉、大数据分析和人工智能技术，提供人脸检测及活体检测功能。创新的炫彩活体检测和动作活体检测，能够有效防御AI换脸和深度伪造等新型攻击和传统的呈现式攻击及注入式攻击，为用户和机构提供安全便捷的人脸识别和活体检测服务。

API 接入方式，产品采用高效便捷的设计，仅需向用户提供一个认证 URL，即可完成活体检测流程。

适用场景：无明确限定，覆盖H5、小程序、公众号多平台。更适合不需要深度嵌入自有App，追求快速实现活体检测功能的场景。
接入效率：客户平均接入时间仅需30分钟左右。
核心特点：
接入速度极快，无需对现有App进行改造，接入方能快速上线功能。
平台方更容易更新底层SDK，可快速迭代产品版本，及时应对黑灰产不断升级的攻击手法，保障核身安全性。
相比SDK接入兼容性更好，降级模式启用读数活体功能，可覆盖更多的终端设备。

什么是端云结合模式

用户在客户端完成客户端刷脸活体检测，并将采集到的人脸图片加密送到服务端完成风控检测、服务端活体检测和权威数据源验证，然后向客户返回认证结果以及采集的最佳人脸图片或人脸视频。

产品优势

安全等级高

全链路加密：敏感信息加密传输，采用动态口令“一图一密”机制。
全链路风险实时对抗：风险决策引擎对用户设备、运行环境和用户操作行为等特征进行实时监控，及时发现异常情况有效防御恶意操作行为，保障高安全水位。
多维度活体检测技术：创新的炫彩检测、动作检测、静默检测等活体检测方法，可有效抵御AI换脸、深度伪造、照片修改、面具、遮挡以及屏幕翻拍等攻击手段。
灵活的检测模式：支持对活体检测模式进行灵活组合，例如指定多动作活体+炫彩活体的联合检测方式，同时多动作活体中支持自定义动作、个数、顺序。

算法性能强

活体检测算法，速度快、体验好、通过率高。
人脸识别算法，准确率高、速度快，在比对万分之一阈值下通过率大于99%。

灵活易用

可根据客户实际业务需求，快速对解决方案进行定制化开发，满足客户需求。
接入方式全覆盖，支持 Android、IOS、鸿蒙、微信小程序、微信 H5、PC等主流客户端。
服务端兼容多种平台，支持本地化部署，兼容主流 Linux 操作系统和国产信创系统；

应用场景

活体检测产品的主要应用场景如下

远程身份认证

在银行远程开户、保险理赔、转账交易、在线开户、电子政务、交通出行等环节，通过移动端采集人脸信息，判断是否为活体并结合人脸比对产品或权威信息源判断是否是本人，保证交易安全和账户安全，提升远程业务办理效率。

人脸图像采集与检测

在银行、政务等场景中，使用移动端采集用户人脸图像进行留底，并且可以结合产品中的多人脸检测、闭眼检测等能力检查采集的图像是否满足要求，为用户提供人脸采集解决方案。

产品效果图

2. 产品使用介绍

接入准备

购买H5活体检测产品套餐包（免费试用100次），购买地址。

计费方式

接口名	是否计费	计费说明
发起认证请求	计费	响应报文 code 字段返回 200 时计一次费。
查询认证结果	不计费	-

活体检测流程

整体交互流程

sequenceDiagram autonumber actor 用户 #yellow participant 应用方页面 #green participant 应用方服务器 #green participant 阿里云网关 #orange participant 活体检测页面 #lightblue rect rgb(240, 248, 255) %% 阶段一：初始化 note over 用户, 活体检测页面: 阶段一：初始化流程用户 ->> 应用方页面: 触发核验流程（如点击认证按钮）应用方页面 ->> 应用方服务器: 发送请求，告知需发起核验应用方服务器 ->> 阿里云网关: 调用「发起认证请求」接口阿里云网关 -->> 应用方服务器: 返回 verifyUrl 和 orderNo 应用方服务器 ->> 应用方服务器: 保存 orderNo （用于查询认证结果）应用方服务器 -->> 应用方页面: 下发 verifyUrl end rect rgb(240, 255, 240) %% 阶段二：执行认证 note over 用户, 活体检测页面: 阶段二：认证流程应用方页面 ->> 活体检测页面: 跳转到 verifyUrl（打开活体检测页面）用户 ->> 活体检测页面: 根据页面提示完成认证阿里云网关 -->> 应用方服务器: 发送 orderNo 到 notifyUrl（可选，notifyUrl非空时）活体检测页面 ->> 应用方服务器: 携带 orderNo 请求应用方的 returnUrl end rect rgb(255, 248, 240) %% 阶段三：结果处理 note over 用户, 活体检测页面: 阶段三：结果处理应用方服务器 ->> 阿里云网关: 调用「获取认证结果」接口，传入 orderNo，获取认证结果。阿里云网关 -->> 应用方服务器: 返回认证结果应用方服务器 ->> 应用方页面: 执行后续业务流程。 end

阶段一

用户端业务触发核验流程。
应用方页面发送请求到应用方服务器，告知应用方服务器需要发起一次核验流程。
应用方服务器传入相关参数调用阿里云网关发起认证请求接口，获取 verifyUrl 和 orderNo.（接口文档请参见下文《服务端集成》）。
应用方服务器将获取到的 orderNo 进行保存，并将 verifyUrl 下发给应用方页面。

阶段二

应用方页面跳转到 verifyUrl，打开活体检测页面。
用户在活体检测页面上根据页面提示进行认证流程。
认证完成后，应用方服务器将 orderNo 发送给应用方的 notifyUrl 地址。（可选，notifyUrl 不为空才会发起请求）
认证完成后，应用方服务器将认证结果下发给活体检测页面，活体检测页面会携带 orderNo 请求应用方的returnUrl 地址。

阶段三

应用方服务器传入 orderNo 调用阿里云网关获取认证结果接口，获取认证结果，进行后续业务流程。

3. 服务端集成

阿里云API网关调用规则

购买API商品成功后，如何调用API，请阅读《如何使用阿里云API类商品》。

重要

使用简单认证方式时，建议通过应用方服务器和API网关通信。

因为简单认证方式免去了复杂的签名过程，但是把AppCode作为明文暴露网络中传输，会带来一些安全隐患，请务必重视。

API 文档

发起认证请求

接口名：getVerifyUrl

全局接入地址：livenessh5.eshunda.cn（IPv4）

请求方法：POST

传输协议：HTTPS

Content-Type: application/x-www-form-urlencoded

接口说明：每次开始认证前通过本接口获取 orderId，用来串联认证请求中的各个接口。

请求参数

名称	类型	是否必选	描述	示例值
bizId	String	是	客户服务端自定义的业务唯一标识，用于后续定位排查问题使用。值最长为32位长度的字母数字组合，请确保唯一。	dl747f5a11c40a5aa5e6ed
livingType	String	是	活体检测类型 1：远近 2：眨眼 3：摇头 4：点头 5：张嘴 6: 炫彩	26：眨眼检测+炫彩检测最多支持4种活体方式组合，推荐使用眨眼检测+炫彩检测。
returnUrl	String	是	客户业务页面回跳的目标地址。认证完成后会携带orderNo，重定向页面到该地址。(前端方式回调)	支持多种推送方式，请阅读下文《returnUrl推送规则》
notifyUrl	String	否	认证结果的回调通知地址。平台在认证完成后会携带ordrNo通过POST表单形式回调该地址。（后端方式回调）重要 1.仅当认证完成时才会触发回调，若用户在刷脸页面认证中放弃、异常中断或未进行认证均不会通知。 2.建议您收到回调通知时，若有需要可通过查询接口获取认证详情信息。 3.该值的传入会在调用接口前做可访问校验，如果传入的地址不能在公网访问，不会发送请求。 4.接口在回调后务必返回 HTTP 状态码 200，否则会触发重试，3秒内两次回调。	请阅读下文《notifyUrl推送规则》

返回数据

名称	类型	描述	示例值
code	String	返回码：200 为成功，其他为失败。	200
msg	String	请求参数的响应信息。	成功
logId	String	日志Id	dl747f5a11c40a5aa*****
data.orderNo	String	订单唯一标识。重要 orderNo字段为计费统计字段，为了方便后续核对账单，请您在本地留存该字段信息。初始化接口返回的认证orderNo在60分钟有效且仅能认证提交一次，请您在有效期内应用，避免重复使用。	202505271116193330KFGGaBmHh9uY5i
data.verifyUrl	String	Web浏览器进行活体检测的URL，认证结束后根据入参ReturnUrl进行跳转。警告 verifyUrl在60分钟有效且仅能认证提交一次，请您在有效期内使用，避免重复使用。	略

返回code和msg说明

code	msg	描述
200	success	成功。
400	参数不能为空	参数不能为空。
401	非法参数	非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。
412	欠费中	产品欠费中，请充值后操作。
414	设备类型不支持	当前移动设备不支持刷脸认证，请更换设备后操作。
415	SDK版本不支持	当前认证SDK版本不支持刷脸认证，请升级SDK后操作。
416	系统版本不支持	当前操作系统版本不支持刷脸认证，请升级系统或更换设备操作。
500	系统错误	系统内部错误，请反馈工程师排查。

出参示例

{
    "msg": "success",
    "code": "200",
    "data": {
        "orderNo": "202505191116193330KFGGaBmHh9uY5i",
        "verifyUrl": "略"
    }
}

查询认证结果

接口名：getResult

全局接入地址：livenessh5.eshunda.cn（IPv4）

请求方法：POST

传输协议：HTTPS

Content-Type: application/x-www-form-urlencoded

接口说明：当您收到回调通知之后，可以在服务端通过该接口获取认证结果。（服务端会执行后端活体检测和风险检测）。

请求参数

名称	类型	是否必选	描述	示例值
orderNo	String	是	订单唯一标识。（由发起认证请求接口返回。）	202505271116193330KFGGaBmHh9uY5i

返回数据

名称	类型	描述	示例值
code	String	返回码：200 为成功，其他为失败。	200
msg	String	请求参数的响应信息。	成功
logId	String	日志Id	dl747f5a11c40a5aa*****
data.passed	String	认证结果，取值：T：通过F：未通过说明判断认证结果以该字段为准。	T
data.resultCode	String	认证结果描述。您可以在resultCode说明中查看不同状态码的描述和处理建议。说明判断认证结果请以 ResultObject.Passed 字段为准。	200
data.bestImgUrl	String	活体检测采集的人脸照片oss下载链接，有效期12小时。	略

返回code和msg说明

code	msg	描述
200	success	成功。
201	查询不到认证结果	可能是用户中断了认证流程或用户未开始认证。
400	参数不能为空	参数不能为空。
401	非法参数	非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。
412	欠费中	产品欠费中，请充值后操作。
414	设备类型不支持	当前移动设备不支持刷脸认证，请更换设备后操作。
415	SDK版本不支持	当前认证SDK版本不支持刷脸认证，请升级SDK后操作。
416	系统版本不支持	当前操作系统版本不支持刷脸认证，请升级系统或更换设备操作。
500	系统错误	系统内部错误，请反馈工程师排查。

特别说明：

响应报文 code 字段返回 200 时计一次费。

resultCode说明

resultCode	msg	描述
200	认证通过	认证完成。
201	活体检测不通过	实人认证产品，活体检测不通过时会返回此状态码。
202	姓名、身份证和人脸不一致	可能是用户的信息有误或用户的信息为假信息，建议用户确认后重新操作。
203	查询不到身份信息	可能是用户户口迁移等特殊状态导致，建议预留人工审核入口，进行人工审核。说明若同一用户多次认证不通过，建议用户尝试通过CTID官方App更新留底数据后再次进行认证。
204	业务策略限制，风控系统判定该笔认证安全等级为高危风险。	为了保证认证的安全性，系统风险决策引擎会对认证的设备、人脸、行为等环境进行安全检测。常见风险原因： - 该设备检测到疑似存在劫持摄像头、被Root、注入、模拟器等高风险特征。 - 该设备或身份存在一定时间内高频重复认证行为。您可以按照如下方法排查处理： - 提醒用户卸载掉设备上可能安装的各种多开、分身、虚拟环境等软件或插件。 - 恢复设备系统初始安全环境后重试。 - 若是内部测试或已经线下人工确认正常，您可以联系客服加白处理。

出参示例

{
    "msg": "success",
    "code": "200",
    "data": {
        "passed": "T",
        "resultCode": "200",
        "bestImgUrl": "略"
    }
}

Q&&A

returnUrl推送规则

推送内容

名称	类型	是否一定返回	描述	示例值
code	String	是	认证结果的返回码。具体内容请阅读下文《获取认证结果》	略
msg	String	是	认证结果的响应信息。具体内容请阅读下文《获取认证结果》	略
logId	String	否	日志Id 仅当服务端出现错误时返回该字段	dl747f5a11c40a5aa*****
orderNo	String	是	订单唯一标识，用于获取认证结果。（由发起认证请求接口返回。）	202505271116193330KFGGaBmHh9uY5i

特别说明：

当SDK出现异常时，直接跳转到 returnUrl，不会执行后端认证流程。

参数code返回内容如下：

名称	类型	描述
EXCEPTION	String	未知异常。
SDK_UNSUPPORT	String	摄像头打开异常。
SDK_PERMISSION_DENIED	String	用户拒绝提供摄像头权限。
SDK_TIMEOUT	String	打开摄像头超时。
DECRYPT_ERROR	String	token解密异常。

推送方式

post请求
GET:
window.location.replace
wx.miniProgram.navigateTo

您需要通过在 returnUrl 前添加特定前缀来选择重定向方式，默认使用POST方式。

示例值：

returnUrl = "https://example.com/default" // 默认方式，form表单，post请求

returnUrl = "post:https://example.com/callback" // form表单，post请求

returnUrl = "get:https://example.com/result" // window.location.replace

returnUrl = "miniprogram:https://example.com/page" // wx.miniProgram.navigateTo

returnUrl = "miniprogram:/page" // wx.miniProgram.navigateTo

returnUrl 接收认证结果和验签示例

POST方式

@RequestMapping("/return-demo")
public void returnUrlDemo(@RequestBody String result) {
    JSONObject jsonObject = JSON.parseObject(result);
    String code = jsonObject.getString("code");
    String code = jsonObject.getString("msg");
    String code = jsonObject.getString("logId");
    String code = jsonObject.getString("orderNo");
}

GET方式

@GetMapping("/return-demo")
public void returnUrlDemo(String code, String msg, String logId, String orderNo, Model model, HttpServletRequest request) {
    log.info("code:{}", code);
    log.info("msg:{}", msg);
    log.info("logId:{}", logId);
    log.info("orderNo:{}", orderNo);
}

notifyUrl推送规则

推送内容

名称	类型	是否一定返回	描述	示例值
orderNo	String	是	订单唯一标识，用于获取认证结果。（由发起认证请求接口返回。）	202505271116193330KFGGaBmHh9uY5i

推送方式

请求方法：POST

Content-Type：application/json;charset=utf-8

请求体格式：JSON字符串

notifyUrl 接收认证结果

@PostMapping ("/notify-demo")
public void notifyUrlDemo(@RequestBody String result) {
   log.info("notify-demo接收到的原始数据: {}", result);
}

兼容性说明

因 Web 实时音视频技术对浏览器和手机系统存在兼容性要求，实时音视频技术的兼容性情况如下：

手机平台	浏览器	兼容性要求
IOS	微信内嵌浏览器	iOS 系统版本14.3+，微信版本6.5+
	Safari 浏览器	iOS 系统版本11.1.2+，浏览器版本11+
	Chrome 浏览器	iOS 系统版本14.3+
Android	微信内嵌浏览器	支持
	自带浏览器	Android 系统版本7+ 华为、OPPO、VIVO、魅族、荣耀、三星等自带浏览器兼容性较好（支持率80%），小米自带浏览器兼容性一般（支持率30%）
	其他浏览器	Android 系统版本7+，支持 Chrome 浏览器，不支持QQ 、UC浏览器

注意：

由于 H.264 版权限制，华为系统的 Chrome 浏览器和以 Chrome WebView 为内核的浏览器,均不支持实时音视频技术的正常运行。

SDK采集的照片尺寸说明

默认尺寸：640×480
特殊情况：部分机型不支持上述默认分辨率，SDK 将自动适配该机型支持的其他分辨率（具体尺寸不固定，以机型实际能力为准）。

联系方式

商务手机：13728636697

商务微信：13728636697

商务钉钉：eshunda

商务邮箱：eshundaface@163.com

商务QQ：1394734377

技术支持：