Colors API
Taxas de contraste WCAG, tons claros e escuros para design tokens, paletas harmônicas (complementar, análoga, triádica) e extração de cores dominantes — em um único contrato REST limpo.
Três endpoints para trabalhar com cores: contrast para auditorias de acessibilidade, shades para design tokens e paletas harmônicas e extract para extrair as cores dominantes de uma imagem. Os endpoints de cálculo rodam em PHP puro e dão resultados idênticos, byte a byte, aos das nossas ferramentas web; a extração usa um pipeline em Python, então tem o mesmo limite rígido da Images API.
# Check black-on-white contrast
curl "https://jinero.online/api/v1/colors/contrast?fg=%23000&bg=%23fff"
# Generate shades for a brand color
curl "https://jinero.online/api/v1/colors/shades?hex=%233b82f6&step=10"const r = await fetch("https://jinero.online/api/v1/colors/contrast?fg=%23000&bg=%23fff");
const { ratio, aa, aaa } = await r.json();Todos os endpoints são públicos — sem chave. Limites por IP:
# Anonymous limits (per IP):
# GET /colors/contrast 60 req/min
# GET /colors/shades 60 req/min
# GET /colors/name 60 req/min
# POST /colors/extract 5 req/min (Python pipeline)
# Max image upload: 10 MB
# Max image_url fetch: 10 MB (server-side, image/* only)Calcula a taxa de contraste WCAG 2.1 (pela luminância relativa) entre duas cores e retorna a indicação de aprovação AA/AAA para texto normal e grande. Aceita #rgb, #rrggbb, rgb(...) ou hsl(...).
https://jinero.online/api/v1/colors/contrast
| Parâmetro | Tipo | Descrição |
|---|---|---|
fg |
string | Cor do texto. Hex, rgb() ou hsl(). |
bg |
string | Cor de fundo. Os mesmos formatos de fg. |
curl "https://jinero.online/api/v1/colors/contrast?fg=%23000000&bg=%23ffffff"
# Equivalent with rgb()
curl "https://jinero.online/api/v1/colors/contrast?fg=rgb(0,0,0)&bg=rgb(255,255,255)"const url = new URL("https://jinero.online/api/v1/colors/contrast");
url.searchParams.set("fg", "#1d4ed8");
url.searchParams.set("bg", "#ffffff");
const r = await fetch(url);
const data = await r.json();
if (!data.aa.normal) console.warn(`Ratio ${data.ratio_string} fails WCAG AA`);$r = Http::get("https://jinero.online/api/v1/colors/contrast", [
"fg" => "#1d4ed8",
"bg" => "#ffffff",
]);
$ratio = $r->json("ratio");{
"success": true,
"foreground": "#000000",
"background": "#ffffff",
"ratio": 21,
"ratio_string": "21.00:1",
"aa": { "normal": true, "large": true },
"aaa": { "normal": true, "large": true },
"thresholds": {
"aa_normal": 4.5,
"aa_large": 3,
"aaa_normal": 7,
"aaa_large": 4.5
}
}Gera um conjunto completo de design tokens a partir de uma cor base: tons claros, tons escuros e cinco relações harmônicas (complementar, análoga ±30°, triádica ±120°, complementar dividida, tetrádica). Cada cor vem com strings hex/rgb/hsl, luminância relativa e a cor de texto recomendada.
https://jinero.online/api/v1/colors/shades
| Parâmetro | Tipo | Descrição |
|---|---|---|
hex |
string | Cor base. Hex/rgb()/hsl(). |
step |
integer | Tamanho do passo em porcentagem: 5, 10 (padrão), 20 ou 25. |
limit |
integer | Limite de quantos tons claros/escuros gerar. Por padrão, preenche até 100% em incrementos do passo (normalmente 9 com step=10). |
curl "https://jinero.online/api/v1/colors/shades?hex=%233b82f6&step=20"const r = await fetch("https://jinero.online/api/v1/colors/shades?hex=%231d4ed8&step=10");
const { base, tints, shades, harmonies } = await r.json();
// Drop into a design token map
const tokens = Object.fromEntries(
tints.map(t => [`brand-${100 - t.percent}`, t.hex])
);$res = Http::get("https://jinero.online/api/v1/colors/shades", ["hex" => "#3b82f6", "step" => 20]);
$harmony = $res->json("harmonies.complementary.0.hex");{
"success": true,
"step": 20,
"base": {
"hex": "#3b82f6",
"rgb": [59, 130, 246],
"rgb_string": "rgb(59, 130, 246)",
"hsl": [217, 91, 60],
"hsl_string": "hsl(217, 91%, 60%)",
"luminance": 0.2355,
"is_light": true,
"text_color": "#000000",
"contrast_on_white": 3.68,
"contrast_on_black": 5.71
},
"tints": [ { "percent": 20, "hex": "#629bf8", ... } ],
"shades": [ { "percent": 20, "hex": "#2f68c5", ... } ],
"harmonies": {
"complementary": [ { "rotation": 180, "hex": "#f6af3b", ... } ],
"analogous": [ { "rotation": -30, ... }, { "rotation": 30, ... } ],
"triadic": [ { "rotation": -120, ... }, { "rotation": 120, ... } ],
"split_complementary":[ { "rotation": 150, ... }, { "rotation": 210, ... } ],
"tetradic": [ { "rotation": 90, ... }, { "rotation": 180, ... }, { "rotation": 270, ... } ]
}
}Obtenha o nome legível mais próximo para uma ou várias cores — a correspondência mais próxima (distância perceptual redmean) em um conjunto de ~31 mil cores. Prático para nomear paletas extraídas, amostras geradas ou qualquer hex que você tenha.
https://jinero.online/api/v1/colors/name
| Parâmetro | Tipo | Descrição |
|---|---|---|
hex |
string | Um hex ou vários separados por vírgula (até 100), ex.: #3b82f6,#000,#ff7f50. |
# Single
curl "https://jinero.online/api/v1/colors/name?hex=%233b82f6"
# Batch (comma-separated)
curl "https://jinero.online/api/v1/colors/name?hex=%233b82f6,%23000,%23ff7f50"const r = await fetch("https://jinero.online/api/v1/colors/name?hex=" + encodeURIComponent("#3b82f6,#ff7f50"));
const { colors } = await r.json();
// colors: [{ input, name, hex, exact, distance }]$r = Http::get("https://jinero.online/api/v1/colors/name", ["hex" => "#3b82f6,#ff7f50"]);
$name = $r->json("colors.0.name"); // "Dodger Blue"{
"success": true,
"count": 3,
"colors": [
{ "input": "#3B82F6", "name": "Dodger Blue", "hex": "#3E82FC", "exact": false, "distance": 10.91 },
{ "input": "#000000", "name": "Black", "hex": "#000000", "exact": true, "distance": 0 },
{ "input": "#FF7F50", "name": "Coral", "hex": "#FF7F50", "exact": true, "distance": 0 }
]
}Extrai as N cores principais de qualquer imagem — um arquivo enviado ou uma URL pública. Usa clusterização k-means em três modos: balanced, vibrant (prioriza matizes saturados) e muted (prioriza neutros pouco saturados). Cada cor volta com nome (a correspondência mais próxima) — uma paleta nomeada e pronta para usar em uma só chamada.
https://jinero.online/api/v1/colors/extract
| Parâmetro | Tipo | Descrição |
|---|---|---|
image |
arquivo (multipart) | Envio de imagem — jpg, jpeg, png, webp, gif, bmp. Até 10 MB. Não pode ser usado junto com image_url. |
image_url |
string | URL pública da imagem que o servidor vai baixar (até 10 MB; a resposta deve ser image/*). |
count |
integer | Número de cores dominantes a retornar. 2–16, padrão 8. |
mode |
string | balanced (padrão) · vibrant · muted. |
# Option 1: file upload
curl -X POST https://jinero.online/api/v1/colors/extract \
-F "[email protected]" \
-F "count=6" \
-F "mode=vibrant"
# Option 2: URL fetch
curl -X POST https://jinero.online/api/v1/colors/extract \
-H "Content-Type: application/json" \
-d '{"image_url": "https://example.com/cover.jpg", "count": 6}'// File upload
const form = new FormData();
form.append("image", file);
form.append("count", "6");
form.append("mode", "vibrant");
const r = await fetch("https://jinero.online/api/v1/colors/extract", { method: "POST", body: form });
const { colors } = await r.json();
// colors: [{ hex, rgb, hsl, percent, name, name_hex, name_exact }]{
"success": true,
"mode": "vibrant",
"count": 6,
"colors": [
{ "hex": "#f9f9f9", "rgb": {"r":249,"g":249,"b":249}, "hsl": {"h":0,"s":0,"l":97.6}, "percent": 90.8, "name": "White", "name_hex": "#FFFFFF", "name_exact": false },
{ "hex": "#1d1c1b", "rgb": {"r":29,"g":28,"b":27}, "hsl": {"h":30,"s":3.6,"l":11}, "percent": 5.8, "name": "Cod Gray", "name_hex": "#1B1B1B", "name_exact": false },
{ "hex": "#a1989b", "rgb": {"r":161,"g":152,"b":155}, "hsl": {"h":340,"s":4.6,"l":61.4}, "percent": 1.9, "name": "Dusty Gray", "name_hex": "#A8989B", "name_exact": false }
]
}Semântica HTTP padrão. Os erros retornam JSON com o campo "message".
// 422 — invalid color format
{ "message": "Invalid color format. Accepts #rgb, #rrggbb, rgb(r,g,b), or hsl(h,s%,l%)." }
// 422 — neither image nor image_url provided
{ "message": "Provide one of: image (file) or image_url." }
// 422 — URL fetch failed (404 from remote, non-image content, > 10 MB)
{ "message": "Could not fetch image from URL." }
// 429 — rate limit exceeded (5 req/min on extract)
{ "message": "Too Many Attempts." }Sobre a Colors API do jinero.online
API REST gratuita para todos os cálculos de cor: contraste WCAG, geração de tons claros e escuros, cinco paletas harmônicas e extração de cores dominantes (k-means) de qualquer imagem.
Pronto para a WCAG 2.1
O contraste é calculado com a mesma linearização sRGB que o Google Lighthouse usa — o seu CI de acessibilidade vai concordar com os nossos números.
Cinco harmonias integradas
Complementar, análoga, triádica, complementar dividida e tetrádica — todas calculadas como rotações de matiz HSL a partir da sua cor base.
Imagem → paleta
Extração de cores dominantes com k-means nos modos vibrant / muted / balanced. Aceita arquivos enviados ou URLs públicas.
Pronto para design tokens
Cada cor volta com hex, rgb, hsl, luminância e a cor de texto recomendada — conecte direto ao seu mapa de tokens.
Perguntas frequentes
Não. Os endpoints de contraste e de tons permitem 60 req/min por IP. A extração de cores é mais pesada (k-means em Python), por isso é limitada a 5 req/min. Para limites maiores, crie uma conta e gere um token de API.
Hex com ou sem # (#rgb / #rrggbb), rgb(r,g,b) e hsl(h,s%,l%). Maiúsculas ou minúsculas, tanto faz. Antes dos cálculos, normalizamos internamente para hex de 6 caracteres em minúsculas.
É o mesmo motor — a página web /colors/extract chama o mesmo script Python (resources/python/color_extract.py). A API só adiciona um wrapper JSON e permite passar image_url para o servidor baixar a imagem.
Níveis da WCAG 2.1: AA para texto normal 4.5:1, AA para texto grande 3:1, AAA normal 7:1, AAA grande 4.5:1. Retornamos a taxa bruta e indicadores booleanos para as quatro verificações, para você aplicar as suas próprias regras.
Giramos o matiz no círculo HSL, preservando a saturação e a luminosidade. Complementar = +180°, análoga = ±30°, triádica = ±120°, complementar dividida = ±150°/210°, tetrádica = 90/180/270°. Outras ferramentas (baseadas em LCH ou OKLCh) podem gerar cores diferentes com os mesmos nomes.