การตรวจจับความมีชีวิตชีวาแบบแอคทีฟของใบหน้า

1 ICต่อคำขอ คำตัดสินที่เซ็นชื่อ HMAC

v1.0 ใช้งานอยู่ กรกฎาคม 2026 POST /v3/store/ekyc/face-active-liveness/finalize

ยินดีต้อนรับสู่ API การตรวจจับความมีชีวิตชีวาแบบแอคทีฟของใบหน้า ซึ่งเป็นผลิตภัณฑ์ AI ที่พัฒนาโดย บริษัท ไอแอพพ์เทคโนโลยี จำกัด แตกต่างจากความมีชีวิตชีวาแบบพาสซีฟ (ซึ่งวิเคราะห์ภาพเดียว) ความมีชีวิตชีวาแบบแอคทีฟจะขอให้ผู้ใช้ทำตามความท้าทายแบบสุ่ม — กะพริบตา หันซ้าย หันขวา ยิ้ม — ต่อหน้ากล้อง เพื่อพิสูจน์ว่ามีบุคคลที่มีชีวิตและให้ความร่วมมืออยู่จริง การดำเนินการจะเสร็จสมบูรณ์ที่ฝั่งเซิร์ฟเวอร์ และ API จะส่งกลับคำตัดสินที่เซ็นชื่อด้วยการเข้ารหัสลับ ซึ่งแบ็กเอนด์ของคุณสามารถตรวจสอบได้ด้วยตนเอง ดังนั้นไคลเอนต์ที่ถูกแก้ไขจึงไม่สามารถปลอมแปลงผลลัพธ์ "ผ่าน" ได้

ลองใช้ SDK (กล้องจริง)

เรียกใช้กระบวนการท้าทายทั้งหมดได้ที่นี่ในเบราว์เซอร์ของคุณด้วย iApp eKYC Web SDK แบบโอเพนซอร์สฟรี — มันจะจับใบหน้าของคุณ ออกคำท้าทายแบบสุ่ม เลือกเฟรมเซลฟี่ที่ดีที่สุด และส่งไปยัง API finalize ดูเวิร์กโฟลว์เพิ่มเติมได้ที่ หน้าเดโมสด SDK ฉบับเต็ม

Loading live demo…

วิธีการทำงาน

เวิร์กโฟลว์ได้รับการออกแบบมาให้ขับเคลื่อนโดย eKYC SDK แบบโอเพนซอร์สฟรีของเรา (Web, Flutter, iOS, Android & React Native) ซึ่งจัดการกล้อง การติดตามใบหน้า และตรรกะการท้าทายบนอุปกรณ์:

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

วิธีที่เร็วที่สุดในการรวมความมีชีวิตชีวาแบบแอคทีฟคือ iApp eKYC SDK ที่ฟรีภายใต้ใบอนุญาต Apache-2.0 — ดู คู่มือเริ่มต้นใช้งาน 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) { /* ดำเนินการต่อกับการลงทะเบียน */ }

เว็บ (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. เริ่มต้นใช้งานอย่างรวดเร็ว

   • เวิร์กโฟลว์กล้อง SDK แบบ Drop-in สำหรับ Web, Flutter, iOS/Android แบบเนทีฟ และ React Native
   • ลำดับการท้าทายแบบสุ่มในทุกเซสชัน
   • คำตัดสินที่เซ็นชื่อโดยเซิร์ฟเวอร์สำหรับการผสานรวมที่ป้องกันการปลอมแปลง
   • ขับเคลื่อนโดยเอนจิ้นความมีชีวิตชีวาแบบพาสซีฟที่ได้รับการรับรอง 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):

แบ็กเอนด์ของคุณต้องคำนวณ HMAC ใหม่จาก JSON ที่เป็นมาตรฐานของ verdict (เรียงลำดับคีย์ออบเจกต์ทั้งหมดแบบเรียกซ้ำ, ไม่มีช่องว่างที่มีนัยสำคัญ, UTF-8) โดยใช้คีย์ลับที่แชร์ซึ่งออกโดย ไอแอพพ์ และเปรียบเทียบในเวลาคงที่:

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 ms–30 s, ความยาวเซสชัน ≤ 120 s, ความสดใหม่ภายใน 5 นาทีของเวลาเซิร์ฟเวอร์
• SDK ไคลเอนต์แบบโอเพนซอร์สฟรีสำหรับ Web, Flutter, iOS/Android แบบเนทีฟ และ React Native พร้อม UI ที่ปรับแต่งได้เต็มรูปแบบในภาษาอังกฤษ ไทย และจีน

ฟิลด์ที่รองรับ

• คำตัดสินความมีชีวิตชีวาแบบผ่าน/ไม่ผ่าน พร้อมคะแนนความมีชีวิตชีวาแบบพาสซีฟและเกณฑ์
• สรุปการท้าทายต่อเซสชัน (ประเภท, จำนวน, ระยะเวลา, เหตุผลในการตรวจสอบ)
• ตัวเลือกการแสดงเซลฟี่ที่ตรวจสอบแล้วแบบ base64 (ถ้า return_image=true)
• ความเข้ากันได้กับรูปภาพเซลฟี่ JPEG, JPG และ PNG

API Endpoints

Endpoint	Method	Description	ราคา
POST /v3/store/ekyc/face-active-liveness/finalize	POST	ทำให้เซสชันความมีชีวิตชีวาแบบแอคทีฟสมบูรณ์ — ตรวจสอบบันทึกการท้าทาย ตรวจสอบเซลฟี่ซ้ำ และส่งคืนคำตัดสินที่เซ็นชื่อ	1 IC ต่อคำขอ

การอ้างอิง API

Endpoints ความมีชีวิตชีวาแบบแอคทีฟของใบหน้า

1. การเสร็จสิ้นความมีชีวิตชีวาแบบแอคทีฟของใบหน้า

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

ทำให้เซสชันความมีชีวิตชีวาแบบแอคทีฟสมบูรณ์ ตรวจสอบบันทึกการท้าทายบนอุปกรณ์ ตรวจสอบเฟรมเซลฟี่ที่ดีที่สุดอีกครั้งด้วยเอนจิ้นความมีชีวิตชีวาแบบพาสซีฟ และส่งคืนคำตัดสินที่เซ็นชื่อด้วย HMAC-SHA256

SDK เป็นไคลเอนต์ที่ต้องการ

การเรียก endpoint นี้โดยตรงต้องใช้การใช้งานของคุณเองสำหรับการท้าทายบนอุปกรณ์ที่เทียบเท่า (การเลือกแบบสุ่ม การตรวจสอบจุดสำคัญแบบเรียลไทม์ การประทับเวลาที่ถูกต้อง) eKYC SDK เป็นไคลเอนต์ที่ต้องการและจัดการทั้งหมดนี้ให้คุณ

---

รูปแบบคำขอและการตอบกลับ

Headers

Name	Type	Description
apikey	String	คีย์ API ของคุณเพื่อเรียก API นี้

Request Body (multipart/form-data)

Name	Type	Required	Description
file	File	Yes	เฟรมเซลฟี่ที่ดีที่สุดจากเซสชัน (JPEG/PNG, ตรวจสอบ magic-byte ที่ฝั่งเซิร์ฟเวอร์, สูงสุด 10MB)
challenges	String	Yes	สตริง JSON ของบันทึกการท้าทาย — ID เซสชัน ข้อมูล SDK และการประทับเวลาต่อการท้าทาย (ดูตัวอย่างด้านบน)
return_image	String	No	ตั้งค่าเป็น "true" เพื่อรับเซลฟี่ที่ส่งกลับเป็น base64 ในฟิลด์ selfie (ค่าเริ่มต้นถูกละไว้)

พารามิเตอร์ในการตอบกลับ

Name	Type	Description
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	Nonce แบบสุ่มที่ทำให้ทุกคำตัดสินมีเอกลักษณ์
signature	String	Hex HMAC-SHA256 ของ JSON ที่เป็นมาตรฐานของ verdict โดยใช้คีย์ลับที่แชร์ของคุณ
signature_alg	String	เป็น HMAC-SHA256 เสมอ
selfie	Dictionary	เฉพาะเมื่อ return_image=true: filename, content_type, size, image_base64
process_time	Float	เวลาประมวลผลของเซิร์ฟเวอร์เป็นวินาที

รหัสข้อผิดพลาด

Code	Error	Description
400	INVALID_CHALLENGE_LOG / INVALID_IMAGE / MISSING_FIELD	บันทึกการท้าทายที่ผิดรูปแบบ, รูปภาพไม่ถูกต้อง, หรือฟิลด์ที่จำเป็นขาดหายไป (พร้อมอาร์เรย์ reasons)
401	Invalid API key	ส่วนหัว apikey ขาดหายไปหรือไม่ถูกต้อง (gateway)
402	Insufficient credit	เติมเงินได้ที่ เครดิต (gateway)
413	File too large	เซลฟี่เกินขีดจำกัด 10MB
502	UPSTREAM_UNAVAILABLE	เอนจิ้นความมีชีวิตชีวาไม่พร้อมใช้งานชั่วคราว — ลองอีกครั้งในภายหลัง

การเรียกเก็บเงิน

การตรวจสอบที่เสร็จสมบูรณ์ซึ่งส่งคืน "passed": false ยังคงเป็น HTTP 200 และถูกเรียกเก็บเงิน 1 IC — การตรวจสอบความมีชีวิตชีวาได้ทำงานและสร้างคำตัดสินที่เซ็นชื่อ การตอบกลับข้อผิดพลาด (400/401/402/413/502) จะไม่ถูกเรียกเก็บเงิน

ราคา

การดำเนินการ	Production Path	ต้นทุน IC	หน่วย	On-Premise
การเสร็จสิ้นความมีชีวิตชีวาแบบแอคทีฟของใบหน้า	/v3/store/ekyc/face-active-liveness/finalize	1 IC	ต่อ 1 คำขอ	ติดต่อเรา