Color season

POST /v1/color · $0.01 a call

Send a front-facing portrait. A vision model checks the photo and marks the cheeks, forehead, hair and irises. Forkcast then measures those colors from the pixels, converts them to CIELAB, and sorts the person into one of 12 seasons by temperature, value and chroma. Each season comes with the same curated palette every time: best colors, neutrals, colors to avoid, metals, lip and blush shades.

For color analysis apps, styling and outfit apps, makeup shade finders.

Request

Send the photo as image (multipart), image_base64 or image_url, as described in the overview. These optional fields go alongside it:

FieldTypeDescription
contextstring, up to 300 charactersAnything else about the photo, e.g. "taken under a warm lamp".
natural_hair_colorstring, up to 60 charactersThe natural hair color if it is dyed, e.g. "dark brown" or "ash blonde". Used instead of the hair in the photo.
eye_colorstring, up to 60 charactersEye color in words, e.g. "hazel". Used when the eyes are hard to see.

Photo tips. Face the camera in daylight from a window, no makeup, hair pulled back from the face, no filter. JPEG gives measured colors; other formats fall back to estimates.

curl https://ourapi.keronlabs.com/v1/color \
  -H "Authorization: Bearer $FORKCAST_KEY" \
  -F image=@portrait.jpg \
  -F context="example"

Response

FieldDescription
summaryOne line for a list view, e.g. "Soft Autumn, warm undertone, medium contrast".
seasonid, name, family (Spring, Summer, Autumn, Winter), dominant and secondary trait, and confidence from 0 to 1.
runner_upThe next closest season. Worth showing when confidence is low.
undertonewarm, cool or neutral, with the measured skin hue angle in degrees (higher is more golden).
contrastlow, medium or high, from the lightness gap between hair and skin.
scoresThe three axes from -1 to 1: temperature (warm is positive), value (light is positive), chroma (bright is positive).
measuredSkin, hair and eye colors as hex and CIELAB, each with its source: pixels (measured), model (estimated) or user (from your params).
palettebest, neutrals and avoid as { name, hex } lists, metals, and lips and blush shades.
qualityok is false when lighting, makeup, dyed hair or a filter make the result less reliable; warnings says why.

Example

Output of this API's own code on a sample photo. Values will differ for your photos.

{
  "metadata": {
    "id": "req_9cf4da08fe7f40dab71a",
    "engine": "color",
    "status": "success",
    "cached": false,
    "credits_used": 1,
    "created_at": "2026-10-19T09:30:00.000Z",
    "processing_ms": 3400
  },
  "summary": "Bright Spring, warm undertone, high contrast",
  "season": {
    "id": "bright_spring",
    "name": "Bright Spring",
    "family": "Spring",
    "dominant": "bright",
    "secondary": "warm",
    "confidence": 0.58
  },
  "runner_up": {
    "id": "warm_spring",
    "name": "Warm Spring"
  },
  "undertone": {
    "label": "warm",
    "skin_hue_angle": 59.8
  },
  "contrast": {
    "label": "high",
    "hair_skin_delta_l": 43.7
  },
  "scores": {
    "temperature": 0.47,
    "value": -0.18,
    "chroma": 0.38
  },
  "measured": {
    "skin": {
      "hex": "#c99a7b",
      "lab": {
        "L": 67.2,
        "a": 13.4,
        "b": 23
      },
      "source": "model"
    },
    "hair": {
      "hex": "#4a3326",
      "lab": {
        "L": 23.6,
        "a": 8.5,
        "b": 12.4
      },
      "source": "model"
    },
    "eyes": {
      "hex": "#4a342b",
      "lab": {
        "L": 23.8,
        "a": 8.6,
        "b": 9.1
      },
      "source": "pixels"
    },
    "white_balance": "none"
  },
  "palette": {
    "best": [
      {
        "name": "Hot coral",
        "hex": "#ff5a4f"
      },
      {
        "name": "Poppy red",
        "hex": "#e8352e"
      },
      {
        "name": "Bright turquoise",
        "hex": "#00c4b3"
      },
      {
        "name": "Lime",
        "hex": "#9ed84a"
      },
      {
        "name": "Sunflower",
        "hex": "#ffcc1d"
      },
      {
        "name": "Bright aqua",
        "hex": "#14d2dc"
      },
      {
        "name": "Warm fuchsia",
        "hex": "#e63e8a"
      },
      {
        "name": "Clear violet",
        "hex": "#7d4fd6"
      },
      {
        "name": "Emerald",
        "hex": "#11a879"
      },
      {
        "name": "Bright periwinkle",
        "hex": "#6f86f0"
      },
      {
        "name": "Orange",
        "hex": "#ff8a1f"
      },
      {
        "name": "Watermelon",
        "hex": "#f25c78"
      }
    ],
    "neutrals": [
      {
        "name": "Bright white",
        "hex": "#fbfbf7"
      },
      {
        "name": "Navy",
        "hex": "#22356e"
      },
      {
        "name": "Warm charcoal",
        "hex": "#4a4440"
      },
      {
        "name": "Camel",
        "hex": "#c49b6c"
      },
      {
        "name": "Chocolate",
        "hex": "#5b3626"
      }
    ],
    "avoid": [
      {
        "name": "Dusty rose",
        "hex": "#c4a3a3"
      },
      {
        "name": "Mushroom",
        "hex": "#a39587"
      },
      {
        "name": "Olive",
        "hex": "#6b6b3a"
      },
      {
        "name": "Muted mauve",
        "hex": "#9c8494"
      },
      {
        "name": "Rust",
        "hex": "#8f4a2a"
      }
    ],
    "metals": [
      "bright yellow gold",
      "polished silver"
    ],
    "lips": [
      {
        "name": "Coral red",
        "hex": "#f04a3e"
      },
      {
        "name": "Watermelon",
        "hex": "#e94e6a"
      },
      {
        "name": "Bright pink",
        "hex": "#e8507f"
      }
    ],
    "blush": [
      {
        "name": "Coral",
        "hex": "#f47c6e"
      },
      {
        "name": "Warm pink",
        "hex": "#f38aa0"
      }
    ]
  },
  "quality": {
    "ok": false,
    "warnings": [
      "Skin color is an estimate, not a measurement. Send a JPEG for measured colors."
    ]
  }
}