← Back to blog

Free Color Conversion API: Hex, RGB, HSL & CMYK in One Call

September 13, 2026 · Eric · 8 min read

Ask three people for the color of a brand and you get three syntaxes. The designer says #c9a84c. The frontend lead says rgb(201, 168, 76). The print vendor wants C 0 M 16 Y 62 K 21. It is the same color, and somewhere in your pipeline a script is about to choke on the wrong spelling — or worse, on hsl() values that a design token file exports.

Color conversion is one of those small chores that never deserves a dependency tree. You do not want a color library, a build step, and a lockfile bump just to answer "what is this hex in CMYK?" for a report or a design-token lint. Agent Media Tools exposes it as one public endpoint: GET /api/color/convert takes any common color literal and returns every representation at once, plus a quick light/dark flag. No API key, no signup for basic use, no color math in your code. This guide covers the real endpoints, response bodies captured from the live API, and the free-tier limits to respect before you loop a thousand colors through it.

The two endpoints

EndpointInputReturns
GET /api/color/convertvalue — one color literalhex, hex_alpha, rgb, rgba, hsl, hsla, cmyk, luminance, is_light
GET /api/color/namesnothing (or search)The named-color lookup table, or names matching a substring

Both are plain GET requests with query parameters, so they work from a shell one-liner, a browser tab, or any HTTP client with no color library installed.

Quick start: hex to RGB, HSL, and CMYK with curl

One request gives you every format. Note the %23: a raw # starts a URL fragment, so the server would receive an empty value and answer color value required. URL-encode it (or let --data-urlencode do it for you).

curl -s --get --data-urlencode "value=#c9a84c" \
  https://agentmediatools.com/api/color/convert

Real response, trimmed to the useful fields:

{
  "success": true,
  "input": "#c9a84c",
  "hex": "#c9a84c",
  "hex_alpha": "#c9a84c",
  "rgb": { "r": 201, "g": 168, "b": 76, "a": 1 },
  "rgba": "rgba(201, 168, 76, 1)",
  "hsl": { "h": 44, "s": 54, "l": 54 },
  "hsla": "hsla(44, 54%, 54%, 1)",
  "cmyk": { "c": 0, "m": 16.4, "y": 62.2, "k": 21.2 },
  "luminance": 0.66,
  "is_light": true,
  "name": null
}

Shorthand hex works too. #f00, rgb(255,0,0), and hsl(0,100%,50%) all come back as the same normalized red:

{
  "success": true,
  "input": "hsl(0,100%,50%)",
  "hex": "#ff0000",
  "rgb": { "r": 255, "g": 0, "b": 0, "a": 1 },
  "hsl": { "h": 0, "s": 100, "l": 50 },
  "cmyk": { "c": 0, "m": 100, "y": 100, "k": 0 },
  "luminance": 0.213,
  "is_light": false
}

Transparency is preserved as 8-digit hex and 0–1 alpha. Passing #ff000080 returns "hex_alpha": "#ff000080" and "rgba": "rgba(255, 0, 0, 0.5)", while hex stays the opaque #ff0000. That split is handy: use hex for palette keys and hex_alpha when the alpha matters.

What each field is good for

Two honest caveats about those last two fields, because they are easy to over-trust:

Accepted formats, and what fails

InputResult
#c9a84c, #f00Accepted (6-digit and 3-digit hex)
#ff000080Accepted, alpha parsed to 0.5
rgb(255,0,0), rgba(255,0,0,0.5)Accepted (commas or spaces)
hsl(0,100%,50%), hsla(...)Accepted (integer degrees and percentages)
redRejected — use /api/color/names for keywords
#f00f (4-digit hex with alpha)Rejected — expand it to 8 digits first

A rejected value does not return a 4xx status. It returns HTTP 200 with a body like this, so check the success flag rather than the status code:

{ "success": false, "error": "Cannot parse color value. Try #ff0000, rgb(255,0,0), or hsl(0,100%,50%)" }

That matters for quota accounting: in testing, every HTTP-200 response advanced the free daily counter, including parse failures. Validate input locally before you send it, and a malformed token costs nothing.

Named colors without a dictionary

GET /api/color/names returns the lookup table (33 CSS-style names in the current build), and ?search= filters it by substring:

curl -s "https://agentmediatools.com/api/color/names?search=tea"

{ "success": true, "count": 1, "results": [ { "name": "teal", "hex": "#008080" } ] }

Practical use: resolve user-typed color words ("make the header teal") to a literal before handing it to the converter, and reject words that are not in the table instead of guessing.

Python: normalize a color and choose readable text

The pattern that pays off is: let the API do the parsing, then do accessibility math locally on the returned rgb values.

import requests

API = "https://agentmediatools.com/api/color/convert"


def convert(value):
    """Normalize any color literal through the API. Returns the full payload."""
    r = requests.get(API, params={"value": value}, timeout=10)
    data = r.json()
    if r.status_code == 429:
        raise RuntimeError(data["error"])          # free daily limit reached
    if not data.get("success"):
        raise ValueError(data["error"])            # unparseable input
    return data


def wcag_luminance(rgb):
    """WCAG 2.1 relative luminance — this is NOT the API's `luminance` field."""
    def channel(c):
        c = c / 255
        return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4

    return 0.2126 * channel(rgb["r"]) + 0.7152 * channel(rgb["g"]) + 0.0722 * channel(rgb["b"])


def contrast_ratio(rgb_a, rgb_b):
    la, lb = wcag_luminance(rgb_a), wcag_luminance(rgb_b)
    hi, lo = max(la, lb), min(la, lb)
    return (hi + 0.05) / (lo + 0.05)


brand = convert("#c9a84c")                         # one call, every format
black = {"r": 0, "g": 0, "b": 0}
white = {"r": 255, "g": 255, "b": 255}

print(brand["hex"], brand["rgb"], "api luminance:", brand["luminance"], "is_light:", brand["is_light"])
print("brand on black:", round(contrast_ratio(brand["rgb"], black), 2))
print("brand on white:", round(contrast_ratio(brand["rgb"], white), 2))
#c9a84c {'r': 201, 'g': 168, 'b': 76, 'a': 1} api luminance: 0.66 is_light: True
brand on black: 9.19
brand on white: 2.29

The API's is_light: true was right — dark text on that gold clears 9.19:1, while white text fails at 2.29:1. You got the parse, the CMYK breakdown, and the accessibility decision from one HTTP call plus about ten lines of math.

Python: stay inside the free pool

Free calls are limited, so cache aggressively. One literal, one request — and remember that the same color spelled differently normalizes to the same hex:

import json
import os
import requests

API = "https://agentmediatools.com/api/color/convert"
CACHE_FILE = "color-cache.json"


def convert(value, cache):
    """One request per unique literal; cached answers cost nothing."""
    if value in cache:
        return cache[value]
    data = requests.get(API, params={"value": value}, timeout=10).json()
    if data.get("success"):
        cache[value] = data          # cache successes only
    return data


cache = json.load(open(CACHE_FILE)) if os.path.exists(CACHE_FILE) else {}
normalized = {}

for literal in ("#f00", "rgb(255,0,0)", "hsl(0,100%,50%)"):
    data = convert(literal, cache)
    normalized.setdefault(data["hex"], []).append(literal)

json.dump(cache, open(CACHE_FILE, "w"), indent=2)

for hex_code, spellings in normalized.items():
    print(hex_code, "<-", " | ".join(spellings))
print("cached literals:", len(cache))
#ff0000 <- #f00 | rgb(255,0,0) | hsl(0,100%,50%)
cached literals: 3

Grouping by the returned hex is also how you detect duplicate tokens in a design system: three token files, three spellings, one actual color.

Free tier and limits

When you run out, the endpoint answers HTTP 429 with a structured body instead of a stack trace:

{
  "success": false,
  "code": "ANON_DAILY_LIMIT",
  "error": "Free daily limit reached (10/day). Sign up free for 25/day—no card required: https://agentmediatools.com/app?register=1",
  "suggested_action": "register",
  "limit": 10,
  "used": 10,
  "register_url": "https://agentmediatools.com/app?register=1",
  "pricing_url": "https://agentmediatools.com/pricing"
}

Branch on code (ANON_DAILY_LIMIT, FREE_USER_DAILY_LIMIT, AGENT_FREE_DAILY_LIMIT, AGENT_PAID_DAILY_LIMIT) rather than string-matching the human-readable error, and let your agent back off instead of retrying the same request in a loop.

When this API is the wrong tool

Conversion reads your value and returns a fixed set of formats. If you are converting a hundred thousand colors inside a data pipeline, a local library is the right call — no network, no daily budget, no latency. Reach for the endpoint when zero setup beats the cost of a request: shell scripts, CI checks, serverless functions with no native color dependency, notebook cells, and agent tool calls where the model should not be doing hex arithmetic in its head. The browser toolbox also has the same converter as a UI panel if you just want to eyeball a color.

Convert a color right now

Open the toolbox for the browser panel, or call the same endpoint from your script with no API key.

Open toolbox