K-means assign step API

Performs one k-means iteration: assigns vectors to the nearest centroids (euclidean/cosine), recomputes centroids, and reports inertia and cluster sizes. Answers 'How do I assign embeddings to centroids?', 'What is one k-means update step?'.

Price$0.03per request

MethodPOST

Route/v1/retrieval/kmeans-assign

StatusLive

MIME typeapplication/json

Rate limit120/minute

Cache0s public

kmeansclusteringcentroidassigninertiavectorembeddingrag

API URLhttps://x402.hexl.dev/v1/retrieval/kmeans-assign

Integration docs

Example request

{
  "vectors": [
    [
      0,
      0
    ],
    [
      1,
      1
    ],
    [
      10,
      10
    ],
    [
      11,
      11
    ]
  ],
  "centroids": [
    [
      0,
      0
    ],
    [
      10,
      10
    ]
  ]
}

Example response

{
  "metric": "euclidean",
  "assignments": [
    {
      "cluster": 0,
      "distance": 0
    },
    {
      "cluster": 0,
      "distance": 1.41421356
    },
    {
      "cluster": 1,
      "distance": 0
    },
    {
      "cluster": 1,
      "distance": 1.41421356
    }
  ],
  "newCentroids": [
    [
      0.5,
      0.5
    ],
    [
      10.5,
      10.5
    ]
  ],
  "clusterSizes": [
    2,
    2
  ],
  "inertia": 3.99999999,
  "k": 2
}

Input schema

{
  "type": "object",
  "required": [
    "vectors",
    "centroids"
  ],
  "properties": {
    "vectors": {
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "type": "number"
        }
      }
    },
    "centroids": {
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "type": "number"
        }
      }
    },
    "metric": {
      "type": "string",
      "enum": [
        "euclidean",
        "cosine"
      ]
    }
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}