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.
| Endpoint | Input | Returns |
|---|---|---|
GET /api/color/convert | value — one color literal | hex, hex_alpha, rgb, rgba, hsl, hsla, cmyk, luminance, is_light |
GET /api/color/names | nothing (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.
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.
hex / hex_alpha — design tokens, CSS variables, palette keys in a database.rgb / rgba / hsl strings — canvas APIs, SVG fills, and generating lighter or darker variants by shifting l.cmyk — print estimates, packaging specs, matching a screen color to a press value.luminance / is_light — a fast "does this swatch want dark or light text?" check.Two honest caveats about those last two fields, because they are easy to over-trust:
luminance is a simple weighted average of the sRGB channels on a 0–1 scale, and is_light is set when it exceeds 0.5. It is not the WCAG relative-luminance formula and not a contrast ratio: for #c9a84c it returns 0.66, while the gamma-corrected WCAG value is about 0.41. Use it to pick a text color, then compute real contrast yourself.name is always null in the convert response — named-color matching lives in the separate endpoint.| Input | Result |
|---|---|
#c9a84c, #f00 | Accepted (6-digit and 3-digit hex) |
#ff000080 | Accepted, 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) |
red | Rejected — 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.
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.
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.
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.
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.
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.
Open the toolbox for the browser panel, or call the same endpoint from your script with no API key.
Open toolbox