Random Color API

Q: Can I get harmonious palettes instead of single colors?

Yes — the palette route builds a coordinated set from a base color and a scheme, ready for UI mockups.

Q: Do responses include readable text colors?

Every color ships contrastText — the black-or-white hex that stays readable on top of it, so you can style badges without computing contrast yourself.

Q: Can I constrain the random colors?

hue and luminosity bias generation (e.g. only dark blues), and seed makes results reproducible.

MOCK DATA

Random colors in hex, RGB and HSL with hue and luminosity filters, nearest CSS color names and WCAG contrast text — plus deterministic color-scheme palettes.

Generated test data for fixtures and development

Base URL: /api/colors
Category: Design & Media
Capabilities: 2 routes Seedable
Last updated: July 30, 2026

GET /api/colors Generate random colors with hue and luminosity filters Returns a list

Colors are drawn uniformly inside the requested HSL ranges; hex, rgb and hsl always describe the same value.

Live requestRuns against the public API

No key required

GET/api/colors?count=5

Request parameters

huedefault any

Color family as an HSL hue range: red 345–15°, orange 15–45°, yellow 45–70°, green 70–170°, blue 170–260°, purple 260–315°, pink 315–345°. 'monochrome' = pure grays (saturation 0%).

luminositydefault any

Lightness band: 'bright' = lightness 45–65% with saturation ≥ 60%, 'light' = 70–90%, 'dark' = 10–35%, 'any' = 10–90%.

Advanced response options7 options

countdefault 10

How many records to generate (1–100).

seed

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

fields

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

exclude

Return all fields except these (comma-separated).

formatdefault json

Response format: json envelope, ndjson (one record per line) or csv.

prettydefault false

Pretty-print the JSON response.

unwrapdefault false

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples 9 params · 5 fields · 4 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/colors?count=5"

const res = await fetch("https://randomapi.dev/api/colors?count=5");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/colors?count=5").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/colors?count=5"
), true);
$data = $json["data"];

Parameters Route-specific request inputs 2

Parameter	Type	Default & allowed	Description
`hue`	enum	default: any allowed: red \| orange \| yellow \| green \| blue \| purple \| pink \| monochrome \| any example: green	Color family as an HSL hue range: red 345–15°, orange 15–45°, yellow 45–70°, green 70–170°, blue 170–260°, purple 260–315°, pink 315–345°. 'monochrome' = pure grays (saturation 0%).
`luminosity`	enum	default: any allowed: bright \| light \| dark \| any example: dark	Lightness band: 'bright' = lightness 45–65% with saturation ≥ 60%, 'light' = 70–90%, 'dark' = 10–35%, 'any' = 10–90%.

hue enum

default: any

example: hue=green

luminosity enum

Lightness band: 'bright' = lightness 45–65% with saturation ≥ 60%, 'light' = 70–90%, 'dark' = 10–35%, 'any' = 10–90%.

default: any

allowed: bright | light | dark | any

example: luminosity=dark

Universal parameters Shared response and formatting options 7

Parameter	Type	Default & allowed	Description
`count`	int	default: 10 allowed: 1 – 100 example: 3	How many records to generate (1–100).
`seed`	int	example: 42	Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).
`fields`	list	example: hex,rgb	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: contrastText	Return all fields except these (comma-separated).
`format`	enum	default: json allowed: json \| ndjson \| csv example: csv	Response format: json envelope, ndjson (one record per line) or csv.
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

count int

How many records to generate (1–100).

default: 10

allowed: 1 – 100

example: count=3

seed int

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

example: seed=42

fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=hex,rgb

exclude list

Return all fields except these (comma-separated).

example: exclude=contrastText

format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json

allowed: json | ndjson | csv

example: format=csv

pretty boolean

Pretty-print the JSON response.

default: false

example: pretty=true

unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false

example: unwrap=true

Response schema Fields returned in each record 5

Field	Type	Description	Example
`hex`	string (hex)	Lowercase '#rrggbb'.	#3ea873
`rgb`	string (CSS)	CSS rgb() notation with 0–255 channels — same color as hex.	rgb(62, 168, 115)
`hsl`	string (CSS)	CSS hsl() notation. The color is generated in HSL space, so these are the exact source values the filters constrained.	hsl(150, 46%, 45%)
`name`	string	Nearest of the 148 CSS named colors by squared RGB distance (ties resolve alphabetically).	mediumseagreen
`contrastText`	string (hex)	'#000000' or '#ffffff' — whichever reads better on this color per WCAG relative luminance (threshold 0.179).	#000000

hex string (hex)

Lowercase '#rrggbb'.

example: #3ea873

rgb string (CSS)

CSS rgb() notation with 0–255 channels — same color as hex.

example: rgb(62, 168, 115)

hsl string (CSS)

CSS hsl() notation. The color is generated in HSL space, so these are the exact source values the filters constrained.

example: hsl(150, 46%, 45%)

name string

Nearest of the 148 CSS named colors by squared RGB distance (ties resolve alphabetically).

example: mediumseagreen

contrastText string (hex)

'#000000' or '#ffffff' — whichever reads better on this color per WCAG relative luminance (threshold 0.179).

example: #000000

Documented examples

Build-generated requests and complete responses 4

Five random colors /api/colors?count=5

GET /api/colors?count=5

{
  "data": [
    {
      "hex": "#3fe9d2",
      "rgb": "rgb(63, 233, 210)",
      "hsl": "hsl(172, 79%, 58%)",
      "name": "turquoise",
      "contrastText": "#000000"
    },
    {
      "hex": "#9e5f4c",
      "rgb": "rgb(158, 95, 76)",
      "hsl": "hsl(14, 35%, 46%)",
      "name": "sienna",
      "contrastText": "#ffffff"
    },
    {
      "hex": "#8a387f",
      "rgb": "rgb(138, 56, 127)",
      "hsl": "hsl(308, 42%, 38%)",
      "name": "rebeccapurple",
      "contrastText": "#ffffff"
    },
    {
      "hex": "#353108",
      "rgb": "rgb(53, 49, 8)",
      "hsl": "hsl(55, 73%, 12%)",
      "name": "black",
      "contrastText": "#ffffff"
    },
    {
      "hex": "#d115d1",
      "rgb": "rgb(209, 21, 209)",
      "hsl": "hsl(300, 82%, 45%)",
      "name": "darkorchid",
      "contrastText": "#000000"
    }
  ],
  "meta": {
    "endpoint": "colors",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Bright greens /api/colors?hue=green&luminosity=bright&count=5

GET /api/colors?hue=green&luminosity=bright&count=5

{
  "data": [
    {
      "hex": "#38f132",
      "rgb": "rgb(56, 241, 50)",
      "hsl": "hsl(118, 87%, 57%)",
      "name": "limegreen",
      "contrastText": "#000000"
    },
    {
      "hex": "#b2d043",
      "rgb": "rgb(178, 208, 67)",
      "hsl": "hsl(73, 60%, 54%)",
      "name": "yellowgreen",
      "contrastText": "#000000"
    },
    {
      "hex": "#36d394",
      "rgb": "rgb(54, 211, 148)",
      "hsl": "hsl(156, 64%, 52%)",
      "name": "lightseagreen",
      "contrastText": "#000000"
    },
    {
      "hex": "#83d214",
      "rgb": "rgb(131, 210, 20)",
      "hsl": "hsl(85, 83%, 45%)",
      "name": "yellowgreen",
      "contrastText": "#000000"
    },
    {
      "hex": "#21f298",
      "rgb": "rgb(33, 242, 152)",
      "hsl": "hsl(154, 89%, 54%)",
      "name": "mediumspringgreen",
      "contrastText": "#000000"
    }
  ],
  "meta": {
    "endpoint": "colors",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Reproducible dark palette material /api/colors?luminosity=dark&seed=7&count=8

GET /api/colors?luminosity=dark&seed=7&count=8

{
  "data": [
    {
      "hex": "#0d0675",
      "rgb": "rgb(13, 6, 117)",
      "hsl": "hsl(244, 91%, 24%)",
      "name": "navy",
      "contrastText": "#ffffff"
    },
    {
      "hex": "#0c3050",
      "rgb": "rgb(12, 48, 80)",
      "hsl": "hsl(208, 74%, 18%)",
      "name": "midnightblue",
      "contrastText": "#ffffff"
    },
    {
      "hex": "#0a7b5b",
      "rgb": "rgb(10, 123, 91)",
      "hsl": "hsl(163, 85%, 26%)",
      "name": "teal",
      "contrastText": "#ffffff"
    },
    {
      "hex": "#481a5b",
      "rgb": "rgb(72, 26, 91)",
      "hsl": "hsl(282, 55%, 23%)",
      "name": "indigo",
      "contrastText": "#ffffff"
    },
    {
      "hex": "#52193f",
      "rgb": "rgb(82, 25, 63)",
      "hsl": "hsl(320, 53%, 21%)",
      "name": "darkslategray",
      "contrastText": "#ffffff"
    },
    {
      "hex": "#0e0330",
      "rgb": "rgb(14, 3, 48)",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Pure grays /api/colors?hue=monochrome&count=6

GET /api/colors?hue=monochrome&count=6

{
  "data": [
    {
      "hex": "#7a7a7a",
      "rgb": "rgb(122, 122, 122)",
      "hsl": "hsl(0, 0%, 48%)",
      "name": "gray",
      "contrastText": "#000000"
    },
    {
      "hex": "#212121",
      "rgb": "rgb(33, 33, 33)",
      "hsl": "hsl(0, 0%, 13%)",
      "name": "black",
      "contrastText": "#ffffff"
    },
    {
      "hex": "#c9c9c9",
      "rgb": "rgb(201, 201, 201)",
      "hsl": "hsl(0, 0%, 79%)",
      "name": "silver",
      "contrastText": "#000000"
    },
    {
      "hex": "#383838",
      "rgb": "rgb(56, 56, 56)",
      "hsl": "hsl(0, 0%, 22%)",
      "name": "darkslategray",
      "contrastText": "#ffffff"
    },
    {
      "hex": "#c4c4c4",
      "rgb": "rgb(196, 196, 196)",
      "hsl": "hsl(0, 0%, 77%)",
      "name": "silver",
      "contrastText": "#000000"
    },
    {
      "hex": "#1c1c1c",
      "rgb": "rgb(28, 28, 28)",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

GET /api/colors/palette Build a color-scheme palette from one base color Computed answer

Deterministic — no seed, no randomness: the same base and scheme always return the same palette. The base swatch keeps your exact input hex.

Live requestRuns against the public API

No key required

GET/api/colors/palette?base=ff0000

Request parameters

baserequired

Base color as hex: '#rrggbb', 'rrggbb' or 3-digit shorthand ('#f80' / 'f80'). In a URL, encode '#' as %23 — or just omit it. Anything else is a 400.

schemedefault complementary

Scheme recipe: complementary (base + 180° opposite), analogous (±30° neighbors), triadic (+120°/+240°), tetradic (+90°/+180°/+270°), monochromatic (lightness ladder 15/35/50/70/88%).

Advanced response options4 options

fields

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

exclude

Return all fields except these (comma-separated).

prettydefault false

Pretty-print the JSON response.

unwrapdefault false

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples 6 params · 3 fields · 4 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/colors/palette?base=ff0000"

const res = await fetch("https://randomapi.dev/api/colors/palette?base=ff0000");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/colors/palette?base=ff0000").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/colors/palette?base=ff0000"
), true);
$data = $json["data"];

Parameters Route-specific request inputs 2

Parameter	Type	Default & allowed	Description
`base` required	string	example: 3498db	Base color as hex: '#rrggbb', 'rrggbb' or 3-digit shorthand ('#f80' / 'f80'). In a URL, encode '#' as %23 — or just omit it. Anything else is a 400.
`scheme`	enum	default: complementary allowed: complementary \| analogous \| triadic \| tetradic \| monochromatic example: triadic	Scheme recipe: complementary (base + 180° opposite), analogous (±30° neighbors), triadic (+120°/+240°), tetradic (+90°/+180°/+270°), monochromatic (lightness ladder 15/35/50/70/88%).

base string required

Base color as hex: '#rrggbb', 'rrggbb' or 3-digit shorthand ('#f80' / 'f80'). In a URL, encode '#' as %23 — or just omit it. Anything else is a 400.

example: base=3498db

scheme enum

Scheme recipe: complementary (base + 180° opposite), analogous (±30° neighbors), triadic (+120°/+240°), tetradic (+90°/+180°/+270°), monochromatic (lightness ladder 15/35/50/70/88%).

default: complementary

allowed: complementary | analogous | triadic | tetradic | monochromatic

example: scheme=triadic

Universal parameters Shared response and formatting options 4

Parameter	Type	Default & allowed	Description
`fields`	list	example: base,scheme	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: colors	Return all fields except these (comma-separated).
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=base,scheme

exclude list

Return all fields except these (comma-separated).

example: exclude=colors

pretty boolean

Pretty-print the JSON response.

default: false

example: pretty=true

unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false

example: unwrap=true

Response schema Fields returned in each record 3

Field	Type	Description	Example
`base`	string (hex)	The base color normalized to lowercase '#rrggbb' (3-digit shorthand expanded).	#3498db
`scheme`	string	The scheme that was applied.	complementary
`colors`	object[]	Palette swatches as { hex, role }, in scheme order: analogous runs −30° → base → +30°, monochromatic runs darkest → lightest, all other schemes lead with the base.	[{"hex":"#3498db","role":"base"},{"hex":"#db7734","role":"complement"}]

base string (hex)

The base color normalized to lowercase '#rrggbb' (3-digit shorthand expanded).

example: #3498db

scheme string

The scheme that was applied.

example: complementary

colors object[]

Palette swatches as { hex, role }, in scheme order: analogous runs −30° → base → +30°, monochromatic runs darkest → lightest, all other schemes lead with the base.

example: [{"hex":"#3498db","role":"base"},{"hex":"#db7734","role":"complement"}]

Documented examples

Build-generated requests and complete responses 4

Complementary pair for pure red /api/colors/palette?base=ff0000

GET /api/colors/palette?base=ff0000

{
  "data": {
    "base": "#ff0000",
    "scheme": "complementary",
    "colors": [
      {
        "hex": "#ff0000",
        "role": "base"
      },
      {
        "hex": "#00ffff",
        "role": "complement"
      }
    ]
  },
  "meta": {
    "endpoint": "colors",
    "route": "/palette",
    "params": {
      "base": "#ff0000",
      "scheme": "complementary"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Triadic scheme from a brand blue /api/colors/palette?base=3498db&scheme=triadic

GET /api/colors/palette?base=3498db&scheme=triadic

{
  "data": {
    "base": "#3498db",
    "scheme": "triadic",
    "colors": [
      {
        "hex": "#3498db",
        "role": "base"
      },
      {
        "hex": "#db3498",
        "role": "triad +120°"
      },
      {
        "hex": "#98db34",
        "role": "triad +240°"
      }
    ]
  },
  "meta": {
    "endpoint": "colors",
    "route": "/palette",
    "params": {
      "base": "#3498db",
      "scheme": "triadic"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Monochromatic ladder from 3-digit shorthand /api/colors/palette?base=f80&scheme=monochromatic

GET /api/colors/palette?base=f80&scheme=monochromatic

{
  "data": {
    "base": "#ff8800",
    "scheme": "monochromatic",
    "colors": [
      {
        "hex": "#4d2900",
        "role": "darkest (15%)"
      },
      {
        "hex": "#b35f00",
        "role": "dark (35%)"
      },
      {
        "hex": "#ff8800",
        "role": "mid (50%)"
      },
      {
        "hex": "#ffb866",
        "role": "light (70%)"
      },
      {
        "hex": "#ffe2c2",
        "role": "lightest (88%)"
      }
    ]
  },
  "meta": {
    "endpoint": "colors",
    "route": "/palette",
    "params": {
      "base": "#ff8800",
      "scheme": "monochromatic"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Analogous trio ('#' URL-encoded as %23) /api/colors/palette?base=%23663399&scheme=analogous

GET /api/colors/palette?base=%23663399&scheme=analogous

{
  "data": {
    "base": "#663399",
    "scheme": "analogous",
    "colors": [
      {
        "hex": "#333399",
        "role": "analogous -30°"
      },
      {
        "hex": "#663399",
        "role": "base"
      },
      {
        "hex": "#993399",
        "role": "analogous +30°"
      }
    ]
  },
  "meta": {
    "endpoint": "colors",
    "route": "/palette",
    "params": {
      "base": "#663399",
      "scheme": "analogous"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Random colors are generated directly in HSL space, so the hue and luminosity filters are honored exactly — every record genuinely lands inside the documented ranges — and only then converted to RGB. The hex, rgb and hsl fields are three notations of the same color.

How the filters map to HSL:

hue constrains the hue angle: red 345–15°, orange 15–45°, yellow 45–70°, green 70–170°, blue 170–260°, purple 260–315°, pink 315–345°. monochrome forces saturation to 0% (pure grays quantize to at most 81 distinct shades, so very large counts will repeat some).
luminosity constrains lightness: bright 45–65% (with saturation ≥ 60%), light 70–90%, dark 10–35%, any 10–90%. Unless bright demands more, saturation spans 35–100% so the requested hue stays clearly visible.

Each color also carries the nearest of the 148 CSS named colors (smallest squared RGB distance; ties resolve alphabetically, so #00ffff is aqua, not cyan) and a ready-made contrastText — #000000 or #ffffff, chosen by WCAG relative luminance (black text above the 0.179 threshold), so labels stay readable on any swatch.

The list route is seeded: the same seed returns identical colors forever. /palette is the opposite — a pure, deterministic function of base + scheme with no randomness at all:

complementary — the base and its 180° opposite.
analogous — the base flanked by its −30° and +30° neighbors.
triadic / tetradic — 3 or 4 colors evenly spun around the wheel (+120°/+240°, or +90°/+180°/+270°), keeping the base's saturation and lightness.
monochromatic — the base hue and saturation at five lightness stops: 15/35/50/70/88%.

base accepts #rrggbb, rrggbb or 3-digit shorthand (#f80 → #ff8800). In a URL, encode # as %23 — or simply omit it.

Use it for

Generate on-brand placeholder colors for charts, avatars and tag pills (e.g. only dark blues)
Style text on random backgrounds safely with the ready-made WCAG contrastText field
Derive a complete UI color scheme from a single brand hex via /palette

Frequently asked questions

Practical answers about this endpoint 3

Can I get harmonious palettes instead of single colors?

Yes — the palette route builds a coordinated set from a base color and a scheme, ready for UI mockups.

Do responses include readable text colors?

Every color ships contrastText — the black-or-white hex that stays readable on top of it, so you can style badges without computing contrast yourself.

Can I constrain the random colors?

hue and luminosity bias generation (e.g. only dark blues), and seed makes results reproducible.

Standards & references

Primary sources behind the contract

CSS Color Module Level 4 (W3C)

Useful next tools in the catalog

WCAG 2.2 Color Contrast Checker API REAL DATA

Calculate WCAG 2.2 contrast for two opaque sRGB hex colors, including exact relative luminance and AA/AAA normal- and large-text results.

Placeholder Image API MOCK DATA

Hotlinkable SVG placeholder images at any size from 8 to 4000 px — custom label, colors and an optional gradient. Deterministic and crisp at every scale.

Avatar Placeholder API MOCK DATA

Deterministic SVG avatars from any seed string — identicons, initials and abstract shapes. Same seed, same avatar forever; plus ready-to-use avatar URL batches.

SVG Sparkline & Chart Placeholder API MOCK DATA

Sparkline SVGs straight from a URL — plot 2–100 numbers as a line, area or bar chart with custom size, color and smoothing. No chart library needed.

OKLCH & Color Space Conversion API REAL DATA

Convert any CSS color between sRGB, Display P3, Rec2020, CIE Lab/LCh, OKLab/OKLCH and XYZ, with per-gamut flags, Delta-E differences and CSS gamut mapping.

GET /api/colors Generate random colors with hue and luminosity filters Returns a list

Request parameters

Response

Route reference

Documented examples

GET /api/colors/palette Build a color-scheme palette from one base color Computed answer

Request parameters

Response

Route reference

Documented examples

About this API

Coverage & behavior

Use it for

Frequently asked questions

Standards & references

Related APIs