Tìm kiếm khuôn mặt

Nhận một ảnh chứa khuôn mặt và truy xuất các khuôn mặt tương đồng từ một collection, mỗi khuôn mặt kèm một điểm tương đồng (similarity score) và metadata đi kèm của nó. Đây là kiểm tra 1:N cho các tài khoản trùng lặp và trường hợp blocklist.

Endpoint

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

{
  "image": {
    "id": "de02a784-a7bc-43a7-96ba-226420b18960",
    "base64": "",
    "label": "portrait",
    "metadata": "{}"
  },
  "collection": "default"
}

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 tìm kiếm.
collection	string	Không	collection mặc định	Collection để tìm kiếm. Phân biệt hoa thườ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}

Ví dụ request

curl --location '<BASE_URL>/v1/search_faces_sync' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "collection": "default",
    "image": {
      "id": "de02a784-a7bc-43a7-96ba-226420b18960",
      "base64": "",
      "label": "portrait",
      "metadata": "{}"
    }
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": {
    "request_id": "81a3cf2b-bdbb-4208-b304-3a234cf21b9c",
    "status": "success",
    "image": {
      "id": "de02a784-a7bc-43a7-96ba-226420b18960",
      "faces": [
        {
          "id": "73644de1-d727-4bce-9e8c-f5453658556a",
          "bounding_box": { "top": 154, "right": 408, "bottom": 335, "left": 173 }
        }
      ]
    },
    "faces": [
      [
        {
          "id": "452476f8-1a88-4082-a777-21250f3dbdf4",
          "image_id": "6b5b2984-a834-4c30-b6c0-c3c0720b51af",
          "score": 1
        }
      ]
    ]
  },
  "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 truy vấn.
data.image.faces	Face[]	Các khuôn mặt phát hiện được trong ảnh truy vấn, mỗi khuôn mặt có id và bounding_box.
data.faces	SearchMatch[][]	Một mảng kết quả trùng khớp cho mỗi khuôn mặt truy vấn được phát hiện, theo cùng thứ tự với data.image.faces.

SearchMatch

Trường	Kiểu	Mô tả
id	string	ID của khuôn mặt trùng khớp trong collection.
image_id	string	ID của ảnh đã lập chỉ mục mà khuôn mặt trùng khớp thuộc về.
score	float	Độ tương đồng giữa khuôn mặt truy vấn và khuôn mặt trùng khớp, khoảng 0–1.

data.faces là một mảng của các mảng — hãy truy cập theo chỉ số của khuôn mặt truy vấn, sau đó đọc các kết quả trùng khớp cho khuôn mặt đó.

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.
request_not_found_exception	Không tìm thấy request ID khi poll kết quả theo id.
request_timeout_exception	Request mất quá nhiều thời gian để xử lý.
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

• Lập chỉ mục khuôn mặt — điền dữ liệu vào collection mà API này tìm kiếm
• So sánh khuôn mặt — so sánh 1:1 khi bạn đã biết cả hai ảnh