Phiên bản
Beta
Mô tả
Dịch vụ nhận ảnh trang phục dưới dạng URL, file nhị phân hoặc dữ liệu Base64 cùng vùng chọn hình chữ nhật, sau đó trả về danh sách nhãn tự động cho trang phục.
Yêu cầu đối với ảnh
- Định dạng: JPG, JPEG, PNG
- Độ phân giải: từ 48×48 đến 1280×1280 pixel
- Dung lượng: không vượt quá 2 MB
URL truy cập
https://api.example.com/v1/fashion/auto-tag
Phương thức HTTP
POST
Xác thực
API Key đã kích hoạt đều có thể gọi.
Tham số yêu cầu
| Bắt buộc | Tên tham số | Kiểu dữ liệu | Mô tả |
|---|---|---|---|
| Có | api_key | String | Khóa API dùng để xác thực. |
| Có | api_secret | String | Bí mật API. |
| Có | top | Int | Tọa độ y của góc trên bên trái vùng trang phục. |
| Có | left | Int | Tọa độ x của góc trên bên trái vùng trang phục. |
| Có | width | Int | Chiều rộng vùng chọn. |
| Có | height | Int | Chiều cao vùng chọn. |
| Có (chọn 1 trong 4) | image_url | String | URL trỏ đến ảnh. Nên upload trực tiếp qua file để tránh lỗi tải ảnh. |
| image_id | String | ID ảnh đã lưu trong hệ thống. | |
| image_file | File | File ảnh, upload bằng multipart/form-data. | |
| image_base64 | String | Dữ liệu ảnh mã hóa Base64. |
Thứ tự ưu tiên khi gửi nhiều nguồn ảnh
Nếu image_url, image_id, image_file, image_base64 đều được truyền, hệ thống sử dụng theo thứ tự: image_file → image_base64 → image_id → image_url.
Các trường trả về
| Trường | Kiểu | Ý nghĩa |
|---|---|---|
| request_id | String | Mã định danh duy nhất của mỗi yêu cầu. |
| tags | Array | Mảng nhãn nhận diện được. Nếu không có nhãn thì trả về mảng rỗng. |
| image_id | String | ID ảnh trong hệ thống. |
| elapsed | Int | Thời gian xử lý, đơn vị ms. |
| error_message | String | Chỉ xuất hiện khi có lỗi. |
Cấu trúc phần tử trong mảng tags
| Trường | Kiểu | Ý nghĩa |
|---|---|---|
| category | String | Nhóm nhãn, ví dụ: phong cách, màu sắc. |
| label | String | Giá trị nhãn c thể. |
| score | Float | Độ tin cậy, từ 0 đến 100, 3 chữ số thập phân. |
Ví dụ khi thành công
{
"image_id": "aB3x9LmQpZ==",
"request_id": "1620345678,feed1234-abcd-5678-90ef-1234567890ab",
"elapsed": 823,
"tags": [
{
"category": "style",
"label": "casual",
"score": 99.875
},
{
"category": "color",
"label": "orange",
"score": 95.105
}
]
}Ví dụ khi lỗi
{
"request_id": "1620345680,deadbeef-1234-5678-90ab-cdef01234567",
"elapsed": 5,
"error_message": "MISSING_ARGUMENTS: image_url, image_file, image_base64"
}Lỗi đặc thù của API
| Mã HTTP | Thông báo lỗi | Ý nghĩa |
|---|---|---|
| 400 | IMAGE_ERROR_UNSUPPORTED_FORMAT:<param> | Ảnh tại tham số <param> không thể phân tích, có thể file bị hng hoặc không phải ảnh. |
| 400 | INVALID_IMAGE_SIZE:<param> | Kích thước pixel ảnh không nằm trong giới hạn cho phép. |
| 400 | INVALID_IMAGE_URL | Không thể tải nh từ URL đã cung cấp. |
| 400 | IMAGE_FILE_TOO_LARGE | Dung lượng ảnh vượt quá 2 MB. |
| 412 | IMAGE_DOWNLOAD_TIMEOUT | Tải ảnh từ URL quá thời gian chờ. |
Lỗi chung
| Mã HTTP | Thông báo lỗi | Ý ngha |
|---|---|---|
| 401 | AUTHENTICATION_ERROR | api_key và api_secret không khớp. |
| 403 | AUTHORIZATION_ERROR:<reason> | API Key không có quyền truy cập. Lý do có thể là Denied by Client, Denied by Admin hoặc Insufficient Account Balance. |
| 403 | CONCURRENCY_LIMIT_EXCEEDED | Vượt quá giới hạn QPS của API Key. |
| 400 | MISSING_ARGUMENTS:<key> | Thiếu tham số bắt buộc. |
| 400 | BAD_ARGUMENTS:<key> | Tham số sai định dạng hoặc giá trị không hợp lệ. |
| 400 | COEXISTENCE_ARGUMENTS | Truyền đồng thời các tham số ràng buộc loại trừ. |
| 413 | Request Entity Too Large | Payload yêu cầu vượt quá 2 MB. Trả về dạng plain text. |
| 404 | API_NOT_FOUND | API không tn tại. |
| 500 | INTERNAL_ERROR | Lỗi máy chủ nội bộ. Thử lại hoặc liên hệ hỗ trợ kỹ thuật. |
Ví dụ gọi API
curl -X POST "https://api.example.com/v1/fashion/auto-tag" \
-F "api_key=<your_api_key>" \
-F "api_secret=<your_api_secret>" \
-F "top=<top>" \
-F "left=<left>" \
-F "width=<width>" \
-F "height=<height>" \
-F "image_file=@clothing.jpg"