Lập chỉ mục khuôn mặt

Lập chỉ mục khuôn mặt trong một ảnh và thêm nó vào một collection, xây dựng tập hợp có thể tìm kiếm mà Tìm kiếm khuôn mặt sẽ truy vấn để tìm các trường hợp trùng lặp và blocklist.

Endpoint

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

{
  "image": {
    "id": "a4facba3-334b-41fb-97e3-4766cb70ae29",
    "base64": "",
    "label": "portrait",
    "metadata": "{}"
  },
  "enable_update_metadata": false,
  "collection": "default",
  "type": 0
}

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 lập chỉ mục. Khi dùng TS SDK, hãy truyền frame chính diện cuối cùng.
enable_update_metadata	bool	Không	false	Cho phép image.metadata được cập nhật trên một ảnh đã được lập chỉ mục.
collection	string	Không	collection mặc định	Collection để lập chỉ mục khuôn mặt vào. Phân biệt hoa thường.
type	int	Không	—	Loại collection.

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 -X POST \
  '<BASE_URL>/v1/index_faces_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": {
      "id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
    }
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": {
    "status": "success",
    "image": {
      "id": "a4facba3-334b-41fb-97e3-4766cb70ae29",
      "transformed_image_id": ""
    },
    "request_id": "dfdef016-e89b-4da4-ae17-5844f909c947"
  },
  "errors": []
}

Trường	Kiểu	Mô tả
data.status	string	success hoặc failure.
data.image.id	string	ID của ảnh đã lập chỉ mục.
data.image.transformed_image_id	string	ID của ảnh đã biến đổi, chỉ có mặt khi ảnh đã được biến đổi.
data.request_id	string	Request ID; cung cấp cho CAKE Support khi cần kiểm tra log.

WARNING

Việc lập chỉ mục đăng ký một template sinh trắc học tồn tại cho đến khi bạn xóa nó. Chỉ lập chỉ mục sau khi khách hàng đã đồng ý và lần onboarding đã được phê duyệt, và dùng Xóa khuôn mặt để đáp ứng các yêu cầu xóa dữ liệu.

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

• Tìm kiếm khuôn mặt — truy vấn collection bạn vừa thêm vào
• Xóa khuôn mặt — gỡ một khuôn mặt đã lập chỉ mục