So sánh khuôn mặt
So sánh các khuôn mặt trong hai ảnh và trả về liệu chúng có thuộc về cùng một người hay không — matched, unmatched hoặc unsure — cùng một điểm tương đồng (similarity score) từ 0 đến 1. Đây là kiểm tra 1:1 gắn một ảnh selfie với một ảnh chân dung trên thẻ ID (ID card).
Endpoint
http
POST /v1/compare_faces_sync
Content-Type: application/jsonjson
{
"image1": {
"id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74",
"base64": "",
"label": "portrait",
"metadata": "{}"
},
"image2": {
"id": "a4facba3-334b-41fb-97e3-4766cb70ae29",
"base64": "",
"label": "id_card.vn.national_id.front",
"metadata": "{}"
},
"type": ""
}Tham số:
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
image1 | ImageData | Có | — | Ảnh thứ nhất chứa một khuôn mặt để so sánh với image2. |
image2 | ImageData | Có | — | Ảnh thứ hai chứa một khuôn mặt để so sánh với image1. |
type | string | Không | default | Chỉ định loại so sánh khuôn mặt cho các trường hợp đặc biệt. Bỏ qua để dùng mặc định. |
ImageData
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
id | string | Không | — | ID của ảnh được trả về bởi Tải ảnh lên. |
base64 | string | Không | — | Văn bản dữ liệu ảnh mã hóa Base64. |
label | string | Không | — | Nhãn của ảnh, như mô tả trong Khuyến nghị sử dụng. |
metadata | string_json | Không | — | Chuỗi JSON key/value. Ví dụ: {"id":"<ID>","type":1} |
Chỉ cung cấp id hoặc base64 cho mỗi ảnh, không bao giờ cả hai.
Ví dụ request
bash
curl -X POST \
'<BASE_URL>/v1/compare_faces_sync' \
-H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
-H 'X-TV-Timestamp: <TIMESTAMP>' \
-H 'Content-Type: application/json' \
-d '{
"image1": { "id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74" },
"image2": { "id": "a4facba3-334b-41fb-97e3-4766cb70ae29" }
}'Response
json
{
"success": true,
"code": 0,
"message": "success",
"data": {
"status": "success",
"compare_faces": [
{
"face1_id": "abdba678-b680-4b62-bc4b-d9b8fb37e8e4",
"face2_id": "d43bf504-f1a3-4799-9bda-e5709ae7aa69",
"result": "matched",
"score": 0.95
},
{
"face1_id": "ae7a6cd2-4f5b-45b3-955f-844b1bc6d95a",
"face2_id": "d43bf504-f1a3-4799-9bda-e5709ae7aa69",
"result": "unmatched",
"score": 0.1
}
],
"image1": {
"id": "f3f6f8b5-2ac0-4734-a4b5-836c6c300b0b",
"transformed_image_id": "",
"faces": [
{
"id": "abdba678-b680-4b62-bc4b-d9b8fb37e8e4",
"bounding_box": { "top": 172, "right": 550, "bottom": 446, "left": 357, "angle": 0 }
}
]
},
"image2": {
"id": "639058a6-0631-4bfd-a718-bc72c2695daf",
"transformed_image_id": "",
"faces": [
{
"id": "d43bf504-f1a3-4799-9bda-e5709ae7aa69",
"bounding_box": { "top": 296, "right": 559, "bottom": 369, "left": 504, "angle": 0 }
}
]
},
"request_id": "b6e90aa2-a2d2-44bb-b4d5-cd4b92d0cdae"
},
"errors": []
}| Trường | Kiểu | Mô tả |
|---|---|---|
data.status | string | success hoặc failure. |
data.compare_faces | ComparePair[] | Mọi cặp khuôn mặt đã được đánh giá, cặp lớn nhất trước. |
data.image1 | ImageResult | Các khuôn mặt phát hiện được trong ảnh thứ nhất. |
data.image2 | ImageResult | Các khuôn mặt phát hiện được trong ảnh thứ hai. |
data.request_id | string | Request ID; cung cấp cho CAKE Support khi cần kiểm tra log. |
ComparePair
| Trường | Kiểu | Mô tả |
|---|---|---|
face1_id | string | ID của khuôn mặt trong image1. |
face2_id | string | ID của khuôn mặt trong image2. |
score | float | Khả năng hai khuôn mặt là cùng một người, khoảng 0–1. 0 nghĩa là không có sự tương đồng nào cả. |
result | string | matched, unmatched hoặc unsure. Xem Định nghĩa kết luận. |
ImageResult
| Trường | Kiểu | Mô tả |
|---|---|---|
id | string | ID của ảnh. |
transformed_image_id | string | ID của ảnh đã biến đổi, chỉ có mặt khi ảnh đã được biến đổi. |
faces | Face[] | Các khuôn mặt phát hiện được trong ảnh, mỗi khuôn mặt có id và bounding_box (top, right, bottom, left, angle). |
Cặp khuôn mặt lớn nhất được sắp xếp đầu tiên. Khi ảnh selfie chứa nhiều khuôn mặt, hãy dùng cặp đầu tiên trong compare_faces.
INFO
unsure là một kết quả thực sự, không phải một dạng matched mềm. Hãy chuyển các kết quả unsure sang xét duyệt thủ công thay vì gộp chúng vào một trong hai nhánh của một quyết định tự động.
Lỗi
| Mã | Thông báo |
|---|---|
2001003 | Ảnh gửi lên server không có khuôn mặt nào. |
2001010 | Không tìm thấy Access ID. |
2001026 | Các ảnh gửi lên server bị trùng lặp. |
401100 | Bạn không được phép thực hiện hành động này. |
4001000 | Tham số đầu vào vi phạm một ràng buộc. |
4001001 | Header X-TV-Timestamp đã hết hạn, cần một cái mới hơn. |
4041000 | Không tìm thấy image ID trong DB. |
4131000 | Kích thước ảnh đầu vào vượt quá giới hạn cho phép (15MB). |
4151000 | Định dạng ảnh được cung cấp không được hỗ trợ (JPG/PNG). |
4291000 | Số lượng request vượt quá giới hạn throughput của bạn. |
5001000 | Xảy ra lỗi không mong đợi trong quá trình xử lý request. |
| Mã | Mô tả |
|---|---|
access_id_not_found | Không tìm thấy Access ID. |
access_denied_exception | Bạn không được phép thực hiện hành động này. |
invalid_parameter_exception | Tham số đầu vào vi phạm một ràng buộc. |
request_time_too_skewed | Header X-TV-Timestamp đã hết hạn, cần một cái mới hơn. |
image_not_found_exception | Không tìm thấy image ID trong DB. |
image_too_large_exception | Kích thước ảnh đầu vào vượt quá giới hạn cho phép (15MB). |
invalid_image_format_exception | Định dạng ảnh được cung cấp không được hỗ trợ (JPG/PNG). |
duplicated_image | Các ảnh gửi lên server bị trùng lặp. |
image_has_no_faces | Ảnh gửi lên server không có khuôn mặt nào. |
rate_limit_exception | Số lượng request vượt quá giới hạn throughput của bạn. |
internal_server_error | Xảy ra lỗi không mong đợi trong quá trình xử lý request. |
Bước tiếp theo
- Tìm kiếm khuôn mặt — tìm kiếm 1:N trên một collection thay vì một cặp đơn lẻ
- Định nghĩa kết luận — ý nghĩa của
matched,unmatchedvàunsure