Embeddings

Implementation target. This guide specifies the intended product surface. The current frontend uses local samples; it does not call an inference service or collect funds. An endpoint is enabled only after its adapter, ownership, usage, and payment behavior are qualified.

Planned API origin. Examples use https://noemad.dev/v1, the intended product API path. The API is not connected in this frontend preview. MODEL_ID_FROM_DISCOVERY and NOEMAD_API_KEY are placeholders, not published credentials or model IDs. A product API key identifies an account; a separate payment-aware transport must handle spending authorization.

An endpoint for indexed vectors

POST /v1/embeddings accepts one string or a bounded batch and returns one vector per input in stable order. Discover compatible models with GET /v1/models?type=embedding; a chat model is not automatically an embedding model.

The reference target accepts up to 64 strings per request. Per-item, aggregate size, and token limits must also be enforced by the qualified adapter.

Archived embedding models

Model specification reference. Names and capability limits come from the imported catalog snapshot. Enabled models require fresh qualification. USD rates below are listed only when verified for the exact model against an official source; unverified prices are marked.

Request

{
  "model": "MODEL_ID_FROM_DISCOVERY",
  "input": [
    "A document about semantic search.",
    "A note about finding related ideas."
  ],
  "encoding_format": "float",
  "input_type": "document",
  "dimensions": 1024
}

The archived Voyage 4 series supports 256, 512, 1024, or 2048 dimensions. Finance and law records use 1024. Other archived models retain their native dimension. These values need fresh adapter qualification before becoming live product choices.

Response validation

{
  "object": "list",
  "model": "MODEL_ID_FROM_DISCOVERY",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.012,
        -0.034,
        0.021
      ]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [
        0.028,
        0.017,
        -0.009
      ]
    }
  ],
  "usage": {
    "item_count": 2,
    "dimensions": 3,
    "encoding_format": "float"
  }
}

The vectors above are shortened illustrative values, not real embeddings. Validate one output index for every input, the exact selected dimension, finite numeric values, and the declared encoding. A missing item is an incomplete result.

Batching and retrieval

1. 1
   Chunk and normalize documents consistently.
2. 2
   Embed bounded batches with the document mode when supported.
3. 3
   Store the model, version, dimension, and normalization method alongside each vector.
4. 4
   Embed the query using a compatible query mode and dimension.
5. 5
   Retrieve candidates, then optionally rerank them.

Do not mix vectors from different models or dimensions in the same comparison space. Reindex when the representation changes. Retrying a batch preserves operation identity and indexes; it must not double-charge already delivered work.

Token and byte units are distinct

Embedding billing must follow the selected hosted provider’s official USD unit. Tokenization and any UTF-8 counting rules are adapter-specific; a local byte count is not an exact token count for another model.

Use the quote’s pinned unit and any verified minimum, then settle reliable attributable usage. The billing reference shows verified USD rates and clearly marks prices that could not be established. The final USDC payment terms come from a fresh quote.