How to extract the dominant colors and palette of an image with an API
Updated 2026-10-12
Use when an agent needs the dominant colors or palette of an image.
From an MCP client, add https://tanod.dev/mcp and call image_colors; its free daily calls are applied automatically, no key or signup.
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 -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
{
"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, Polygon, Solana, BNB Chain or Arbitrum 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.
Use it from Claude without writing code: in claude.ai or Claude Desktop, add https://tanod.dev/mcp/images?via=image-color-palette-api as a custom connector (steps), then ask in plain words, for example "What are the dominant colours in this image?" The free daily allowance is applied automatically over MCP. Beyond it a call needs an x402 payment, which these clients can make.
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.