Embeddings

The embeddings endpoint converts text into a fixed-length vector of floating-point numbers. Those numbers capture the semantic meaning of the text so you can compare it to other vectors, cluster documents, build semantic search, and feed your own downstream models. The endpoint is OpenAI-compatible, so any client or library that already calls /v1/embeddings works by changing only the base URL and the API key.

Sending a request

The endpoint accepts POST /v1/embeddings with a JSON body. Authenticate with your API key as a bearer token:

curl https://api.akumi.cloud/v1/embeddings \
  -H "Authorization: Bearer wk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral/mistral-embed",
    "input": "The quarterly report is ready for review."
  }'

The response looks like this:

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.01, -0.02] }
  ],
  "model": "mistral/mistral-embed",
  "usage": { "prompt_tokens": 7, "total_tokens": 7 }
}

Required fields

Optional fields

Batch requests

Set input to a non-empty array of strings to embed multiple texts in one call:

{
  "model": "mistral/mistral-embed",
  "input": ["First document.", "Second document.", "Third document."]
}

The response contains one embedding object per input string, in the same order, each with its own index.

Available models

External models are not disabled by default; every request to one is checked by the fail-closed egress guard. Before you can route a request to one, an organisation admin must record the non-EU-routing acceptance on the Router settings page. This is the same acceptance used for external chat models, so if your organisation has already accepted, external embedding models are available without any additional step. Without the acceptance, the egress guard rejects the request.

Pricing

Embeddings are metered per input token, using the model's per-1,000-token rate. There are no output tokens for embeddings. Charges appear on the Usage page as an embeddings line, separate from chat completions.

Why the PII firewall does not apply

The PII firewall pseudonymises personal data in the request, routes it through the model, and then restores the original values in the generated text. This pattern cannot be applied to embeddings for three reasons.

First, pseudonymising the input before embedding would embed the wrong text. The vector would represent the pseudonymised version, not the original document, making it semantically incorrect and incomparable to vectors produced without pseudonymisation.

Second, embeddings return a vector, not generated text. There is nothing to restore personal data into.

Third, the token map that links placeholders to real values is created fresh for each request. The same named entity maps to a different placeholder across calls, so vectors for the same content would not be comparable to one another.

Embeddings are therefore governed by residency rather than the firewall. The EU model (mistral/mistral-embed) keeps all text within the EU with no transfer. External models are gated by the egress guard and available only with the recorded acceptance. The firewall's absence here is not a governance gap; it is the correct model for this data type.

Good to know

The default model is EU-sovereign. mistral/mistral-embed keeps all text within the EU and requires no additional setup or acceptance.

External models are gated by the egress guard. An admin must record the non-EU-routing acceptance before any external embedding model can be used. The egress guard rejects the request otherwise.

Restricted keys need the embeddings.create scope. Organisation keys include it by default. Restricted keys must have the scope ticked when they are created.

Dimensions reduction is model-specific. Only models with native reduction (the OpenAI text-embedding-3 models) accept a smaller dimensions. Asking a model that cannot reduce for a non-native size, or any model for a size above its native dimension, returns a 400.

Embeddings have no output tokens. Usage is charged on input tokens only and appears as a separate line on the Usage page.