Colors API
Relaciones de contraste WCAG, sombras y tintes para tokens de diseño, paletas armónicas (complementaria, análoga, triádica) y extracción de colores dominantes, con un contrato REST limpio.
Tres endpoints para trabajar con el color: contrast para auditorías de accesibilidad, shades para tokens de diseño y paletas armónicas, y extract para obtener los colores dominantes de una imagen. Los endpoints de cálculo funcionan en PHP puro y dan resultados idénticos byte a byte a los de nuestras herramientas web; la extracción usa un pipeline de Python, así que comparte el límite estricto de la 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 los endpoints son públicos: no se necesita clave. Límites 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 la relación de contraste WCAG 2.1 (basada en la luminancia relativa) entre dos colores y devuelve indicadores de cumplimiento AA/AAA para texto normal y grande. Acepta #rgb, #rrggbb, rgb(...) o hsl(...).
https://jinero.online/api/v1/colors/contrast
| Parámetro | Tipo | Descripción |
|---|---|---|
fg |
string | Color de primer plano. Hex, rgb() o hsl(). |
bg |
string | Color de fondo. Mismos formatos que 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
}
}Genera un conjunto completo de tokens de diseño a partir de un color base: tintes (más claros), sombras (más oscuras) y cinco relaciones armónicas (complementaria, análoga ±30°, triádica ±120°, complementaria dividida, tetrádica). Cada color incluye cadenas hex/rgb/hsl, luminancia relativa y un color de texto recomendado.
https://jinero.online/api/v1/colors/shades
| Parámetro | Tipo | Descripción |
|---|---|---|
hex |
string | Color base. Hex/rgb()/hsl(). |
step |
integer | Tamaño del paso en porcentaje: 5, 10 (predeterminado), 20 o 25. |
limit |
integer | Máximo de tintes/sombras que se generan. De forma predeterminada se completa hasta el 100 % en incrementos del paso (normalmente 9 con 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, ... } ]
}
}Obtén el nombre legible más cercano para uno o varios colores: la coincidencia más próxima (distancia perceptual redmean) en un conjunto de ~31.000 colores. Útil para etiquetar paletas extraídas, muestras generadas o cualquier hex que tengas.
https://jinero.online/api/v1/colors/name
| Parámetro | Tipo | Descripción |
|---|---|---|
hex |
string | Un hex o varios separados por comas (hasta 100), p. ej. #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 }
]
}Obtén los N colores principales de cualquier imagen, ya sea un archivo subido o una URL pública. Funciona con agrupamiento k-means en tres modos: balanced, vibrant (prioriza los tonos saturados) y muted (prioriza los neutros poco saturados). Cada color se devuelve con nombre (la coincidencia más próxima): una paleta etiquetada y lista para usar en una sola llamada.
https://jinero.online/api/v1/colors/extract
| Parámetro | Tipo | Descripción |
|---|---|---|
image |
archivo (multipart) | Imagen subida: jpg, jpeg, png, webp, gif, bmp. Máximo 10 MB. Incompatible con image_url. |
image_url |
string | URL pública de la imagen que descargará el servidor (máximo 10 MB; debe responder con image/*). |
count |
integer | Número de colores dominantes que se devuelven. 2–16, predeterminado: 8. |
mode |
string | balanced (predeterminado) · 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 estándar. Los errores devuelven un JSON con el 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." }Acerca de la Colors API de jinero.online
API REST gratuita para todos los cálculos de color: contraste WCAG, generación de sombras y tintes, cinco paletas armónicas y extracción de colores dominantes con k-means de cualquier imagen.
Compatible con WCAG 2.1
El contraste se calcula con la misma linealización sRGB que usa Google Lighthouse: tu CI de accesibilidad coincidirá con nuestras cifras.
Cinco armonías integradas
Complementaria, análoga, triádica, complementaria dividida y tetrádica: todas se calculan como rotaciones del tono HSL a partir de tu color base.
Imagen → paleta
Extracción de colores dominantes con k-means en los modos vibrant / muted / balanced. Acepta archivos subidos o URL públicas.
Pensada para tokens de diseño
Cada color se devuelve con hex, rgb, hsl, luminancia y color de texto recomendado: intégralo directamente en tu mapa de tokens.
Preguntas frecuentes
No. Los endpoints de contraste y de sombras permiten 60 solicitudes/min por IP. La extracción de colores es más pesada (k-means en Python), así que está limitada a 5 solicitudes/min. Regístrate y obtén un token de API para tener límites más altos.
Hex con o sin # (#rgb / #rrggbb), rgb(r,g,b) y hsl(h,s%,l%). Da igual si usas mayúsculas o minúsculas. Internamente normalizamos el color a hex de 6 caracteres en minúsculas antes de hacer los cálculos.
Es el mismo motor: la página web /colors/extract llama al mismo script de Python (resources/python/color_extract.py). La API solo añade un envoltorio JSON y te permite pasar image_url para que el servidor descargue la imagen.
Niveles de WCAG 2.1: AA para texto normal, 4.5:1; AA para texto grande, 3:1; AAA para texto normal, 7:1; AAA para texto grande, 4.5:1. Devolvemos la relación sin procesar y un indicador booleano para cada una de las cuatro comprobaciones, así que puedes aplicar tus propias reglas.
Giramos el tono en la rueda HSL manteniendo la saturación y la luminosidad. Complementaria = +180°, análoga = ±30°, triádica = ±120°, complementaria dividida = ±150°/210°, tetrádica = 90/180/270°. Otras herramientas (basadas en LCH u OKLCh) pueden dar colores distintos con los mismos nombres.