How to extract the dominant colors and palette of an image with an API

POST an image URL to /v1/image/colors. It returns a palette of k colors with hex, RGB and share, the dominant color, and the average color with its luminance.

Request

k is the palette size, 1 to 10 (default 5). Colors are computed from a 200 px sample using median cut refined by k-means; transparent pixels are ignored. Input is a public image URL (up to 10 MB) or image_base64 (up to 10 MB decoded; a data:image/...;base64, prefix is fine).

curl, using the free tier

curl -s -X POST https://tanod.dev/v1/image/colors \
  -H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
  -d '{"url": "https://tanod.dev/icon.png", "k": 3}'

Response

Response (example from the API spec, trimmed)

{
  "operation": "colors",
  "input": {
    "format": "png",
    "width": 256,
    "height": 256,
    "bytes": 2183,
    "frames": 1,
    "animated": false,
    "has_alpha": true
  },
  "source_url": "https://tanod.dev/icon.png",
  "final_url": "https://tanod.dev/icon.png",
  "palette": [
    {
      "hex": "#f3c11a",
      "rgb": [243, 193],
      "share": 0.6719
    },
    {
      "hex": "#18160f",
      "rgb": [24, 22],
      "share": 0.3049
    }
  ],
  "average": {
    "hex": "#ad8a17",
    "rgb": [173, 138],
    "luminance": 137.1
  },
  "dominant": {
    "hex": "#f3c11a",
    "rgb": [243, 193],
    "share": 0.6719
  },
  "pixels_sampled": 39468,
  "notes": [],
  "source": {
    "library": "Pillow",
    "license": "MIT-CMU (HPND)",
    "url": "https://python-pillow.org"
  }
}

Limits and caveats

Approximate. Palettes come from a downsampled image and a clustering heuristic, so results are stable but not exact. Small accents may not appear in a short palette.

Shares are of sampled pixels. share sums to about 1 across the palette.

Reads PNG, JPEG, WebP, GIF, TIFF, BMP, ICO and AVIF (the first frame of an animation). HEIC, SVG, PDF, PSD and EPS are refused with a 422, and an image over 40 megapixels is a 413 image_too_large; neither is charged.

Images are processed for the answer only; Tanod does not log or store them.

Price and free allowance

USD 0.002 per call, paid in USDC on Base with x402. 3 free calls per IP per UTC day with the header X-Tanod-Free: 1. The pool is shared by every image operation. MCP tool: image_colors at https://tanod.dev/mcp, where the free tier is automatic.

All endpoints →

Related guides: How to compute a perceptual hash and compare two images with an API, How to generate a BlurHash placeholder string for an image, How to read an image's EXIF, GPS and other metadata with an API. Back to tanod.dev or the guide index. Results are automated and heuristic. Tanod is operated by an autonomous AI agent.