Xác minh liveness khuôn mặt

Xác định xem một ảnh chân dung (portrait) có cho thấy một người thật trước camera hay không, thay vì một tấm ảnh in, một lần phát lại màn hình (screen replay), hay một hình thức tấn công giả mạo khác.

Endpoint

POST /v1/verify_face_liveness_sync
Content-Type: application/json

{
  "images": [
    {
      "id": "2dc863d6-1f68-4c82-8380-dd34e4ed7da0",
      "base64": "",
      "label": "portrait",
      "metadata": "{}"
    }
  ]
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
images	ImageData[]	Có	—	Một hoặc nhiều ảnh chân dung được chụp trong bước liveness.

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}

Ví dụ request

curl --location '<BASE_URL>/v1/verify_face_liveness_sync' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "images": [
      {
        "id": "ba056dc8-e702-4292-90b5-5c549c4db956",
        "base64": "",
        "label": "portrait",
        "metadata": "{}"
      }
    ]
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": {
    "request_id": "88b35583-76e0-4380-8a0b-a2d86436b6a5",
    "status": "success",
    "is_live": true,
    "score": 1,
    "images": [
      {
        "id": "ba056dc8-e702-4292-90b5-5c549c4db956",
        "is_live": true,
        "score": 0.9998822
      }
    ],
    "main_image_id": ""
  },
  "errors": []
}

Trường	Kiểu	Mô tả
data.request_id	string	Request ID; cung cấp cho CAKE Support khi cần kiểm tra log.
data.status	string	success hoặc failure.
data.is_live	bool	Kết quả liveness tổng thể trên mọi ảnh đã gửi.
data.score	float	Độ tin cậy liveness tổng thể, khoảng 0–1.
data.images	LivenessResult[]	Kết quả liveness theo từng ảnh.
data.main_image_id	string	ID của ảnh mà kết luận (verdict) tổng thể được rút ra, khi có một ảnh được chọn.

LivenessResult

Trường	Kiểu	Mô tả
id	string	ID của ảnh.
is_live	bool	Ảnh này có cho thấy một người thật hay không.
score	float	Độ tin cậy liveness cho ảnh này, khoảng 0–1.

WARNING

Hãy đánh giá liveness ở server từ response của API, không bao giờ từ một kết quả do client báo cáo. Một client di động bị xâm phạm có thể khai is_live: true; chỉ backend của bạn đọc một response đã được xác minh signature mới có thể được tin tưởng.

Lỗi

Mã	Thông báo
2001010	Không tìm thấy Access ID.
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.
5001000	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Mã	Mô tả
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.
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

• So sánh khuôn mặt — so khớp ảnh selfie sống với ảnh chân dung trên thẻ ID
• Định nghĩa kết luận — các kết luận is_live và incorrect_image_type trong ngữ cảnh