Docs / Developer tools

Colours API

Colour conversions, WCAG contrast checks and the palette of a picture.

Hex, RGB, HSL and OKLCH for any colour; whether a text colour is readable on a background, with a nearby colour that is; the main colours of a picture.

Base URL https://api.dharun.devNo key needed for most600 units a minute, 3000 with a free keyThis page as Markdown

One colour every way

GET/v1/color/{color}

Parameter	Description
`color`path, required	Hex (with or without #, written %23), rgb(...), hsl(...) or a name such as saffron.

curl

curl "https://api.dharun.dev/v1/color/ff9933?utm_medium=docs"

JavaScript

const response = await fetch("https://api.dharun.dev/v1/color/ff9933?utm_medium=docs");
const body = await response.json();
if (!response.ok) throw new Error(body.error.message);
console.log(body.data);

Python

import requests

response = requests.get("https://api.dharun.dev/v1/color/ff9933?utm_medium=docs", timeout=10)
body = response.json()
if not response.ok:
    raise RuntimeError(body["error"]["message"])
print(body["data"])

Try it here

Change the values and send the request from your browser. Needs JavaScript.

Response

{
  "data": {
    "hex": "#ff9933",
    "rgb": [
      255,
      153,
      51
    ],
    "hsl": {
      "h": 30,
      "l": 60,
      "s": 100
    },
    "oklch": {
      "c": 0.163,
      "h": 60.3,
      "l": 0.774
    },
    "css": {
      "hsl": "hsl(30 100% 60%)",
      "oklch": "oklch(0.774 0.163 60.3)",
      "rgb": "rgb(255 153 51)"
    },
    "luminance": 0.4428,
    "textColor": "#000000"
  },
  "meta": {}
}

Contrast check

GET/v1/color/contrast

Parameter	Description
`fg`query, required	Text colour.
`bg`query, required	Background colour.

curl

curl "https://api.dharun.dev/v1/color/contrast?fg=999999&bg=ffffff&utm_medium=docs"

JavaScript

const response = await fetch("https://api.dharun.dev/v1/color/contrast?fg=999999&bg=ffffff&utm_medium=docs");
const body = await response.json();
if (!response.ok) throw new Error(body.error.message);
console.log(body.data);

Python

import requests

response = requests.get("https://api.dharun.dev/v1/color/contrast?fg=999999&bg=ffffff&utm_medium=docs", timeout=10)
body = response.json()
if not response.ok:
    raise RuntimeError(body["error"]["message"])
print(body["data"])

Try it here

Change the values and send the request from your browser. Needs JavaScript.

Response

{
  "data": {
    "bg": "#ffffff",
    "contrast": {
      "ratio": 2.85,
      "passes": {
        "AA": false,
        "AAA": false,
        "AAALarge": false,
        "AALarge": false,
        "nonText": false
      },
      "suggestion": "#757575"
    },
    "fg": "#999999"
  },
  "meta": {
    "note": "WCAG 2 contrast: AA needs 4.5 for body text and 3 for large text; AAA needs 7 and 4.5. suggestion is the nearest text colour that reaches AA."
  }
}

Palette of a picture

POST/v1/color/palette

Its main colours with their shares and a readable text colour for each. Options go in the query string, or as form fields when the file is sent as multipart/form-data.

Send: A picture: JPEG, PNG, WebP, HEIC, AVIF, GIF, BMP or TIFF, up to 10 MB. Post the file as the request body, or as multipart/form-data. Try it with this sample.

What you send here is never written to the log, and the answer is not cached.

Parameter	Description
`count`query	Colours, 1 to 16. Default 6.

curl

# a sample to try: https://api.dharun.dev/samples/photo.jpg
curl -F "[email protected]" "https://api.dharun.dev/v1/color/palette?count=5&utm_medium=docs"

JavaScript

// input is an <input type="file"> element
const form = new FormData();
form.append("file", input.files[0]);
const response = await fetch("https://api.dharun.dev/v1/color/palette?count=5&utm_medium=docs", { method: "POST", body: form });
const body = await response.json();
if (!response.ok) throw new Error(body.error.message);
console.log(body.data);

Python

import requests

files = [("file", open("photo.jpg", "rb"))]
response = requests.post("https://api.dharun.dev/v1/color/palette?count=5&utm_medium=docs", files=files, timeout=90)
body = response.json()
if not response.ok:
    raise RuntimeError(body["error"]["message"])
print(body["data"])

Try it here

Change the values and send the request from your browser. Needs JavaScript.

Response, with lists and long text shortened

{
  "data": [
    {
      "hex": "#d6e0e8",
      "share": 0.432,
      "textColor": "#000000"
    },
    {
      "hex": "#c1ced9",
      "share": 0.357,
      "textColor": "#000000"
    },
    {
      "hex": "#de9226",
      "share": 0.184,
      "textColor": "#000000"
    }
  ],
  "meta": {
    "note": "The main colours, largest share first (median cut, then k-means). Transparent pixels are left out."
  }
}

Using an AI assistant? Connect the MCP server and it can call this API by itself. Want every endpoint on one bench? Open the playground.