Skin shade and undertone

POST /v1/color/shade · $0.01 a call

Send a front-facing selfie. A vision model marks bare skin on the cheeks and forehead, and Truelens measures those colors from the pixels in CIELAB. Depth is the nearest of 10 fixed reference tones by lightness; undertone comes from the measured hue (warm, cool or neutral), with olive for skin that is golden but muted. The result gives the depth band and undertone family to look for in a foundation, and how to test it.

For makeup shade finders, beauty retail apps, skincare apps.

Request

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

This API takes no extra fields.

Photo tips. Bare skin, facing a window in daylight, no flash and no filter. JPEG gives measured colors; other formats fall back to estimates.

1curl https://truelens.keronlabs.com/v1/color/shade \
2  -H "Authorization: Bearer $TRUELENS_KEY" \
3  -F image=@portrait.jpg

Response

Field	Description
`summary`	One line, e.g. "Depth 5 of 10 (medium), warm undertone".
`depth`	step from 1 (lightest) to 10 (deepest), its band (fair, light, medium, tan, deep) and the reference tone as hex.
`undertone`	warm, cool, neutral or olive, the measured skin hue angle (higher is more golden) and the cues used.
`foundation`	The depth band and undertone family to shop for, and how to test a shade.
`measured`	The measured skin color as hex and CIELAB, and whether white balance was corrected.
`quality`	ok is false when light, makeup 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.

1{
2  "metadata": {
3    "id": "req_9cf4da08fe7f40dab71a",
4    "engine": "color/shade",
5    "status": "success",
6    "cached": false,
7    "credits_used": 1,
8    "created_at": "2026-10-19T09:30:00.000Z",
9    "processing_ms": 3400
10  },
11  "summary": "Depth 5 of 10 (medium), warm undertone",
12  "depth": {
13    "step": 5,
14    "of": 10,
15    "label": "medium",
16    "reference_hex": "#c99370"
17  },
18  "undertone": {
19    "label": "warm",
20    "skin_hue_angle": 59.8,
21    "cues": [
22      "skin hue angle 59.8 degrees"
23    ]
24  },
25  "foundation": {
26    "depth_band": "medium",
27    "undertone_family": "golden or yellow",
28    "how_to_test": "Pick three medium shades with golden or yellow undertones and swipe each in a short stripe along your jawline. Let them dry for a few minutes, then look in daylight by a window: the one that disappears into both your face and neck is your match."
29  },
30  "measured": {
31    "skin": {
32      "hex": "#c99a7b",
33      "lab": {
34        "L": 67.2,
35        "a": 13.4,
36        "b": 23
37      }
38    },
39    "white_balance": "none"
40  },
41  "quality": {
42    "ok": false,
43    "warnings": [
44      "Makeup on the skin changes the measured shade. Bare skin gives the truest result.",
45      "Skin color is an estimate, not a measurement. Send a JPEG for measured colors."
46    ]
47  }
48}