API-reference · Embeddings

Create embeddings

POSThttps://api.stav.ai/v1/embeddings

Generates vector embeddings for one or more inputs. Drop-in for the OpenAI SDK.

Anmodningapplication/json

modelstringpåkrævet
inputstring | array of stringpåkrævet
encoding_formatenum
floatbase64
Standard: "float"
dimensionsinteger
Truncate to this many dimensions (Matryoshka-style). Sent only to a Provider Endpoint measured to honour it; refused by name (400 unsupported_parameter) when none does.
userstring
providerobject
Stav extension, region per request. Narrows where this one request may run and which Inference Providers may serve it, on top of your workspace policy — it can only narrow, never widen. It filters Provider Endpoints: the serving endpoint and every failover stay inside it, and when no endpoint of the model passes, the request is refused (403 endpoint_not_admissible, or provider_blocked when every endpoint is on a provider you named in ignore) and nothing is sent. A provider pinned in the model id (creator/model/provider) that the filter excludes is 400 invalid_value with param provider.

Any other key is refused by name (400 unsupported_parameter, param provider.<key>). Never forwarded to a provider.
Vis 4 underfelter
- runs_instring | array of string
  Where the request may run: "eu", "eea", one ISO 3166 alpha-2 country code, or a list of country codes (["NO", "SE"]). One region or countries, not both in one list. global endpoints satisfy no region, so most Claude and Gemini endpoints are excluded by "eu".
- regionstring | array of string
  Alias of runs_in, same meaning. Not a provider region code — those are chosen in the model id (creator/model/provider:<code>). Sending both with different values is 400 invalid_value.
- onlyarray of string
  Only endpoints of these Inference Providers serve (slugs, as listed by GET /v1/models/{model_id}/endpoints). Applies to the endpoint, whoever the model's provider of record is. An unknown slug is 400 invalid_value.
- ignorearray of string
  No endpoint of these Inference Providers serves (slugs).

Noter

POST https://api.stav.ai/v1/embeddings takes the same request as OpenAI's embeddings endpoint.

Request

Field	Type	Notes
`model`	string	Required. An embedding model from the catalogue.
`input`	string or array of strings	Required. Must not be empty.
`encoding_format`	`float` or `base64`	Default `float`.
`dimensions`	integer	A shorter vector than the model's native size. Honoured by the Provider Endpoint, not only the model: Stav sends it only to an endpoint that was measured to honour it, and refuses by name (`400 unsupported_parameter`, `param: dimensions`) when none of the model's endpoints your workspace can use does.
`user`	string	Accepted.

Any other field is refused by name with 400, as on chat and rerank. It is never dropped. provider is not supported on embeddings yet (400 unsupported_parameter, param: provider): to use one Inference Provider, put it in the model id as creator/model/provider.

Response

{
  "object": "list",
  "data": [{ "object": "embedding", "index": 0, "embedding": [0.012, -0.034, "..."] }],
  "model": "mistral/mistral-embed",
  "usage": { "prompt_tokens": 9, "total_tokens": 9 }
}

How it differs from chat

Name the model. auto and Routers do not apply; Routers serve the chat surfaces only.
Commercial Inference Providers only. Embeddings are served through provider connectors. A model with no priced Provider Endpoint is refused.
Your key needs the inference:embeddings scope. Without it: 403 insufficient_scope.
Billing is the same, plus a per-request price where the endpoint has one. Input tokens are charged at catalogue price. Some embedding endpoints are priced per request instead of, or as well as, per token; that amount is shown on the model page ("€0.001 / request") and charged once per call, from the same tariff, as its own line in your usage. An empty balance blocks paid requests. See Credits and billing.

Errors

Status	When
`400`	`input` is empty, or the body has a field not listed above. The message names the field.
`400 unsupported_parameter`	`provider` was sent. Pin the Inference Provider in the model id (`creator/model/provider`) instead.
`400 unsupported_parameter`	`dimensions` was sent, and no endpoint of the model your workspace can use honours it (or the pinned endpoint does not). Leave it out, or pick another model.
`403`	The key lacks `inference:embeddings`
`404 model_not_found`	The model is not an embedding model, or has no priced Provider Endpoint. The message lists the embedding models available.
`402`	Not enough credits, or a spend limit was reached
Provider status	The provider refused the request; its message is passed through as `provider_error`

Full catalogue: Errors.

Svarheadere

Header	Betydning
`X-RateLimit-Limit`	Per-minute request cap on this key.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp (seconds) when the current window rolls over.

Fejl

Status	Hvornår
400	Invalid request — malformed JSON, missing required fields, or invalid parameter values.
401	Missing or invalid API key.
404	Model id is not in the catalogue, or the caller's key doesn't have access to it.
429	Per-key or per-IP rate limit exceeded.

Alle fejlkoder, hvad de betyder, og hvad du skal gøre: Fejl.

curl -X POST https://api.stav.ai/v1/embeddings \
  -H "Authorization: Bearer $STAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-embedding-2",
    "input": "Sovereignty is not a feature, it is a contract."
  }'

Svar · 200

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0
      ]
    }
  ],
  "model": "string",
  "usage": {}
}

API-reference · Embeddings

Create embeddings

POSThttps://api.stav.ai/v1/embeddings

Generates vector embeddings for one or more inputs. Drop-in for the OpenAI SDK.

Anmodningapplication/json

modelstringpåkrævet
inputstring | array of stringpåkrævet
encoding_formatenum
floatbase64
Standard: "float"
dimensionsinteger
Truncate to this many dimensions (Matryoshka-style). Sent only to a Provider Endpoint measured to honour it; refused by name (400 unsupported_parameter) when none does.
userstring
providerobject
Stav extension, region per request. Narrows where this one request may run and which Inference Providers may serve it, on top of your workspace policy — it can only narrow, never widen. It filters Provider Endpoints: the serving endpoint and every failover stay inside it, and when no endpoint of the model passes, the request is refused (403 endpoint_not_admissible, or provider_blocked when every endpoint is on a provider you named in ignore) and nothing is sent. A provider pinned in the model id (creator/model/provider) that the filter excludes is 400 invalid_value with param provider.

Any other key is refused by name (400 unsupported_parameter, param provider.<key>). Never forwarded to a provider.
Vis 4 underfelter
- runs_instring | array of string
  Where the request may run: "eu", "eea", one ISO 3166 alpha-2 country code, or a list of country codes (["NO", "SE"]). One region or countries, not both in one list. global endpoints satisfy no region, so most Claude and Gemini endpoints are excluded by "eu".
- regionstring | array of string
  Alias of runs_in, same meaning. Not a provider region code — those are chosen in the model id (creator/model/provider:<code>). Sending both with different values is 400 invalid_value.
- onlyarray of string
  Only endpoints of these Inference Providers serve (slugs, as listed by GET /v1/models/{model_id}/endpoints). Applies to the endpoint, whoever the model's provider of record is. An unknown slug is 400 invalid_value.
- ignorearray of string
  No endpoint of these Inference Providers serves (slugs).

Noter

POST https://api.stav.ai/v1/embeddings takes the same request as OpenAI's embeddings endpoint.

Request

Field	Type	Notes
`model`	string	Required. An embedding model from the catalogue.
`input`	string or array of strings	Required. Must not be empty.
`encoding_format`	`float` or `base64`	Default `float`.
`dimensions`	integer	A shorter vector than the model's native size. Honoured by the Provider Endpoint, not only the model: Stav sends it only to an endpoint that was measured to honour it, and refuses by name (`400 unsupported_parameter`, `param: dimensions`) when none of the model's endpoints your workspace can use does.
`user`	string	Accepted.

Response

{
  "object": "list",
  "data": [{ "object": "embedding", "index": 0, "embedding": [0.012, -0.034, "..."] }],
  "model": "mistral/mistral-embed",
  "usage": { "prompt_tokens": 9, "total_tokens": 9 }
}

How it differs from chat

Name the model. auto and Routers do not apply; Routers serve the chat surfaces only.
Commercial Inference Providers only. Embeddings are served through provider connectors. A model with no priced Provider Endpoint is refused.
Your key needs the inference:embeddings scope. Without it: 403 insufficient_scope.
Billing is the same, plus a per-request price where the endpoint has one. Input tokens are charged at catalogue price. Some embedding endpoints are priced per request instead of, or as well as, per token; that amount is shown on the model page ("€0.001 / request") and charged once per call, from the same tariff, as its own line in your usage. An empty balance blocks paid requests. See Credits and billing.

Errors

Status	When
`400`	`input` is empty, or the body has a field not listed above. The message names the field.
`400 unsupported_parameter`	`provider` was sent. Pin the Inference Provider in the model id (`creator/model/provider`) instead.
`400 unsupported_parameter`	`dimensions` was sent, and no endpoint of the model your workspace can use honours it (or the pinned endpoint does not). Leave it out, or pick another model.
`403`	The key lacks `inference:embeddings`
`404 model_not_found`	The model is not an embedding model, or has no priced Provider Endpoint. The message lists the embedding models available.
`402`	Not enough credits, or a spend limit was reached
Provider status	The provider refused the request; its message is passed through as `provider_error`

Full catalogue: Errors.

Svarheadere

Header	Betydning
`X-RateLimit-Limit`	Per-minute request cap on this key.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp (seconds) when the current window rolls over.

Fejl

Status	Hvornår
400	Invalid request — malformed JSON, missing required fields, or invalid parameter values.
401	Missing or invalid API key.
404	Model id is not in the catalogue, or the caller's key doesn't have access to it.
429	Per-key or per-IP rate limit exceeded.

Alle fejlkoder, hvad de betyder, og hvad du skal gøre: Fejl.

curl -X POST https://api.stav.ai/v1/embeddings \
  -H "Authorization: Bearer $STAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-embedding-2",
    "input": "Sovereignty is not a feature, it is a contract."
  }'

Svar · 200

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0
      ]
    }
  ],
  "model": "string",
  "usage": {}
}