🙂 ระบบตรวจสอบความมีชีวิตของใบหน้าแบบแอคทีฟ Face Active Liveness Detection

1 ICต่อคำขอ🔏 ผลตัดสินลงลายเซ็น HMAC

v1.0 Active ก.ค. 2026 POST /v3/store/ekyc/face-active-liveness/finalize

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

ทดลองใช้ SDK (กล้องสด)

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

Loading live demo…

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

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

1. ล็อกใบหน้า — SDK จะค้นหาใบหน้าตรงเพียงหนึ่งใบหน้า และรอจนกว่าใบหน้าจะนิ่งและอยู่ในกรอบอย่างเหมาะสม
2. ท่าทางแบบสุ่ม — SDK จะสุ่มเลือกท่าทางที่แตกต่างกัน 3 ท่าจาก กะพริบตา / หันซ้าย / หันขวา / ยิ้ม และตรวจสอบแต่ละท่าบนอุปกรณ์โดยใช้จุดสังเกตใบหน้า (face landmarks) แบบเรียลไทม์ (เช่น การกะพริบตาต้องเป็นการเปลี่ยนจากหลับตาแล้วลืมตา ดังนั้นรูปถ่ายที่พิมพ์ออกมาเป็นภาพหลับตาจึงไม่สามารถผ่านได้)
3. การเลือกเฟรมที่ดีที่สุด — ตลอดทั้งเซสชัน SDK จะให้คะแนนทุกเฟรมที่คมชัด เป็นภาพหน้าตรง และลืมตา แล้วเก็บภาพเซลฟีที่ดีที่สุดไว้ (ความคมชัด × ขนาดใบหน้า)
4. สรุปผล (Finalize) — SDK จะส่งภาพเซลฟีที่ดีที่สุดพร้อมบันทึกการทำท่าทาง (challenge log) ที่มีการประทับเวลา ไปยัง POST /v3/store/ekyc/face-active-liveness/finalize
5. การตรวจสอบซ้ำฝั่งเซิร์ฟเวอร์ — เซิร์ฟเวอร์จะตรวจสอบความถูกต้องของบันทึกการทำท่าทาง (ประเภทท่าทางต้องอยู่ในรายการที่อนุญาต มีท่าทางอย่างน้อย 2 ท่า ผ่านทั้งหมด การประทับเวลาต้องเพิ่มขึ้นอย่างเคร่งครัด ระยะเวลาต่อท่าทางสมเหตุสมผล และเซสชันยังใหม่อยู่) และตรวจสอบภาพเซลฟีซ้ำอย่างอิสระด้วยเอนจินตรวจสอบความมีชีวิตแบบพาสซีฟที่ได้รับการรับรอง iBeta Level 1 ของเรา
6. ผลตัดสินที่ลงลายเซ็น — เซิร์ฟเวอร์จะส่งคืนผลตัดสินที่ลงลายเซ็นด้วย HMAC-SHA256 โดยผลตัดสินจะฝังค่าแฮช SHA-256 ของภาพเซลฟี ซึ่งผูกการตัดสินเข้ากับข้อมูลไบต์ของภาพนั้นโดยตรง แบ็กเอนด์ของคุณจะตรวจสอบลายเซ็นด้วยรหัสลับที่ใช้ร่วมกัน (shared secret) ที่ออกโดย iApp และเชื่อถือเฉพาะผลตัดสินที่ลงลายเซ็นเท่านั้น — ไม่ใช่คำกล่าวอ้างจากฝั่งไคลเอนต์เอง

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

3. คุณสมบัติหลัก

   • ท่าทางกะพริบตา หันซ้าย หันขวา และยิ้ม
   • ป้องกันการโกง: เซสชันจะเริ่มใหม่เมื่อใบหน้าหายไป มีหลายใบหน้า หรือมีการสลับตัวบุคคล
   • การเลือกภาพเซลฟีจากเฟรมที่ดีที่สุด (ให้คะแนนตามความคมชัด)
   • ผลตัดสินลงลายเซ็น HMAC-SHA256 ที่ผูกกับค่าแฮช SHA-256 ของภาพเซลฟี

4. ความปลอดภัยและการปฏิบัติตามข้อกำหนด

   • ปฏิบัติตาม GDPR และ PDPA
   • ไม่มีการเก็บรักษาข้อมูลรูปภาพหลังจากการประมวลผล
   • ผลตัดสินที่ลงลายเซ็นสามารถตรวจสอบแบบออฟไลน์บนแบ็กเอนด์ของคุณได้

วิธีรับ API Key?

กรุณาไปที่หน้า การจัดการ API Key เพื่อดู API Key ที่มีอยู่ของคุณ หรือขอใหม่

ตัวอย่าง

คำขอ Face Active Liveness Finalize:

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 }
      ]
    }'

การตอบกลับ Face Active Liveness Finalize:

{
  "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 ซ้ำจาก canonical JSON ของ verdict (เรียงลำดับคีย์ของออบเจ็กต์ทั้งหมดแบบเรียกซ้ำ ไม่มีช่องว่างที่ไม่จำเป็น และเข้ารหัสแบบ UTF-8) โดยใช้รหัสลับที่ใช้ร่วมกันซึ่งออกโดย iApp แล้วเปรียบเทียบแบบ constant time:

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

คุณสมบัติและความสามารถ

คุณสมบัติหลัก

• ลำดับท่าทางแบบสุ่มบนอุปกรณ์ (กะพริบตา หันซ้าย หันขวา ยิ้ม) ในทุกเซสชัน — ออกแบบมาให้ทนทานต่อการโจมตีแบบเล่นซ้ำ (replay)
• การตรวจสอบภาพเซลฟีซ้ำฝั่งเซิร์ฟเวอร์ด้วยเอนจินตรวจสอบความมีชีวิตแบบพาสซีฟที่ได้รับการรับรอง iBeta Level 1 ของเรา
• ผลตัดสินลงลายเซ็น HMAC-SHA256 ที่ผูกการตัดสินเข้ากับข้อมูลไบต์ของภาพเซลฟีผ่าน selfie_sha256
• การตรวจสอบบันทึกการทำท่าทางอย่างเข้มงวด: ประเภทต้องอยู่ในรายการที่อนุญาต มีท่าทางอย่างน้อย 2 ท่า การประทับเวลาเพิ่มขึ้นอย่างเคร่งครัด ระยะเวลาต่อท่าทาง 300 ms–30 s ความยาวเซสชัน ≤ 120 s และความใหม่ภายใน 5 นาทีจากเวลาเซิร์ฟเวอร์
• SDK ฝั่งไคลเอนต์แบบโอเพนซอร์สฟรีสำหรับเว็บ, Flutter, iOS/Android เนทีฟ และ React Native พร้อม UI ที่ปรับแต่งธีมได้เต็มรูปแบบในภาษาอังกฤษ ไทย และจีน

ช่องที่รองรับ

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

API Endpoints

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

ข้อมูลอ้างอิง API

Face Active Liveness Endpoints

1. Face Active Liveness Finalize

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

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

SDK คือไคลเอนต์ที่ออกแบบมาให้ใช้งาน

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

---

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

Headers

ชื่อ	ประเภท	คำอธิบาย
apikey	String	คีย์ API ของคุณเพื่อเรียกใช้ API นี้

Request Body (multipart/form-data)

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

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

ชื่อ	ประเภท	คำอธิบาย
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	ค่า HMAC-SHA256 แบบฐานสิบหกของ canonical JSON ของ verdict โดยใช้รหัสลับที่ใช้ร่วมกันของคุณ
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	คีย์ API ไม่ถูกต้อง	ไม่มีหรือมี header apikey ที่ไม่ถูกต้อง (gateway)
402	เครดิตไม่เพียงพอ	เติมเครดิตได้ที่ Credits (gateway)
413	ไฟล์มีขนาดใหญ่เกินไป	ภาพเซลฟีมีขนาดเกินขีดจำกัด 10MB
502	UPSTREAM_UNAVAILABLE	เอนจินตรวจสอบความมีชีวิตไม่พร้อมใช้งานชั่วคราว — กรุณาลองใหม่ภายหลัง

การคิดค่าบริการ

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

ราคา

การดำเนินการ	Production Path	ต้นทุน IC	หน่วย	On-Premise
Face Active Liveness Finalize	/v3/store/ekyc/face-active-liveness/finalize	1 IC	ต่อ 1 คำขอ	ติดต่อเรา