Tải ảnh lên

Tải một ảnh lên FaceAuthen và trả về một image_id. Đây là bước đầu tiên bắt buộc cho mọi service khác — mọi API downstream đều nhận một image_id thay vì dữ liệu ảnh thô.

Endpoint

http

POST /v1/images
Content-Type: multipart/form-data

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`file`	file	Có	—	File ảnh cần tải lên. JPG hoặc PNG, tối đa 15MB.
`label`	string	Có	—	Nhãn của ảnh. Phải là một trong các giá trị trong Khuyến nghị sử dụng.
`metadata`	string_json	Không	`{}`	Chuỗi JSON của các cặp key/value. Key là string; value là string, int, float hoặc bool. Ví dụ: `{"id":"<ID>","type":1}`

Trả về: UploadImageResponse

Dùng portrait cho một ảnh selfie chụp bằng camera và portrait_nfc cho một ảnh chân dung đọc từ chip NFC.

Ví dụ request

bash

curl -X POST \
  '<BASE_URL>/v1/images' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -F 'file=@"images/portrait.jpg"' \
  -F 'label="portrait"'

Signature của thiết bị (request từ SDK)

Khi Mobile SDK tải ảnh lên bằng token giao dịch (Authorization: Bearer …), trên tenant đã bật kiểm tra signature của thiết bị, SDK còn gửi Device-Id, X-Device-Key-Id và X-Device-Signature, được ký trên body multipart thô đúng như khi gửi. Khóa ký (signing credential) mà X-Device-Key-Id chỉ tới phải ở trạng thái ACTIVE và được đăng ký cho cùng Device-Id; nếu không, request bị từ chối với access_denied_exception. Xem Ký request.

Response

json

{
  "data": {
    "image_id": "20b457d2-cf11-4c2b-a491-8137ae6b0bc8"
  },
  "errors": [],
  "success": true,
  "code": 0,
  "message": "Success"
}

Trường	Kiểu	Mô tả
`data.image_id`	string	UUID của ảnh đã tải lên trong StoreDB. Truyền giá trị này cho mọi API khác.
`errors`	array	Chi tiết từng lỗi. Rỗng khi thành công.
`success`	bool	Cuộc gọi có thành công hay không.
`code`	int	status code dạng số — `0` khi thành công.
`message`	string	Thông báo trạng thái.

Khi thành công, HTTP status là 200. Chỉ riêng HTTP 200 là chưa đủ — hãy kiểm tra success và data.status trước khi coi việc tải lên đã hoàn tất.

Lỗi

Khi success là false, một trong các mã số sau sẽ được trả về:

Mã	Thông báo
`2001010`	Không tìm thấy Access ID.
`2001014`	Vượt giới hạn tốc độ đăng ký.
`2001015`	Vượt giới hạn brute-force khi đăng ký.
`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.
`4041001`	Không tìm thấy người dùng.
`4091000`	`cus_user_id` đã được đăng ký.
`4291000`	Số lượng request vượt quá giới hạn throughput của bạn.
`5001000`	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Mảng errors mang một hoặc nhiều mã lỗi chi tiết:

Mã	Mô tả
`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.
`access_denied_exception`	Bạn không được phép thực hiện hành động này.
`image_not_found_exception`	Không tìm thấy image ID trong DB.
`image_too_large_exception`	Kích thước ảnh đầu vào vượt quá giới hạn cho phép (15MB).
`invalid_image_format_exception`	Định dạng ảnh được cung cấp không được hỗ trợ (JPG/PNG).
`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

Khuyến nghị sử dụng — toàn bộ danh sách nhãn
Đăng ký khuôn mặt — đăng ký bằng các image ID được trả về ở đây
Xác minh Face Authen — xác thực bằng các image ID được trả về ở đây

Tải ảnh lên ​

Endpoint ​

Ví dụ request ​

Signature của thiết bị (request từ SDK) ​

Response ​

Lỗi ​