Phát hiện khuôn mặt

Phát hiện mọi khuôn mặt trong một ảnh và tùy chọn trả về embedding của nó — vector đại diện dùng để so sánh và tìm kiếm khuôn mặt.

Endpoint

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

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

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
image	ImageData	Có	—	Ảnh chứa khuôn mặt cần phát hiện.
return_embedding	bool	Không	false	Có trả về vector embedding của khuôn mặt hay không.

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}

Key type bên trong metadata đánh dấu ngữ cảnh so sánh:

Trường	Kiểu	Mô tả
1	int	So khớp ID với ID
2	int	So khớp ID với Selfie
3	int	So khớp Selfie với Selfie

Ví dụ request

curl -X POST \
  '<BASE_URL>/v1/detect_faces_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

{
  "data": {
    "request_id": "f77bf948-fce3-48f3-b61c-396e4cd9a89b",
    "status": "success",
    "image": {
      "id": "e5e32ef1-296e-4385-8f23-9eb7e6512800",
      "transformed_image_id": "",
      "faces": [
        {
          "id": "2cc3a440-3390-407a-914c-66a63e6eda33",
          "bounding_box": {
            "top": 402,
            "right": 257,
            "bottom": 568,
            "left": 123,
            "angle": 0
          },
          "embedding": [0.09560582041740417, -0.15577684342861176, -0.009643876925110817]
        }
      ]
    }
  },
  "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.image.id	string	ID của ảnh đã phân tích.
data.image.transformed_image_id	string	ID của ảnh đã biến đổi, chỉ có mặt khi ảnh đã được biến đổi.
data.image.faces	Face[]	Các khuôn mặt tìm thấy trong ảnh, lớn nhất trước.

Face

Trường	Kiểu	Mô tả
id	string	ID của khuôn mặt trong ảnh.
bounding_box	BoundingBox	Vị trí của khuôn mặt trong ảnh.
embedding	float[]	Vector embedding cho khuôn mặt. Chỉ được trả về khi return_embedding là true.

BoundingBox

Trường	Kiểu	Mô tả
top	int	Cạnh trên của khung.
right	int	Cạnh phải của khung.
bottom	int	Cạnh dưới của khung.
left	int	Cạnh trái của khung.
angle	int	Góc xoay của khung.

Các khuôn mặt được sắp xếp lớn nhất trước. Khi đầu vào có nhiều khuôn mặt, hãy dùng kết quả đầu tiên.

WARNING

Một embedding khuôn mặt là dữ liệu sinh trắc học. Hãy lưu trữ nó dưới cùng các kiểm soát như ảnh gốc, giữ nó ngoài log và các pipeline phân tích, và xóa nó khi mối quan hệ với khách hàng kết thúc.

Lỗi

Mã	Thông báo
2001002	Xảy ra lỗi không mong đợi trong quá trình xử lý request bên ngoài.
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.
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.
request_not_found_exception	Không tìm thấy request ID khi poll kết quả theo id.
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 1:1 giữa hai ảnh
• Lập chỉ mục khuôn mặt — đăng ký một khuôn mặt đã phát hiện vào một collection