Docs · Native API
Embeddings
Turns text into vectors.
POST/api/v1/embeddings#
- Auth: your API key. A key whose account group has no API access is refused with
401. - Limit: 30 requests per minute per account by default, on the counter that the other limited endpoints share. See rate limits and quotas.
- Body: JSON, with
Content-Type: application/json.
curl -s "$SHVIA_URL/api/v1/embeddings" \
-H "Authorization: Bearer $SHVIA_API_KEY" -H "Content-Type: application/json" \
-d '{ "input": ["How do I restart the service?", "Where are the logs?"] }'{
"embeddings": [
[0.0123, -0.0456, 0.0789],
[0.0101, -0.0222, 0.0333]
],
"model": "nomic-embed-text",
"server": "…",
"server_label": "…",
"dimensions": 768
}The vectors above are shortened: a real vector has dimensions numbers. server and server_label name the server that embedded the text. Their values belong to the installation.
Request#
| Field | Notes |
|---|---|
input | required. A string, or an array of strings. Each item must be a non-empty string. At most 64 items, and 8000 characters per item, by default |
server | optional string, up to 64 characters: the key of one of the operator's own servers, which is what embeds. Cloud providers are refused. Leave it out to use the installation's default server, and ask the operator if you need to pick another |
You cannot choose the embedding model: each server has the one that the operator configured for it. Choosing a server therefore chooses the model and the size of the vectors, so read dimensions and model from the response, and do not mix vectors from different models in one index.
Response#
embeddings is always an array of vectors, even for one input, in the order of the inputs. There is no token count, and the call is not counted against your token quota.
Errors#
| Status | Body | When |
|---|---|---|
| 401 | {"message": "Unauthenticated."} | the credential is not valid |
| 400 | {"detail": "…"} | the server is unknown or disabled |
| 403 | {"detail": "…"} | a session token whose account group has no API access. A key in that situation gets 401 |
| 422 | {"message", "errors": {…}} | input is missing or empty |
| 422 | {"detail": "…"} | an item is empty, there are too many items, or an item is too long |
| 429 | {"message": "Too Many Attempts."} | request limit reached |
| 502 | {"detail": "…"} | the embedding server could not be reached or failed |
| 503 | {"detail": "…"} | the embedding server is offline |
Notice that 422 has two shapes on this endpoint: switch on the status, then read errors if it is present and detail otherwise.