Dịch vụ AI

Cách tích hợp so sánh khuôn mặt

Gửi hai ảnh khuôn mặt và nhận về kết quả có phải cùng một người không, kèm điểm số độ khớp.

Request

Gửi multipart/form-data với cả hai ảnh:

Trường	Ý nghĩa
`sourceImage`	sourceImage là bắt buộc. JPEG hoặc PNG, tối đa 5 MB. Khuôn mặt dùng làm tham chiếu.
`targetImage`	targetImage là bắt buộc. JPEG hoặc PNG, tối đa 5 MB. Được so sánh với mọi khuôn mặt tìm thấy trong ảnh này.

Ví dụ

curl -X POST https://core.roammoon.com/v1/ai/face-comparison/compare \
  -H "X-API-Key: rm_live_YOUR_KEY" \
  -F "sourceImage=@id-card.jpg" \
  -F "targetImage=@selfie.jpg"

Response

Trả về hai khuôn mặt có phải cùng một người không:

JSON

{
  "isSamePerson": true,
  "similarity": 97.52
}

Khi không tìm thấy khớp

similarity là null chứ không phải 0, vì không có gì để tính điểm, dù là do ảnh đích không có khuôn mặt khớp hay hoàn toàn không có khuôn mặt nào. isSamePerson đều là false trong cả hai trường hợp.

JSON

{
  "isSamePerson": false,
  "similarity": null
}

Các trường quan trọng

Trường	Ý nghĩa
`isSamePerson`	true khi có ít nhất một khuôn mặt trong targetImage khớp với sourceImage.
`similarity`	Điểm khớp cao nhất tìm được, 0–100. null khi isSamePerson là false.

Tính phí

Chỉ khi so sánh thành công và trả về kết quả thì mới bị trừ 10 credit. Mọi trường hợp thất bại đều được hoàn lại, dù là ảnh bị từ chối hay chính dịch vụ không xử lý được.

Chính sách tính phí là charge-on-success: credit được giữ chỗ khi tiếp nhận request và chỉ thực sự trừ khi xử lý thành công. Thất bại thì hoàn lại.

Mẹo đạt độ chính xác cao

Ảnh đủ sáng, chụp thẳng mặt, khuôn mặt chiếm phần đáng kể khung hình. Góc chụp quá lệch hoặc bóng đổ nặng là nguyên nhân phổ biến nhất khiến không khớp được.
sourceImage nên chỉ chứa đúng khuôn mặt cần kiểm tra, vì nếu có nhiều khuôn mặt, hệ thống chỉ dùng khuôn mặt lớn nhất.
Đây là so sánh xác suất, không phải xác thực danh tính. Hãy coi kết quả độ tin cậy thấp là chưa kết luận được chứ không phải chắc chắn không khớp, và luôn có con người xem xét lại với những quyết định ảnh hưởng đến quyền lợi hay quyền truy cập của một người.

Lỗi

Mọi lỗi đều dùng chung một cấu trúc. Hãy xử lý theo trường code, không phải theo message, vì message có thể thay đổi.

JSON

{
  "error": {
    "code": "NO_FACE_DETECTED",
    "message": "No face was detected in one of the images."
  }
}

HTTP	Mã lỗi	Nên làm gì
401	`API_KEY_REQUIRED`	Thiếu header X-API-Key.
401	`API_KEY_INVALID`	Key sai, đã bị vô hiệu hóa hoặc hết hạn. Kiểm tra lại hoặc tạo key mới.
403	`API_KEY_FORBIDDEN`	Key không có quyền dùng dịch vụ này.
400	`INVALID_FACE_COMPARISON_REQUEST`	Trường sourceImage hoặc targetImage bị thiếu hoặc rỗng. Không bị trừ credit.
400	`NO_FACE_DETECTED`	Không tìm thấy khuôn mặt nào trong một trong hai ảnh. Không bị trừ credit.
402	`CREDIT_LIMIT_EXCEEDED`	Hết credit trong chu kỳ. Nâng gói hoặc chờ sang chu kỳ mới.
413	`IMAGE_TOO_LARGE`	Ảnh vượt quá 5 MB. Hãy nén hoặc thu nhỏ ảnh.
415	`UNSUPPORTED_IMAGE_TYPE`	Chỉ hỗ trợ JPEG và PNG.
429	`RATE_LIMIT_EXCEEDED`	Vượt giới hạn request mỗi phút.
429	`FACE_COMPARISON_SERVICE_BUSY`	Dịch vụ so sánh đang quá tải. Thử lại sau vài giây.
502	`FACE_COMPARISON_UPSTREAM_ERROR`	Mô hình so sánh khuôn mặt không xử lý được request. Có thể thử lại.
503	`FACE_COMPARISON_SERVICE_MISCONFIGURED`	Dịch vụ chưa được cấu hình đúng. Đây là lỗi phía vận hành, thử lại cũng không giải quyết được.

Thử lại an toàn

429 và 502 có thể thử lại, dùng exponential backoff. Các lỗi khác trả về cùng kết quả khi thử lại. Chỉ lần so sánh thành công mới bị trừ phí, nên thử lại sau khi thất bại không tốn thêm gì. Ngoại lệ là timeout mạng: nếu lần gọi đầu thực ra đã thành công, lần thử lại sẽ tính phí như một lệnh gọi thứ hai.

Tiếp theo: Tham chiếu API →