Bảng màu ảnh & BlurHash API

Lấy màu chủ đạo của ảnh PNG, JPEG, SVG kèm tỷ lệ, màu trung bình, màu chữ dễ đọc, và chuỗi BlurHash / ThumbHash làm ảnh giữ chỗ.

GETPOSThttps://apibox.io.vn/v1/image-palette

Tải ảnh lên (PNG, JPEG hoặc SVG, qua file multipart, body thô hoặc file_base64) hoặc đưa url. Ảnh được thu nhỏ còn 128 px, bỏ qua điểm ảnh trong suốt hơn một nửa, rồi gom màu bằng thuật toán median cut và tinh chỉnh vài vòng k-means. Kết quả có tối đa 16 màu (colors, mặc định 6) xếp theo tỷ lệ, mỗi màu có mã hex, RGB, HSL, tỷ lệ diện tích trong ảnh, độ tương phản WCAG với nền trắng và đen, và màu chữ dễ đọc nhất khi đặt lên màu đó; kèm màu trung bình, màu chủ đạo và is_dark (ảnh tối hay sáng).

Để làm ảnh giữ chỗ khi tải chậm (lazy-load), API tính thêm BlurHash (thư viện blurhash, MIT; 4×3 thành phần với ảnh ngang, 3×4 với ảnh dọc, hoặc đặt blurhash_x / blurhash_y 1–9) và ThumbHash (thư viện thumbhash, MIT; dạng base64), mỗi loại có sẵn một ảnh PNG rất nhỏ dạng data URI để gắn thẳng vào src hoặc nền CSS trong lúc chờ ảnh thật.

Ảnh tối đa 25 megapixel; không lưu lại dữ liệu.

Tham số

TênVị tríKiểuBắt buộcMặc định
filebodyfilekhôngẢnh (PNG, JPEG hoặc SVG): multipart, body thô hoặc file_base64.
urlquery|bodystringkhôngURL công khai của ảnh (tối đa 15 MB) thay cho file.
colorsquery|bodynumberkhông6Số màu trong bảng màu (1–16).
blurhash_xquery|bodynumberkhông4Số thành phần ngang của BlurHash (1–9; ảnh dọc mặc định 3).
blurhash_yquery|bodynumberkhông3Số thành phần dọc của BlurHash (1–9; ảnh dọc mặc định 4).

Ví dụ

curl -X POST "https://apibox.io.vn/v1/image-palette?colors=5" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./my-file"

Kết quả trả về

{
  "width": 320,
  "height": 200,
  "format": "jpeg",
  "has_transparency": false,
  "average": {
    "hex": "#987b6e",
    "rgb": [
      152,
      123,
      110
    ],
    "hsl": [
      19,
      17,
      51
    ],
    "text_color": "#000000",
    "contrast_white": 3.89,
    "contrast_black": 5.39
  },
  "dominant": {
    "hex": "#13506d",
    "rgb": [
      19,
      80,
      109
    ],
    "hsl": [
      199,
      70,
      25
    ],
    "share": 0.3336,
    "text_color": "#ffffff",
    "contrast_white": 8.76,
    "contrast_black": 2.4
  },
  "palette": [
    {
      "hex": "#13506d",
      "rgb": [
        19,
        80,
        109
      ],
      "hsl": [
        199,
        70,
        25
      ],
      "share": 0.3336,
      "text_color": "#ffffff",
      "contrast_white": 8.76,
      "contrast_black": 2.4
    },
    {
      "hex": "#ea825f",
      "rgb": [
        234,
        130,
        95
      ],
      "hsl": [
        15,
        77,
        65
      ],
      "share": 0.3125,
      "text_color": "#000000",
      "contrast_white": 2.67,
      "contrast_black": 7.86
    },
    {
      "hex": "#cb977f",
      "rgb": [
        203,
        151,
        127
      ],
      "hsl": [
        19,
        42,
        65
      ],
      "share": 0.2989,
      "text_color": "#000000",
      "contrast_white": 2.54,
      "contrast_black": 8.27
    },
    {
      "hex": "#fdd466",
      "rgb": [
        253,
        212,
        102
      ],
      "hsl": [
        44,
        97,
        70
      ],
      "share": 0.0438,
      "text_color": "#000000",
      "contrast_white": 1.42,
      "contrast_black": 14.79
    },
    {
      "hex": "#556f7b",
      "rgb": [
        85,
        111,
        123
      ],
      "hsl": [
        199,
        18,
        41
      ],
      "share": 0.0112,
      "text_color": "#ffffff",
      "contrast_white": 5.32,
      "contrast_black": 3.95
    }
  ],
  "is_dark": false,
  "blurhash": {
    "hash": "L|LCI:a#WXs,}Tj@j@f7RQoJoJWE",
    "components": [
      4,
      3
    ],
    "placeholder": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAUCAIAAABj86gYAAAGfElEQVR4XlXNWXBT1xkH8PPQmb50Ojz1oTN56UMf0lKmaVqcBd…"
  },
  "thumbhash": {
    "base64": "4DgOVJh3eIePeIiDeHd3j3b3eA==",
    "placeholder": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAASCAYAAAA6yNxSAAAJcklEQVR4AQCBAH7/APp1Uf/5dFD/+HJO//dwTP/3b0r/+G9K//…",
    "average": "#997d6f"
  },
  "method": "median cut seeds refined by k-means on a 128 px thumbnail (pixels with alpha < 50% ignored)"
}

Ứng dụng

  • Màu giữ chỗ và BlurHash cho ảnh sản phẩm của shop online
  • Đổi màu giao diện trang, thẻ theo ảnh bìa
  • Chọn chữ trắng hay đen khi đặt lên ảnh người dùng
  • Lập chỉ mục ảnh theo màu để lọc tìm kiếm

Hỏi đáp

Nên dùng BlurHash hay ThumbHash?

Cả hai đều là chuỗi ngắn, giải mã bằng thư viện nhỏ phía client. ThumbHash giữ tỷ lệ khung hình, độ trong suốt và chi tiết hơn; BlurHash có nhiều thư viện hơn (iOS, Android, React Native).

Vì sao bảng màu thiếu màu của chi tiết nhỏ?

Màu được tính theo diện tích. Tăng colors để thấy vùng nhỏ; vùng rất nhỏ (dưới khoảng 1%) vẫn có thể bị gộp với màu bên cạnh.

Màu chữ được chọn thế nào?

Là đen hoặc trắng, chọn màu có tỷ lệ tương phản WCAG 2 cao hơn với màu nền đó; cả hai tỷ lệ đều được trả về.

API liên quan

Bắt đầu với 1.000 request miễn phí mỗi tháng. Nhận API key miễn phí →