Create embeddings

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

Header parameters

• X-Stav-Runs-Instring

  Where this request may run, as a header: eu, eea, one ISO 3166 alpha-2 country code, or a comma-separated list of codes (NO, SE). The same values and the same meaning as the provider.runs_in body field, for clients that can set fixed headers but not body fields (an SDK's default_headers). It filters the Provider Endpoints that may serve and every failover; when none passes, the request is refused (403 endpoint_not_admissible) and nothing is sent.

  It only ever narrows. Sent together with provider.runs_in, both must hold: X-Stav-Runs-In: eea with "runs_in": "NO" runs in Norway; X-Stav-Runs-In: eu with "runs_in": "NO" or "US" has no country in common and is 400 invalid_value. It never widens your workspace policy. A value Stav cannot read, an empty one, or two header lines with different values is 400 invalid_value with param X-Stav-Runs-In; the same value sent twice counts once. The request log shows the region with its source.

  GET /v1/models lists only models with an endpoint inside it, and a Router or auto only when at least one of its candidates has one (without a key, auto is not listed under the header); GET /v1/models/{model_id}/endpoints lists only those endpoints. /v1/messages/count_tokens reads it too: when the provider's own counter is outside it, the count is a local estimate and the prompt is never sent. The response header X-Stav-Token-Count says exact or estimate. Reading or cancelling a stored response (GET /v1/responses/{id}, /input_items, /cancel) held by an endpoint outside it is refused with 403 endpoint_not_admissible; DELETE is not refused, so data held outside the region can always be erased.

Request bodyapplication/json

• modelstringrequired
• inputstring | array of stringrequired
• encoding_formatenum
  floatbase64
  Default: "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.

  Show 4 child fields

  • 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". The X-Stav-Runs-In header takes the same values; sent with this field, both must hold.

  • 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).

Notes

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

Request

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, "cost": 0.00000018, "cost_currency": "EUR" }
}

usage.cost is what your wallet is charged for the request, in your workspace's currency (usage.cost_currency), from Stav's own ledger: the input tokens at catalogue price, plus the endpoint's per-request price where Stav charges one. X-Stav-Cost and X-Stav-Cost-Currency carry the same number. When your workspace's own provider key (BYOK) served the call, it is the platform fee alone, or 0 under the free allowance — as on chat. Both fields are absent when the cost could not be quoted; never an estimate.

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

Full catalogue: Errors.

Response headers

Errors

Every error code, what it means and what to do: Errors.