Face Matching System

Default: admin / admin

Dashboard

Registered Faces

Total Matches

Match Rate

Avg Confidence

📊 Faces by Department

🕔 System Health

API Docs Swagger UI

Engine InsightFace ArcFace

Model buffalo_l

Database SQLite

📋 Recent Match Logs

Time	Matched Name	Confidence	Result
Loading...

💳 บัตรประชาชน กรอกเองหรืออ่านบัตร

💳

คลิก "อ่านบัตร"

ไม่พบ SmartCard Agent — เปิด SmartCardAgent.exe ก่อน 📥 ดาวน์โหลด

📷 รูปถ่าย *

📷

Drag & drop หรือคลิกเลือกรูปภาพ

💾 ลงทะเบียนใบหน้า

เลขบัตรประชาชน / Citizen ID

รหัสพนักงาน * (ห้ามซ้ำ)

แผนก / Department

ประเภทพนักงาน / Employee Type

คำนำหน้า (TH)

ชื่อ (TH) *

นามสกุล (TH) *

Prefix (EN)

First Name (EN)

Last Name (EN)

วันเกิด / Birthday

เพศ / Sex

ที่อยู่ / Address

ตำบล / Tambol

อำเภอ / Amphur

จังหวัด / Province

วันออกบัตร / Issue Date

วันหมดอายุ / Expire Date

ผู้ออกบัตร / Issuer

🔎 Face Compare Test

เปรียบเทียบใบหน้า 2 รูปว่าเป็นคนเดียวกันหรือไม่ — ทดสอบประสิทธิภาพของ Face Matching Engine

📸 รูปที่ 1

📷

คลิกเพื่อเลือกรูป

📸 รูปที่ 2

📷

คลิกเพื่อเลือกรูป

📊 ผลการทดสอบ (session)

#	ผล	ความเชื่อมั่น	ประมวลผล	เวลา
ยังไม่มีการทดสอบ

🎥 Live Camera Scan

🎥

Click "Start Camera" to begin

📍 ไม่มี GPS

📸 Captured

📈 Result

Waiting for scan...

📋 Scan History

Time	Name	Matches	Result
No scans yet

Registered Faces

Photo	Name	Employee ID	Department	Registered	Actions
Loading...

👥 Sync Check — Attendance vs Face Registration

Total in Attendance

Registered Face

Not Registered

#	Citizen ID	ชื่อ (TH)	Name (EN)	Department	Action
Click Refresh to load

📍 Scan Logs — บันทึกการลงเวลา

ประวัติการแสกนหน้า พร้อม IP Address และ Location

ทั้งหมด

พบใบหน้า

ส่ง Attendance

ไม่พบใบหน้า

📋 รายการแสกน

เวลา	ชื่อ	รหัสพนักงาน	ประเภท	ความเชื่อมั่น	สถานะ	Attendance	IP Address	Location
Loading...

User Management

👥 Users

Username	Display Name	Role	Status	Created	Actions
Loading...

API Key Management

🔑 API Keys

Name	Key	Created By	Status	Last Used	Actions
Loading...

📚 Usage

Include the API key in your request header:

Header

X-API-Key: fm_your_api_key_here

Activity Logs

📋 Activity History

Time	Action	Detail	User	IP
Loading...

Settings

🔗

Attendance API Integration

Connect to external attendance system for time tracking

General

Status

ส่งลงเวลาจากการสแกนหน้า

Auto Scan (detect หน้าอัตโนมัติ)

API Endpoint URL

Authentication

Username

Password

API Documentation

REST API reference for integrating Face Matching into your application. Base URL: · Open Swagger UI

📚 Overview

This API uses InsightFace ArcFace (buffalo_l) for face recognition. It extracts 512-dimensional face embeddings and compares them using cosine similarity.

1 Register faces with photos via POST /api/faces/register

2 Verify 1:1 via POST /api/faces/match or scan 1:N via POST /api/faces/scan

3 Update face data via PUT /api/faces/update/{employee_id}

4 Monitor statistics via GET /api/faces/stats

Threshold: 0.4 Embedding: 512-dim Format: multipart/form-data

🔑 Authentication

ทุก endpoint ภายใต้ /api/faces/* ต้องยืนยันตัวตน — ใช้ได้ 2 แบบ (อย่างใดอย่างหนึ่ง)

1. API Key ThirdParty

HTTP Header

X-API-Key: fm_your_api_key_here

2. JWT Bearer ผู้ใช้เว็บ

HTTP Header

Authorization: Bearer <token จาก /api/admin/login>

สร้าง/ปิดใช้ API Key ได้ที่หน้า API Keys (admin เท่านั้น) — ถ้าไม่ส่ง header, key ถูกปิด, หรือ token หมดอายุ จะได้ 401 Unauthorized
ยกเว้น /api/health, /api/admin/login, /api/admin/captcha ที่เรียกได้โดยไม่ต้องยืนยันตัวตน

📄 Endpoints

👤 Faces — จัดการข้อมูลใบหน้า

POST /api/faces/register PUT /api/faces/update/{employee_id} GET /api/faces/ DELETE /api/faces/{face_id}

📷 Matching & Scan — เปรียบเทียบ/ลงเวลา

POST /api/faces/match POST /api/faces/scan GET /api/faces/scan-config

📋 Time Attendance — รายงานการลงเวลา

GET /api/faces/scan-logs GET /api/faces/timescan GET /api/faces/timescan-list

🔧 System — สถิติ/สถานะ

GET /api/faces/stats GET /api/health

POST /api/faces/register

Request multipart/form-data

Field	Type	Required	Description
`image`	file	Required	Face photo (JPG, PNG, BMP, WebP)
`employee_id`	string	Required	Unique employee identifier
`name`	string	Optional	Full name (display)
`citizen_id`	string	Optional	National ID / citizen ID
`department`	string	Optional	Department name
`employee_type`	string	Optional	ประเภทพนักงาน: `D` = รายวัน, `M` = ประจำ (บันทึกที่ master_employee ใน Attendance)
`th_prefix`	string	Optional	Thai prefix (นาย / นาง / นางสาว)
`th_firstname`	string	Optional	Thai first name
`th_lastname`	string	Optional	Thai last name
`en_prefix`	string	Optional	English prefix
`en_firstname`	string	Optional	English first name
`en_lastname`	string	Optional	English last name
`birthday`	string	Optional	Date of birth (ISO 8601)
`sex`	string	Optional	Sex code (1 = male, 2 = female)
`address`	string	Optional	Full address
`addr_tambol`	string	Optional	Sub-district (ตำบล)
`addr_amphur`	string	Optional	District (อำเภอ)
`addr_province`	string	Optional	Province (จังหวัด)
`issue`	string	Optional	Card issue date (ISO 8601)
`expire`	string	Optional	Card expiry date (ISO 8601)
`issuer`	string	Optional	Issuing authority

Response 200 OK

JSON

{
  "id": 1,
  "employee_id": "EMP001",
  "name": "John Doe",
  "department": "Engineering",
  "citizen_id": "1234567890123",
  "created_at": "2026-01-01T09:00:00"
}

Example

cURL

curl -X POST http://localhost:6100/api/faces/register \
  -H "X-API-Key: fm_your_api_key_here" \
  -F "image=@photo.jpg" \
  -F "employee_id=EMP001" \
  -F "name=สมชาย ใจดี" \
  -F "citizen_id=1234567890123" \
  -F "department=Engineering"

Python (requests)

import requests

url = "http://localhost:6100/api/faces/register"
headers = {"X-API-Key": "fm_your_api_key_here"}
files = {"image": open("photo.jpg", "rb")}
data = {
    "employee_id": "EMP001",
    "name": "สมชาย ใจดี",
    "citizen_id": "1234567890123",
    "department": "Engineering",
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

C# (HttpClient)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "fm_your_api_key_here");

using var form = new MultipartFormDataContent();
var imageBytes = File.ReadAllBytes("photo.jpg");
form.Add(new ByteArrayContent(imageBytes), "image", "photo.jpg");
form.Add(new StringContent("EMP001"), "employee_id");
form.Add(new StringContent("สมชาย ใจดี"), "name");
form.Add(new StringContent("1234567890123"), "citizen_id");
form.Add(new StringContent("Engineering"), "department");

var response = await client.PostAsync(
    "http://localhost:6100/api/faces/register", form);
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

JavaScript (fetch)

const formData = new FormData();
formData.append("image", fileInput.files[0]);
formData.append("employee_id", "EMP001");
formData.append("name", "สมชาย ใจดี");
formData.append("citizen_id", "1234567890123");
formData.append("department", "Engineering");

const response = await fetch(
    "http://localhost:6100/api/faces/register",
    {
        method: "POST",
        headers: { "X-API-Key": "fm_your_api_key_here" },
        body: formData,
    }
);
const data = await response.json();
console.log(data);

PUT /api/faces/update/{employee_id}

Update an existing face record by employee_id. All fields are optional — only provided fields will be updated.

Path Parameter

Parameter	Type	Description
`employee_id`	string	Employee ID of the registered face to update

Request multipart/form-data

Field	Type	Required	Description
`image`	file	Optional	New face photo — re-extracts embedding
`name`	string	Optional	Updated display name
`department`	string	Optional	Updated department

Example

cURL

curl -X PUT http://localhost:6100/api/faces/update/EMP001 \
  -H "X-API-Key: fm_your_api_key_here" \
  -F "name=สมชาย ใจดีมาก" \
  -F "image=@new_photo.jpg"

POST /api/faces/match

1:1 verification — compare a photo against one specific employee. Returns whether the face matches and the confidence score.

Request multipart/form-data

Field	Type	Required	Description
`image`	file	Required	Photo of face to verify
`employee_id`	string	Required	Employee ID to match against
`threshold`	float	Optional	Cosine similarity threshold (default: 0.4)

Response 200 OK

JSON

{
  "matched": true,
  "employee_id": "EMP001",
  "name": "สมชาย ใจดี",
  "confidence": 0.8712,
  "face_id": 1
}

Example

cURL

curl -X POST http://localhost:6100/api/faces/match \
  -H "X-API-Key: fm_your_api_key_here" \
  -F "image=@photo.jpg" \
  -F "employee_id=EMP001"

Python (requests)

import requests

url = "http://localhost:6100/api/faces/match"
headers = {"X-API-Key": "fm_your_api_key_here"}
files = {"image": open("photo.jpg", "rb")}
data = {"employee_id": "EMP001"}

response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()

if result["matched"]:
    print(f"✓ Verified: {result['name']} ({result['confidence']:.1%})")
else:
    print(f"✗ Not matched (score: {result['confidence']:.1%})")

C# (HttpClient)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "fm_your_api_key_here");

using var form = new MultipartFormDataContent();
var imageBytes = File.ReadAllBytes("photo.jpg");
form.Add(new ByteArrayContent(imageBytes), "image", "photo.jpg");
form.Add(new StringContent("EMP001"), "employee_id");

var response = await client.PostAsync(
    "http://localhost:6100/api/faces/match", form);
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

JavaScript (fetch)

const formData = new FormData();
formData.append("image", fileInput.files[0]);
formData.append("employee_id", "EMP001");

const response = await fetch(
    "http://localhost:6100/api/faces/match",
    {
        method: "POST",
        headers: { "X-API-Key": "fm_your_api_key_here" },
        body: formData,
    }
);
const result = await response.json();

if (result.matched) {
    console.log(`✓ ${result.name} — ${(result.confidence * 100).toFixed(1)}%`);
} else {
    console.log(`✗ Not matched (${(result.confidence * 100).toFixed(1)}%)`);
}

POST /api/faces/scan

1:N scan — match a photo against all registered faces. Returns every match above the threshold, sorted by confidence (highest first). เมื่อ match สำเร็จ (ไม่กำกวม) จะบันทึกลงเวลาเข้า AttendanceAPI ให้อัตโนมัติ (ควบคุมเปิด/ปิดที่หน้า Settings) โดยส่ง typeScan="FACE" และ employee_type ตามที่เลือก

Request multipart/form-data

Field	Type	Required	Description
`image`	file	Required	ภาพหน้าตรง (ใช้ match)
`pose_image`	file	Optional	ภาพหันหน้าตามทิศที่สุ่ม — เปิดใช้ pose challenge กันภาพถ่าย (ต้องส่งคู่กับ `pose_direction`)
`pose_direction`	string	Optional	`L` = หันซ้าย, `R` = หันขวา — ระบบตรวจทิศ + ยืนยันเป็นคนเดียวกันทั้ง 2 ภาพ ไม่ผ่าน = `spoof_detected`
`threshold`	float	Optional	Cosine similarity threshold (default: 0.4)
`scan_type`	string	Optional	ประเภทพนักงาน: `D` = รายวัน, `M` = ประจำ — ถ้าไม่ระบุ ใช้ค่าจากข้อมูลลงทะเบียน (master) อัตโนมัติ
`send_attendance`	boolean	Optional	ส่งลงเวลาเข้า AttendanceApi หรือไม่ (`true`/`false`) — สำหรับ ThirdParty; ถ้าไม่ระบุ ใช้ค่าจากหน้า Settings
`latitude`, `longitude`	float	Optional	พิกัด GPS ของจุดสแกน
`location_name`	string	Optional	ชื่อสถานที่

Response 200 OK

JSON

{
  "matches": [
    {
      "face_id": 1,
      "employee_id": "EMP001",
      "name": "สมชาย ใจดี",
      "department": "Engineering",
      "confidence": 0.9123
    }
  ],
  "no_face": false
}

When no face is detected: {"matches": [], "no_face": true}

Example

cURL

curl -X POST http://localhost:6100/api/faces/scan \
  -H "X-API-Key: fm_your_api_key_here" \
  -F "image=@photo.jpg"

Python (requests)

import requests

url = "http://localhost:6100/api/faces/scan"
headers = {"X-API-Key": "fm_your_api_key_here"}
files = {"image": open("photo.jpg", "rb")}

response = requests.post(url, headers=headers, files=files)
result = response.json()

if result["no_face"]:
    print("No face detected")
elif result["matches"]:
    top = result["matches"][0]
    print(f"Best match: {top['name']} ({top['confidence']:.1%})")
else:
    print("No match found")

C# (HttpClient)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "fm_your_api_key_here");

using var form = new MultipartFormDataContent();
var imageBytes = File.ReadAllBytes("photo.jpg");
form.Add(new ByteArrayContent(imageBytes), "image", "photo.jpg");

var response = await client.PostAsync(
    "http://localhost:6100/api/faces/scan", form);
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

JavaScript (fetch)

const formData = new FormData();
formData.append("image", fileInput.files[0]);

const response = await fetch(
    "http://localhost:6100/api/faces/scan",
    {
        method: "POST",
        headers: { "X-API-Key": "fm_your_api_key_here" },
        body: formData,
    }
);
const result = await response.json();

if (result.no_face) {
    console.log("No face detected");
} else if (result.matches.length > 0) {
    const top = result.matches[0];
    console.log(`Best match: ${top.name} (${(top.confidence * 100).toFixed(1)}%)`);
} else {
    console.log("No match found");
}

GET /api/faces/

List all registered faces, ordered by most recently added.

Response 200 OK — array

JSON

[
  {
    "id": 1,
    "employee_id": "EMP001",
    "name": "สมชาย ใจดี",
    "department": "Engineering",
    "citizen_id": "1234567890123",
    "created_at": "2026-01-01T09:00:00"
  }
]

DELETE /api/faces/{face_id}

Delete a registered face by its database ID. Returns 404 if the face does not exist.

Path Parameter

Parameter	Type	Description
`face_id`	integer	Face database ID (from register or list response)

Response 200 OK

JSON

{ "detail": "Deleted", "id": 1 }

Example

cURL

curl -X DELETE http://localhost:6100/api/faces/1 \
  -H "X-API-Key: fm_your_api_key_here"

GET /api/faces/stats

Get summary statistics and the last 20 match logs.

Response 200 OK

JSON

{
  "total_faces": 42,
  "total_matches": 1200,
  "successful_matches": 1150,
  "failed_matches": 50,
  "no_face_detected": 10,
  "match_rate": 95.83,
  "avg_confidence": 0.8521,
  "faces_by_department": {
    "Engineering": 20,
    "HR": 12
  },
  "recent_logs": [
    {
      "id": 1,
      "matched_name": "สมชาย ใจดี",
      "confidence": 0.8712,
      "result": "matched",
      "created_at": "2026-01-01T09:01:00"
    }
  ]
}

GET /api/health

Health check. Returns server status, uptime, memory, and CPU usage. No authentication required.

Response 200 OK

JSON

{
  "status": "healthy",
  "uptime_seconds": 3600.5,
  "memory_mb": 512.3,
  "cpu_percent": 12.4
}

GET /api/faces/scan-config

ค่าตั้งค่าฝั่ง client สำหรับหน้า Live Scan (อ่านได้ทุก role) เช่น เปิด/ปิด Auto Scan — ตั้งค่าที่หน้า Settings

Response 200 OK

JSON

{ "auto_scan": true }

GET /api/faces/scan-logs

ประวัติการสแกนล่าสุด (ทุกผลลัพธ์) เรียงจากใหม่ไปเก่า

Query Parameters

Field	Type	Required	Description
`limit`	int	Optional	จำนวนสูงสุด (default 200)
`result_filter`	string	Optional	กรองตามผล: matched / confirmed / unmatched / no_face

Response 200 OK

JSON

[
  {
    "id": 12, "employee_id": "11969", "name": "สุรสิทธิ์ บอช",
    "confidence": 0.87, "result": "matched", "scan_type": "D",
    "attendance_sent": true, "created_at": "2026-07-02T09:01:00"
  }
]

GET /api/faces/timescan

รายการลงเวลาของพนักงาน 1 คน ตามช่วงวันที่ (นับรวมวันเริ่ม-สิ้นสุด) เฉพาะผลที่เป็นการลงเวลาจริง (matched / confirmed)

Query Parameters

Field	Type	Required	Description
`employee_id`	string	Required	รหัสพนักงาน
`start_date`	string	Required	วันเริ่ม รูปแบบ `YYYY-MM-DD`
`end_date`	string	Required	วันสิ้นสุด รูปแบบ `YYYY-MM-DD`

Example

cURL

curl "$BASE/api/faces/timescan?employee_id=11969&start_date=2026-07-01&end_date=2026-07-31"

Response 200 OK

JSON

{
  "employee_id": "11969",
  "start_date": "2026-07-01", "end_date": "2026-07-31",
  "count": 2,
  "records": [ { "id": 12, "name": "...", "scan_type": "D", "created_at": "..." } ]
}

GET /api/faces/timescan-list

รายการลงเวลาของ ทุกคน ตามช่วงวันที่ (ระบุ employee_id เพื่อกรองเฉพาะคนได้)

Query Parameters

Field	Type	Required	Description
`start_date`	string	Required	วันเริ่ม `YYYY-MM-DD`
`end_date`	string	Required	วันสิ้นสุด `YYYY-MM-DD`
`employee_id`	string	Optional	กรองเฉพาะพนักงานคนนี้

Response 200 OK

JSON

{
  "start_date": "2026-07-01", "end_date": "2026-07-31",
  "count": 128,
  "records": [ /* ScanLog objects */ ]
}

⚠ Error Codes

Status	Meaning	Common Cause
`400`	Bad Request	No face detected in the uploaded image
`401`	Unauthorized	ไม่ได้ส่ง `X-API-Key` / `Authorization`, key ถูกปิด, หรือ token หมดอายุ
`403`	Forbidden	สิทธิ์ไม่พอ (เช่น endpoint ที่ต้องเป็น admin) หรือบัญชีถูกปิดใช้งาน
`404`	Not Found	Employee ID or Face ID does not exist
`409`	Conflict	Employee ID already registered
`422`	Validation Error	Missing required fields or wrong data type
`500`	Server Error	Internal error — check server logs