Điểm cuối API tối ưu hóa hình ảnh
Tài liệu kỹ thuật chính thức cho điểm cuối xử lý hình ảnh cốt lõi POST /v1/optimize.
Điểm cuối chính để tối ưu hóa, chuyển mã, thu nhỏ kích thước và điều chỉnh tỷ lệ hình ảnh là:
POST https://api.smallpict.app/v1/optimize
(Bí danh: POST https://api.smallpict.app/v1/convert)
Định dạng yêu cầu (Tải trọng JSON)
POST /v1/optimize HTTP/1.1Host: api.smallpict.appX-API-Key: sp_sdk_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0bX-Timestamp: 1716301234X-Signature: 3a9f8b2c4d6e8a0f1b3c5d7e9f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e5f7aContent-Type: application/jsonIdempotency-Key: c9b8a7f6-e5d4-4c3b-2a1f-0e9d8c7b6a5fLược đồ phần thân yêu cầu
{ "filename": "hero-banner.jpg", "mime_type": "image/jpeg", "filesize": 1654200, "options": { "format": "avif", "quality": 80, "max_dimension": 1600, "max_width": 1920, "max_height": 1080, "lossless": false, "strip_metadata": true }}| Trường dữ liệu | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
filename | string | Có | Tên tệp gốc của hình ảnh (ví dụ: banner.png) |
mime_type | string | Có | Kiểu MIME (ví dụ: image/jpeg, image/png, image/webp) |
filesize | integer | Có | Tổng kích thước tệp tính theo byte (phải > 0) |
options.format | string | Không | Định dạng đích: avif, webp, original / keep, jpg, png (Mặc định: webp) |
options.quality | integer | Không | Chất lượng nén từ 1 đến 100 (Mặc định: 80) |
options.max_dimension | integer | Không | Giới hạn tỷ lệ kích thước cạnh dài nhất tính theo pixel (ví dụ: 1600, 1920, 2048, 2560) |
options.max_width | integer | Không | Giới hạn chiều rộng tối đa tính theo pixel |
options.max_height | integer | Không | Giới hạn chiều cao tối đa tính theo pixel |
options.lossless | boolean | Không | Bật nén không suy giảm chất lượng từng điểm ảnh (Mặc định: false) |
options.strip_metadata | boolean | Không | Xóa siêu dữ liệu EXIF máy ảnh và hồ sơ màu sắc (Mặc định: true) |
Tham số biến đổi hình ảnh trực tiếp
Các tuyến biến đổi đám mây trực tiếp hỗ trợ tham số truy vấn URL để thay đổi kích thước nhanh chóng:
GET https://api.smallpict.app/v1/transform?url=...&format=webp&quality=80&max_dimension=1600
?format=avif|webp|original?quality=1..100?max_dimension=1600?max_width=1920?max_height=1080
Phản hồi từ máy chủ (200 OK)
Sau khi khởi tạo thành công, SmallPict trả về URL tải lên có chữ ký bảo mật và mã định danh theo dõi tác vụ:
{ "upload_url": "https://upload.smallpict.app/uploads/a1b2c3d4/hero-banner.jpg?signature=...", "job_id": "job-a1b2c3d4", "object_key": "uploads/a1b2c3d4/hero-banner.jpg", "status": "queued"}Tải dữ liệu ảnh lên upload_url bằng yêu cầu HTTP PUT, sau đó kiểm tra trạng thái tác vụ. Hãy dùng liên kết tải lên bảo mật đúng như giá trị được trả về: liên kết sẽ hết hạn sau thời gian ngắn và chỉ dùng được cho lần tải lên này.
Kiểm tra trạng thái tác vụ
Truy vấn tiến độ chuyển đổi bằng cách gọi:
GET https://api.smallpict.app/v1/optimize/status?job_id=job-a1b2c3d4
Phản hồi khi hoàn tất (200 OK)
{ "job_id": "job-a1b2c3d4", "status": "completed", "url": "https://cdn.smallpict.app/opt/hero-banner.avif", "format": "avif", "bytes_saved": 1456200, "savings_percentage": 88.03, "created_at": "2026-08-23T08:00:00Z", "updated_at": "2026-08-23T08:00:01Z"}