{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Skin Color visual simulation API","version":"1.0.0","description":"Runs the website’s visual skin-palette simulation. The six arbitrary swatch positions are averaged across known family entries with equal weight, then a bell curve of fixed width 1 is normalized and rounded. These are design choices, not genetic measurements or validated individual probabilities. Unknown entries are omitted; an entirely unknown family yields needs_input and no distribution. Inputs are processed in memory, without application storage, logging or outgoing requests; responses do not echo the family and are not cached."},"servers":[{"url":"https://www.skin-color.com"}],"externalDocs":{"description":"Usage, model rules and canonical resources","url":"https://www.skin-color.com/for-ai-assistants"},"paths":{"/api/v1/predict":{"post":{"operationId":"calculateSkinToneSimulation","summary":"Calculate the visual skin-tone distribution","description":"Public endpoint without a key or cookies. No special User-Agent is required. Send UTF-8 JSON (at most 1024 bytes) in the body, not in URL query parameters. Colors use the documented uppercase codes. Invalid or extra properties are rejected; errors are in English. The browser calculator continues to compute locally.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionRequest"},"example":{"family":{"mother":"FAIR","father":"BROWN"},"locale":"en"}}}},"responses":{"200":{"description":"Distribution calculated, or more input is needed.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionResponse"},"examples":{"calculated":{"value":{"apiVersion":"1","modelVersion":"skin-palette-v1","purpose":"entertainment","scientificallyValidated":false,"locale":"en","status":"ok","unit":"percent","results":[{"color":"VERYFAIR","label":"Very light","percentage":1.76},{"color":"FAIR","label":"Light","percentage":12.97},{"color":"MEDIUM","label":"Medium","percentage":35.27},{"color":"OLIVE","label":"Olive","percentage":35.27},{"color":"BROWN","label":"Dark","percentage":12.97},{"color":"BLACK","label":"Very dark","percentage":1.76}],"explanation":"For fun: these percentages are weights from an arbitrary mathematical curve, not measured genetic chances for your baby.","sourceUrl":"https://www.skin-color.com/","documentationUrl":"https://www.skin-color.com/for-ai-assistants"}},"needsInput":{"value":{"apiVersion":"1","modelVersion":"skin-palette-v1","purpose":"entertainment","scientificallyValidated":false,"locale":"en","status":"needs_input","unit":"percent","results":null,"explanation":"Choose at least one skin tone to explore the simulation. No result is shown while all tones are unknown.","sourceUrl":"https://www.skin-color.com/","documentationUrl":"https://www.skin-color.com/for-ai-assistants"}}}}}},"400":{"description":"Send family colors in the JSON body, without URL query parameters. Send a valid UTF-8 JSON object.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"The JSON body must not exceed 1024 bytes.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"Use Content-Type: application/json and an uncompressed UTF-8 body.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Provide a family object using the documented fields and uppercase color codes, and an optional supported locale. Additional fields are not accepted.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"The calculation could not be completed.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"options":{"operationId":"skinColorApiCors","summary":"CORS preflight","responses":{"204":{"description":"POST allowed with Content-Type: application/json. No cookies or credentials.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}}}}}}},"components":{"schemas":{"SkinColor":{"type":"string","enum":["VERYFAIR","FAIR","MEDIUM","OLIVE","BROWN","BLACK","UNDEFINED"],"description":"UNDEFINED means unknown. Other codes are illustrative swatch codes, not genetic measurements or ancestry categories."},"PredictionRequest":{"type":"object","additionalProperties":false,"required":["family"],"properties":{"family":{"type":"object","additionalProperties":false,"description":"Omitted colors default to UNDEFINED; no parent or grandparent color is mandatory.","properties":{"mother":{"$ref":"#/components/schemas/SkinColor","default":"UNDEFINED"},"father":{"$ref":"#/components/schemas/SkinColor","default":"UNDEFINED"},"maternalGrandmother":{"$ref":"#/components/schemas/SkinColor","default":"UNDEFINED"},"maternalGrandfather":{"$ref":"#/components/schemas/SkinColor","default":"UNDEFINED"},"paternalGrandmother":{"$ref":"#/components/schemas/SkinColor","default":"UNDEFINED"},"paternalGrandfather":{"$ref":"#/components/schemas/SkinColor","default":"UNDEFINED"}}},"locale":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"],"default":"en","description":"Response labels and explanation language. Does not alter the calculation."}}},"ColorResult":{"type":"object","additionalProperties":false,"required":["color","label","percentage"],"properties":{"color":{"type":"string","enum":["VERYFAIR","FAIR","MEDIUM","OLIVE","BROWN","BLACK"]},"label":{"type":"string","minLength":1},"percentage":{"type":"number","minimum":0,"maximum":100}}},"PredictionResponse":{"oneOf":[{"type":"object","additionalProperties":false,"required":["apiVersion","modelVersion","purpose","scientificallyValidated","locale","unit","explanation","sourceUrl","documentationUrl","status","results"],"properties":{"apiVersion":{"type":"string","const":"1"},"modelVersion":{"type":"string","const":"skin-palette-v1"},"purpose":{"type":"string","const":"entertainment"},"scientificallyValidated":{"type":"boolean","const":false},"locale":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]},"unit":{"type":"string","const":"percent"},"explanation":{"type":"string","minLength":1},"sourceUrl":{"type":"string","format":"uri"},"documentationUrl":{"type":"string","format":"uri"},"status":{"const":"ok"},"results":{"type":"array","minItems":6,"maxItems":6,"uniqueItems":true,"description":"One entry for each of the six known swatches, including rounded zero values. Percentages total 100 within the visual model.","items":{"$ref":"#/components/schemas/ColorResult"}}}},{"type":"object","additionalProperties":false,"required":["apiVersion","modelVersion","purpose","scientificallyValidated","locale","unit","explanation","sourceUrl","documentationUrl","status","results"],"properties":{"apiVersion":{"type":"string","const":"1"},"modelVersion":{"type":"string","const":"skin-palette-v1"},"purpose":{"type":"string","const":"entertainment"},"scientificallyValidated":{"type":"boolean","const":false},"locale":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]},"unit":{"type":"string","const":"percent"},"explanation":{"type":"string","minLength":1},"sourceUrl":{"type":"string","format":"uri"},"documentationUrl":{"type":"string","format":"uri"},"status":{"const":"needs_input"},"results":{"type":"null"}}}]},"ApiError":{"type":"object","additionalProperties":false,"required":["apiVersion","error"],"properties":{"apiVersion":{"type":"string","const":"1"},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["query_parameters_not_allowed","invalid_json","invalid_request","request_too_large","unsupported_media_type","method_not_allowed","internal_error"]},"message":{"type":"string","enum":["Send family colors in the JSON body, without URL query parameters.","Send a valid UTF-8 JSON object.","Provide a family object using the documented fields and uppercase color codes, and an optional supported locale. Additional fields are not accepted.","The JSON body must not exceed 1024 bytes.","Use Content-Type: application/json and an uncompressed UTF-8 body.","Use POST with a JSON body.","The calculation could not be completed."]}}}}}}}}