Upload by URL
Download ảnh từ URL bên ngoài và lưu vào hệ thống file
Endpoint
POST /v1/files/addimagefromurl
API này cho phép tải ảnh từ một URL bên ngoài, tự động download và lưu trữ vào hệ thống file nội bộ. Chỉ nhận ảnh JPG, PNG, GIF, WEBP; extension lưu theo nội dung ảnh thực tế (vd ảnh PNG lưu png).
Giới hạn: Nội dung tải về tối đa 10 MB (hoặc giới hạn ảnh của gói dịch vụ nếu nhỏ hơn, xem Giới hạn upload), tối đa 3 lần chuyển hướng (redirect), và phải là dữ liệu ảnh hợp lệ. URL trỏ tới địa chỉ mạng nội bộ / riêng tư bị từ chối. Request cũng bị từ chối nếu dung lượng đã dùng cộng ảnh mới vượt hạn mức gói dịch vụ (
error_quota_limit_exceed).
Lưu ý: Trường
descriptionsẽ tự động được gán bằng giá trịurlgốc. Trườngrandomcodeđược tạo bằng MD5 hash củaurl.
Content-Type
application/json
Request Body
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
url | string | Có | URL ảnh cần download. Chỉ nhận http:// hoặc https://, phải truy cập được công khai trên Internet |
title | string | Không | Tên file ảnh sau khi lưu (API không bắt buộc, nhưng nên gửi) |
company_id | int | Có | ID công ty |
creator_id | int | Có | ID người tạo |
object_type | int | Không | Loại đối tượng (không gửi sẽ lưu 0). Xem Object Schema |
object_id | int | Không | ID đối tượng liên kết (mặc định: 0) |
status | int | Không | Trạng thái. Không gửi sẽ lưu 0 — nên gửi 1 |
origin | string | Có | Nguồn gốc file. Xem Object Schema |
Ví dụ JSON
{
"url": "https://example.com/images/product-photo.jpg",
"title": "san-pham-moi.jpg",
"company_id": 1,
"creator_id": 10,
"object_type": 30,
"origin": "product",
"status": 1
}Response Schema
HTTP 201 - Created
Trả về File Object vừa tạo.
Ví dụ Response
{
"id": 5678,
"company_id": 1,
"creator_id": 10,
"directory_id": 0,
"object_type": 30,
"object_id": 0,
"md5_hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"file_path": "1/202603/5678-e99a18c428cb38d5f260853678922e03-1741234567.jpg",
"width": 800,
"height": 600,
"randomcode": "e99a18c428cb38d5f260853678922e03",
"title": "san-pham-moi.jpg",
"description": "https://example.com/images/product-photo.jpg",
"extension": "jpg",
"size_in_byte": 102400,
"origin": "product",
"customer_id": 0,
"status": 1,
"is_directory": 0,
"ip_address": "192.168.1.1",
"date_created": 1741234567,
"date_modified": 1741234567,
"url": "https://file.example.com/1/202603/5678-e99a18c428cb38d5f260853678922e03-1741234567.jpg"
}Lưu ý: Trường
descriptiontrong response chứa URL gốc của ảnh, vàrandomcodelà MD5 hash của URL đó.
Error Codes
Tất cả lỗi validate trả HTTP 422 với body {"error": ["error_..."]}.
| Mã lỗi | Mô tả |
|---|---|
error_company_id_required | ID công ty không được để trống |
error_company_id_notfound | ID công ty không tìm thấy |
error_user1_id_required | ID người tạo không được để trống |
error_user_id_notfound | ID người tạo không tìm thấy |
error_origin_is_required | origin không được để trống |
error_origin_is_invalid | origin không hợp lệ |
error_quota_limit_exceed | Dung lượng đã dùng cộng ảnh mới vượt hạn mức của gói dịch vụ |
error_url_is_required | url không được để trống |
error_url_is_invalid | url không đúng định dạng hoặc không phải http/https |
error_url_port_not_allowed | Cổng (port) trong URL không được phép |
error_url_host_invalid | Tên miền trong URL không hợp lệ |
error_url_host_unresolvable | Không phân giải được tên miền trong URL |
error_url_private_address | URL trỏ tới địa chỉ mạng nội bộ / riêng tư |
error_url_too_many_redirects | URL chuyển hướng quá 3 lần |
error_url_content_too_large | Nội dung tải về vượt giới hạn (detail.max_mb) |
error_url_fetch_failed | Tải URL thất bại (mã lỗi kèm HTTP status trả về từ URL, ví dụ error_url_fetch_failed: HTTP 404) |
error_can_not_get_image_content_from_url | Không thể tải nội dung ảnh từ URL (URL không truy cập được hoặc không chứa dữ liệu) |
error_url_content_is_not_image | Nội dung tải về không phải ảnh |
error_system_storage_unavailable | Kho lưu trữ file tạm thời không khả dụng (HTTP 503), thử lại sau |
error_system_file_can_not_copy | Lỗi hệ thống khi lưu file ảnh |
error_file_record_can_not_update | Lỗi hệ thống khi cập nhật record |