{
  "openapi": "3.1.1",
  "info": {
    "title": "Image Palette Extractor (k-means, median cut) API",
    "version": "1.0.0",
    "summary": "Pull a 2–32 color palette from a photo with k-means in OKLab, median cut or a histogram.",
    "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
  },
  "servers": [
    {
      "url": "https://luminapaletteextractor.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Pull a 2–32 color palette from a photo with k-means in OKLab, median cut or a histogram.",
        "description": "Upload a PNG, JPEG, WebP or GIF image and get its main colors with the share of the image each one covers, plus how well the palette represents the image. Download the palette as HEX, GIMP GPL, JASC-PAL, JSON, CSS variables or Adobe Swatch Exchange (ASE).\n\nMethodology:\n- The image is decoded to 8-bit sRGB and scaled so its longer side is at most 512 pixels; pixels with alpha below 128 are ignored. Up to 65,536 pixels are sampled on a fixed stride.\n- Median cut (Heckbert 1982) splits the colour box with the largest count-weighted error at the weighted median of its widest channel, then refines with four k-means passes in RGB — the same function Flipline Pixel Studio uses. Histogram groups colours into 32 levels per channel and keeps frequent bins that differ by at least about 42 RGB units — the same function as Lumina Palette Studio.\n- k-means starts from the median-cut colours and runs Lloyd iterations in OKLab, where distances follow perceived differences, until nothing changes (at most 24 passes). Centres outside sRGB are mapped back with the CSS Color 4 method.\n- Share = fraction of opaque sampled pixels whose nearest palette color (OKLab) is that color. Mean error = average OKLab distance × 100 from each pixel to its nearest palette color; lower is a better fit. Results are deterministic.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "lumina_palette_extractor",
        "x-owner-app": "lumina",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LuminaPaletteExtractorInput"
              },
              "examples": {
                "example1": {
                  "summary": "Four color fields (generated sample)",
                  "value": {
                    "image": {
                      "filename": "four-fields.png",
                      "contentType": "image/png",
                      "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAGAAAABACAYAAADlNHIOAAADHklEQVR42u3RWTabYQCA4W8PkuwINd5WixYtWorEPO/AGBFibOlNzVoUNfR0MoskMidEDDF02MHX86/A1Rvnz8nFs4H3FbrMF5JU+X4UdfcviLr92ooS8QGxPmB8BHX7N4C62WxFCV1mgSQZxkdQ/IAWlNBlFEgSPeDmjx91vdmC4geMDaPwARstKNUPuP7tQ0U2WlD4AP3YMAofsN6MErqMfEnSvxtGRe58qKv1ZlQUBgyhIndeVHzAfQNuvairtWaU0KXnSxI94OrWg7pca0IJbXq+JFW8HUTFBzzwgMsbD+riSxNKaNPzJIkf4Eapf8DoAOri2o06X21ExcAAF4ofkJYnSeWjA6jziAsVXm1E8QNGBlDnEScqvNKIEtq055JUPmJBha+cqLOVBlR8QKwPKBu2oMKXx6iz5QZUFAb0o86USKDQcgNK/QMuHKjQcj1KaFOfSVLZUD8qpEQCnX6uR0VhQB8qdGFHqX7Am6E+1Om5HXWyVI+KD4j5AYNm1EnYhgou1aHiA+4bsFiHEtrUXEkqHTSjTs6OUPyAlFxJKh0wo4JKJFBgsQ4VhQG9qGDIigos1KJUPyCgRAL5F2pR/ABLLypwakVFYUCOJJVYTCj/6SHK96kWJTQpOZKk/gE1KH5AvwnlOzlAeT/WoITmUY4klfT3oOIDHniAN3jA4gdkS9Lrvh6UN7iP8sxXo9Q/ILCPioEBRpQnsIdyz1ej+AFmI8rj30O556pRQpOcLUmvzEaU27+Lcs1VoaIwoBvl9u2iXLNVKKFJfipJ9ACXEgnknK1C8QN6u1Eu3w4qBgZ0oZzeHdZMJQofUNzbhXJ6t1HHM5UofoCpC+X0bKP4AUlPJKnY1Ik69myhHNOVKPUPcG+hVD+gqKcT5VAigezTBpT6B7h+oexTBlQUBnSg7EokkG3KgBKapCxJKjJ2oOzOnyjbpAGl+gE2JRLoaFKPEprELEkqNLajbMc/UOof0N2OOlIikSb0KJGQmCVJah9gndCjRELiY0kq7G5DHTm+o6wTFSjVD7AqkUCHHypQ+ICXXW0oq/0bih7wHxkxj/COypjgAAAAAElFTkSuQmCC"
                    },
                    "method": "kmeans",
                    "count": 4,
                    "name": "Four fields"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LuminaPaletteExtractorResult"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid input (see errors[]).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tool": {
      "get": {
        "operationId": "getToolDefinition",
        "summary": "Inputs, output schema and examples for this tool",
        "responses": {
          "200": {
            "description": "Tool definition.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "LuminaPaletteExtractorInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "image": {
            "title": "Image (PNG, JPEG, WebP or GIF; up to 25 MB)",
            "type": "object",
            "description": "Upload as {filename, contentType?, contentBase64}. Max 24414 KiB. Accepts .png,.jpg,.jpeg,.webp,.gif.",
            "additionalProperties": false,
            "required": [
              "filename",
              "contentBase64"
            ],
            "properties": {
              "filename": {
                "type": "string"
              },
              "contentType": {
                "type": "string"
              },
              "contentBase64": {
                "type": "string"
              }
            }
          },
          "method": {
            "title": "Method",
            "type": "string",
            "enum": [
              "kmeans",
              "median-cut",
              "histogram"
            ],
            "default": "kmeans"
          },
          "count": {
            "title": "Number of colors",
            "type": "integer",
            "minimum": 2,
            "maximum": 32,
            "default": 6
          },
          "name": {
            "title": "Palette name",
            "type": "string",
            "maxLength": 80,
            "default": "Image palette"
          }
        },
        "required": [
          "image"
        ]
      },
      "LuminaPaletteExtractorResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "tool",
          "computedAt",
          "inputs",
          "summary",
          "result",
          "units",
          "assumptions",
          "sources",
          "warnings",
          "presentation",
          "links"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1.0"
          },
          "tool": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "version"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "description": "Normalised inputs actually used, including applied defaults."
          },
          "summary": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "method",
              "colors",
              "width",
              "height",
              "sampledPixels",
              "opaquePixels",
              "meanErrorOK",
              "exports",
              "ase"
            ],
            "properties": {
              "method": {
                "type": "string"
              },
              "width": {
                "type": "integer"
              },
              "height": {
                "type": "integer"
              },
              "sampledPixels": {
                "type": "integer"
              },
              "opaquePixels": {
                "type": "integer"
              },
              "meanErrorOK": {
                "type": "number"
              },
              "colors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "hex",
                    "share"
                  ],
                  "properties": {
                    "hex": {
                      "type": "string"
                    },
                    "share": {
                      "type": "number"
                    }
                  }
                }
              },
              "exports": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "hex",
                  "gpl",
                  "jasc",
                  "json",
                  "css"
                ],
                "properties": {
                  "hex": {
                    "type": "string"
                  },
                  "gpl": {
                    "type": "string"
                  },
                  "jasc": {
                    "type": "string"
                  },
                  "json": {
                    "type": "string"
                  },
                  "css": {
                    "type": "string"
                  }
                }
              },
              "ase": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "artifactId",
                  "filename",
                  "mime",
                  "bytes",
                  "sha256",
                  "path"
                ],
                "properties": {
                  "artifactId": {
                    "type": "string"
                  },
                  "filename": {
                    "type": "string"
                  },
                  "mime": {
                    "type": "string"
                  },
                  "bytes": {
                    "type": "integer"
                  },
                  "sha256": {
                    "type": "string"
                  },
                  "path": {
                    "type": "string",
                    "description": "Download path on the same site (valid for about 2 hours)."
                  }
                }
              }
            }
          },
          "units": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "retrievedAt": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "presentation": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Display blocks used by the human page (same data)."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "human",
              "api",
              "openapi",
              "methodology"
            ],
            "properties": {
              "human": {
                "type": "string",
                "format": "uri"
              },
              "api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}