Color Palette

Extract the dominant colors from an image and return them as hex color values. Uses quantized frequency analysis to identify the most prominent and visually distinct colors.

API Endpoint

POST /api/v1/tools/color-palette

Accepts multipart form data with an image file and an optional JSON settings field.

Parameters

Parameter	Type	Required	Default	Description
count	integer	No	8	Number of colors to extract (2-16)
format	string	No	"hex"	Color format: hex, rgb, hsl

Example Request

curl -X POST http://localhost:1349/api/v1/tools/color-palette \
  -H "Authorization: Bearer si_your-api-key" \
  -F "[email protected]" \
  -F 'settings={"count": 6, "format": "hex"}'

Example Response

{
  "filename": "photo.jpg",
  "colors": [
    "#304080",
    "#e0a060",
    "#f0f0f0",
    "#203020",
    "#a0c0e0",
    "#806040"
  ],
  "hex": [
    "#304080",
    "#e0a060",
    "#f0f0f0",
    "#203020",
    "#a0c0e0",
    "#806040"
  ],
  "count": 6
}

Response Fields

Field	Type	Description
filename	string	Sanitized filename
colors	array	Array of color strings in the requested format, ordered by dominance (most frequent first)
hex	array	Array of hex color strings (always hex, regardless of the format setting)
count	number	Number of colors extracted

Notes

• Returns up to count dominant colors (default 8, range 2-16), sorted by frequency (most common first).
• The image is internally resized to 100x100 pixels for analysis, so the palette represents overall color distribution rather than small details.
• Colors are extracted using median-cut quantization, which recursively splits pixel populations along the channel with the widest range.
• The alpha channel is removed before analysis, so transparent areas are not considered.
• This is a read-only endpoint. It does not produce a downloadable output file or a jobId.
• HEIC, RAW, PSD, and SVG inputs are automatically decoded before analysis.