Xác minh sanity khuôn mặt

Kiểm tra chất lượng của một ảnh chân dung (portrait) (selfie) và trả về một kết luận (verdict) như good, not_qualified hoặc occluded_face. Hãy chạy bước này trước So sánh khuôn mặt hoặc Xác minh liveness khuôn mặt — một ảnh selfie kém sẽ tạo ra kết quả so khớp và liveness không đáng tin cậy.

Endpoint

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

{
  "image": {
    "id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74",
    "base64": "",
    "label": "portrait",
    "metadata": "{}"
  },
  "selfie_type": ""
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
image	ImageData	Có	—	Ảnh chân dung. Khi dùng TS SDK, hãy truyền frame chính diện cuối cùng.
selfie_type	string	Không	—	Nêu đặc điểm của một khuôn mặt khuyết tật, ví dụ một mắt bị khuyết tật, để kiểm tra điều chỉnh cho phù hợp.

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, không bao giờ cả hai.

Ví dụ request

curl -X POST \
  '<BASE_URL>/v1/verify_portrait_sanity_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": {
      "id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74"
    }
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": {
    "status": "success",
    "image": {
      "id": "4368143d-9066-4f3d-ab22-4e0b6dd9b274"
    },
    "portrait_sanity": {
      "score": 1,
      "verdict": "good"
    },
    "request_id": "f77bf948-fce3-48f3-b61c-396e4cd9a89b"
  },
  "errors": []
}

Trường	Kiểu	Mô tả
data.status	string	success hoặc failure.
data.image.id	string	ID của ảnh đã phân tích.
data.portrait_sanity.verdict	string	good, hoặc vấn đề đầu tiên phát hiện được. Xem Định nghĩa kết luận.
data.portrait_sanity.score	float	Độ tin cậy của kết luận, khoảng 0–1.
data.request_id	string	Request ID; cung cấp cho CAKE Support khi cần kiểm tra log.

Chỉ vấn đề đầu tiên phát hiện được sẽ được trả về. Hãy chuyển nó thành một thông báo chụp lại chung chung — không bao giờ hiển thị verdict hay score cho người dùng cuối.

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

• Định nghĩa kết luận — ý nghĩa của từng kết luận sanity khuôn mặt
• Xác minh liveness khuôn mặt — xác nhận một người thật, không phải một lần phát lại