Extract color palettes with 1 API call

Integrate color palette extraction into your app or pipeline. POST an image, get its dominant colors back as JSON — HEX, RGB and HSL with population and WCAG contrast data. The endpoint is free: calls never consume credits.

Get API Key

Not a developer? Use the web app instead — no code required.

Easy to integrate

A simple HTTP interface with sensible options:

Source images: Direct upload (image_file), a URL (image_url), or a base64 string (image_base64).
Result: Always JSON: colors sorted by dominance, plus complementary and analogous harmony suggestions derived from the top color.
Same quantizer as the web app: The server runs the identical median-cut implementation the browser tool uses, so API results match what your users see.

Get started

Create an API key in your dashboard, then send your first request. Palette extraction is free — you only need the key for authentication and fair-use rate limiting. Authenticate with X-Api-Key: cp_live_… (or Authorization: Bearer cp_live_…).

Sample code

The only request you need:

curl -H "X-Api-Key: cp_live_..." \
  -F "image_file=@/path/to/file.jpg" \
  -F "max_colors=8" \
  -f https://usely.tools/api/v1/palette \
  -o palette.json

Response format

Colors are sorted by population — the fraction of the image each color covers. contrast holds the WCAG 2.x contrast ratio against white and black; text_color is the safer of the two for text on that color.

{
  "data": {
    "image": { "width": 1600, "height": 1000 },
    "colors": [
      {
        "hex": "#e76f51",
        "rgb": { "r": 231, "g": 111, "b": 81 },
        "hsl": { "h": 12, "s": 76, "l": 61 },
        "population": 0.34,
        "contrast": { "white": 2.61, "black": 8.05 },
        "text_color": "#000000"
      }
    ],
    "harmonies": [
      { "label": "Complementary", "colors": ["#e76f51", "#51c9e7"] },
      { "label": "Analogous", "colors": ["#e75186", "#e76f51", "#e7b251"] }
    ]
  },
  "credits_charged": 0
}

API Reference

POST /api/v1/palette

Extracts the dominant color palette of a JPG / PNG / WebP image. File size up to 12 MB; input resolution up to 32 megapixels. Image source: file upload (binary or base64) or download from URL. Requires an API key in the X-Api-Key header (or a Bearer token in Authorization).

Request body — `multipart/form-data` or `application/json`

Parameter	Type	Description
`image_file`	binary	Source image file (binary). If present, the other image source parameters must be empty.
`image_base64`	string	Source image as a base64-encoded string. Mutually exclusive with the other sources.
`image_url`	string	Source image URL to fetch. Mutually exclusive with the other sources.
`max_colors`	integer	Number of palette colors to extract, 1–16 (default `8`). Near-identical colors are merged, so the response may contain fewer.

Request headers

Header	Description
`X-Api-Key`	Your API key (`cp_live_…`). Also accepted as `Authorization: Bearer …`.
`Content-Type`	`multipart/form-data` for file upload or `application/json` for URL/base64 sources.

Responses

Code	Description
`200`	Palette extracted. JSON body as shown above; headers include `X-Credits-Charged: 0` and rate-limit headers.
`400`	Invalid parameters or missing image source. Envelope: `{ "error": { "code", "message" } }`.
`401`	Authentication failed — missing or invalid API key.
`413`	Image is over 12 MB.
`422`	The image could not be decoded (unsupported or corrupt format).
`429`	Rate limit exceeded. Includes a `Retry-After` header.

Response headers

Header	Description
`X-Credits-Charged`	Always `0` — palette extraction is free.
`X-RateLimit-Remaining`	Requests remaining in the current window.

Account endpoint

GET /api/v1/account

Fetch the current credit balance for the authenticated key. Palette calls never consume credits, but the shared toolwerk wallet is visible here for consistency with the other services.

{
  "data": {
    "credits": { "balance": 200 }
  }
}