人脸主动活体检测

1 IC每次请求 HMAC 签名验证结果

v1.0 活跃 2026 年 7 月 POST /v3/store/ekyc/face-active-liveness/finalize

欢迎使用人脸主动活体检测 API，这是由艾艾普科技有限公司开发的一款人工智能产品。与被动活体检测（分析单张图像）不同，主动活体检测要求用户在摄像头前执行随机化的挑战——眨眼、向左转、向右转、微笑——以证明现场存在一个活生生、配合的人。会话在服务器端完成，API 返回一个经过加密签名的验证结果，您的后端可以独立验证，因此修改后的客户端永远无法伪造“通过”的结果。

试用 SDK（实时摄像头）

通过免费的开源 艾艾普 eKYC Web SDK 在浏览器中直接运行完整的挑战流程——它会锁定您的面部，发出随机挑战，选择最佳自拍帧，然后将其提交给 finalize API。更多流程请参见 完整 SDK 实时演示页面。

Loading live demo…

工作原理

该流程旨在由我们免费的开源 eKYC SDK（Web、Flutter、iOS、Android 和 React Native）驱动，该 SDK 在设备上处理摄像头、面部跟踪和挑战逻辑：

1. 面部锁定——SDK 找到唯一一个正面人脸，并等待其稳定且构图良好。
2. 随机化挑战——它从眨眼/向左转/向右转/微笑中随机抽取 3 个不同的挑战，并使用实时面部标志在设备上验证每个挑战（例如，眨眼必须是闭眼然后睁眼的过渡，因此印刷的闭眼照片无法通过）。
3. 最佳帧选择——在整个会话中，SDK 对每个清晰、正面、睁眼的帧进行评分，并保留最佳自拍（清晰度 × 面部大小）。
4. 完成——SDK 将最佳自拍以及带时间戳的挑战日志提交给 POST /v3/store/ekyc/face-active-liveness/finalize。
5. 服务器重新验证——服务器验证挑战日志（允许列表中的挑战类型、至少 2 个挑战、全部通过、严格单调递增的时间戳、合理的每个挑战时长、新鲜的会话），并使用我们的 iBeta Level 1 认证的被动活体检测引擎独立地重新检查自拍。
6. 签名验证结果——服务器返回一个使用 HMAC-SHA256 签名的验证结果。验证结果嵌入了自拍的 SHA-256 哈希值，将决策绑定到精确的图像字节。您的后端使用艾艾普颁发的共享密钥验证签名，并且只信任签名验证结果——绝不信任客户端自身的声明。

SDK 快速入门

集成主动活体检测最快的方式是使用免费的 Apache-2.0 许可的 艾艾普 eKYC SDK——请参阅 SDK 入门指南。

Flutter

# pubspec.yaml
dependencies:
  iapp_ekyc_sdk:
    git:
      url: https://github.com/iapp-technology/iapp-ekyc-sdk.git
      path: flutter

import 'package:iapp_ekyc_sdk/iapp_ekyc_sdk.dart';

final client = IappEkycClient(apiKey: 'YOUR_API_KEY');

// 人脸主动活体检测，带签名服务器验证结果
final liveness = await ActiveLivenessView.start(context, client: client);
if (liveness.verdict.passed) { /* 继续进行注册 */ }

Web (JavaScript)

npm install @iapp-technology/ekyc-sdk

import { IappEkyc } from '@iapp-technology/ekyc-sdk';

const ekyc = new IappEkyc({ apiKey: 'YOUR_API_KEY' });

const liveness = await ekyc.startActiveLiveness({
  mount: document.getElementById('ekyc-mount'),
});

入门

1. 先决条件

   • 来自艾艾普科技的 API 密钥
   • eKYC SDK（推荐）或等效的设备内挑战实现
   • 自拍格式：JPEG、JPG、PNG
   • 最大文件大小：10MB

2. 快速入门

   • Web、Flutter、原生 iOS/Android 和 React Native 的即插即用 SDK 摄像头流程
   • 每次会话都有随机挑战序列
   • 服务器签名的验证结果，用于防篡改集成
   • 由我们的 iBeta Level 1 认证的被动活体检测引擎提供支持

3. 主要功能

   • 眨眼、向左转、向右转和微笑挑战
   • 防作弊：面部丢失、多人或身份切换时会话重启
   • 最佳帧自拍选择（按清晰度评分）
   • HMAC-SHA256 签名验证结果，绑定到自拍的 SHA-256 哈希值

4. 安全与合规

   • 符合 GDPR 和 PDPA
   • 处理后不保留图像数据
   • 签名验证结果可在您的后端离线验证

如何获取 API 密钥？

请访问 API 密钥管理 页面查看您现有的 API 密钥或请求新密钥。

示例

人脸主动活体检测完成请求：

SDK 会为您构建此请求。如果您直接调用 API，请提交最佳自拍帧以及设备上记录的 JSON 挑战日志：

curl --location 'https://api.iapp.co.th/v3/store/ekyc/face-active-liveness/finalize' \
    --header 'apikey: {YOUR API KEY}' \
    --form 'file=@"selfie.jpg"' \
    --form 'challenges={
      "session_id": "b0e7c1a2-4f5d-4e6a-9b8c-7d6e5f4a3b2c",
      "sdk": { "name": "iapp-ekyc-sdk-flutter", "version": "0.1.0", "platform": "android" },
      "started_at": 1767500000000,
      "finished_at": 1767500008000,
      "challenges": [
        { "type": "blink",     "issued_at": 1767500000123, "completed_at": 1767500001873, "passed": true },
        { "type": "turn_left", "issued_at": 1767500002000, "completed_at": 1767500004100, "passed": true },
        { "type": "smile",     "issued_at": 1767500004500, "completed_at": 1767500006900, "passed": true }
      ]
    }'

人脸主动活体检测完成响应：

{
  "verdict": {
    "passed": true,
    "passive_liveness": { "predict": "REAL", "real_score": 0.9999, "threshold": 0.5 },
    "challenge_summary": {
      "total": 3,
      "passed": 3,
      "types": ["blink", "turn_left", "smile"],
      "duration_ms": 8000,
      "valid": true,
      "reasons": []
    },
    "session_id": "b0e7c1a2-4f5d-4e6a-9b8c-7d6e5f4a3b2c",
    "selfie_sha256": "ab12cd34ef56ab12cd34ef56ab12cd34ef56ab12cd34ef56ab12cd34ef56ab12",
    "timestamp": "2026-07-04T09:00:00.000Z",
    "nonce": "9f3a1c7e2b8d4f60"
  },
  "signature": "hex(HMAC-SHA256(secret, canonicalJSON(verdict)))",
  "signature_alg": "HMAC-SHA256",
  "process_time": 0.42
}

验证签名 (Node.js)：

您的后端必须使用艾艾普颁发的共享密钥，在 verdict 的规范化 JSON（所有对象键递归排序，无不重要空白，UTF-8）上重新计算 HMAC，并以恒定时间进行比较：

const crypto = require('crypto');
const sortKeysDeep = (v) =>
  Array.isArray(v) ? v.map(sortKeysDeep)
  : v && typeof v === 'object'
    ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeysDeep(v[k])]))
    : v;
const canonical = (o) => JSON.stringify(sortKeysDeep(o));
const expected = crypto.createHmac('sha256', SECRET).update(canonical(verdict)).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));

然后检查 verdict.passed、verdict.timestamp 的新鲜度，以及——如果自拍单独传输——其 SHA-256 是否等于 verdict.selfie_sha256。

功能与能力

核心功能

• 每次会话随机化的设备内挑战序列（眨眼、向左转、向右转、微笑）——设计上即可防重放。
• 使用我们的 iBeta Level 1 认证的被动活体检测引擎进行服务器端重新验证自拍。
• HMAC-SHA256 签名验证结果，通过 selfie_sha256 将决策绑定到精确的自拍字节。
• 严格的挑战日志验证：允许列表中的类型、最少 2 个挑战、严格单调递增的时间戳、每个挑战时长 300 毫秒–30 秒、会话时长 ≤ 120 秒、服务器时间 5 分钟内的新鲜度。
• 免费的开源客户端 SDK，支持 Web、Flutter、原生 iOS/Android 和 React Native，提供完全可主题化的 UI，支持英语、泰语和中文。

支持的字段

• 通过/失败的活体检测结果，包含被动活体检测分数和阈值。
• 每个会话的挑战摘要（类型、计数、时长、验证原因）。
• 可选的已验证自拍的 base64 回显（return_image=true）。
• 兼容 JPEG、JPG 和 PNG 自拍图像。

API 端点

端点	方法	描述	费用
POST /v3/store/ekyc/face-active-liveness/finalize	POST	完成主动活体检测会话——验证挑战日志，重新验证自拍，并返回签名验证结果	1 IC/次

API 参考

人脸主动活体检测端点

1. 人脸主动活体检测完成

POST /v3/store/ekyc/face-active-liveness/finalize

完成主动活体检测会话。验证设备内挑战日志，使用被动活体检测引擎重新验证最佳自拍帧，并返回 HMAC-SHA256 签名验证结果。

SDK 是预期的客户端

直接调用此端点需要您自己实现等效的设备内挑战（随机选择、实时标志验证、准确的挂钟时间戳）。eKYC SDK 是预期的客户端，并为您处理所有这些。

---

请求与响应格式

标头

名称	类型	描述
apikey	String	调用此 API 的 API 密钥

请求正文（multipart/form-data）

名称	类型	必需	描述
file	File	是	会话中的最佳自拍帧（JPEG/PNG，服务器端进行魔术字节验证，最大 10MB）
challenges	String	是	挑战日志的 JSON 字符串——会话 ID、SDK 信息和每个挑战的时间戳（参见上方示例）
return_image	String	否	设置为 "true" 以在 selfie 字段中收到 base64 编码的回显自拍（默认省略）

响应参数

名称	类型	描述
verdict	Dictionary	签名活体检测验证结果对象
verdict.passed	Boolean	总体结果——仅当挑战日志有效且自拍通过被动活体检测时为 true
verdict.passive_liveness	Dictionary	被动活体检测重新检查：predict（REAL/SPOOF）、real_score、threshold
verdict.challenge_summary	Dictionary	挑战验证：total、passed、types、duration_ms、valid、reasons
verdict.session_id	String	从挑战日志中回显的会话 UUID
verdict.selfie_sha256	String	上传自拍的 SHA-256 哈希值（64 个十六进制字符）——将签名绑定到图像字节
verdict.timestamp	String	验证结果的服务器时间（ISO 8601）
verdict.nonce	String	使每个验证结果唯一的随机数
signature	String	verdict 规范化 JSON 的十六进制 HMAC-SHA256，使用您的共享密钥加密
signature_alg	String	始终为 HMAC-SHA256
selfie	Dictionary	仅当 return_image=true 时：filename、content_type、size、image_base64
process_time	Float	服务器处理时间（秒）

错误代码

代码	错误	描述
400	INVALID_CHALLENGE_LOG / INVALID_IMAGE / MISSING_FIELD	格式错误的挑战日志、无效图像或缺少必需字段（带 reasons 数组）
401	Invalid API key	缺少或无效的 apikey 标头（网关）
402	Insufficient credit	在 积分 充值（网关）
413	File too large	自拍超过 10MB 限制
502	UPSTREAM_UNAVAILABLE	活体检测引擎暂时不可用——稍后重试

计费

一个已完成的检查，即使返回 "passed": false，也是 HTTP 200 响应，并且仍计费 1 IC——活体检测已运行并产生了签名验证结果。错误响应（400/401/402/413/502）永远不会计费。

定价

操作	生产路径	IC 成本	单位	本地部署
人脸主动活体检测完成	/v3/store/ekyc/face-active-liveness/finalize	1 IC	每次请求	联系我们