Endpoints

Embeddings

Turn a batch of texts into embedding vectors for search, clustering and classification.

View as Markdown

An embedding is a list of numbers (a vector) that represents the meaning of a text: texts with a similar meaning have vectors that are close to each other. Use them to build your own semantic search, deduplication, clustering or classification. The endpoint takes a batch of texts and returns one vector for each.

Create embeddings

Endpoint POST /api/v3/embeddings
Scope ayeto.embeddings
Rate limit high

Send the texts in input; data of the response holds one vector per text, in the same order. Send as many texts per request as the limits allow rather than one request per text: it is faster and counts once against the rate limit.

Models and vector size

model Largest vector Use
small (default) 1,536 Fast and cheap, good for most search and clustering.
large 3,072 More precise, at a higher price.

dimensions sets the length of the returned vectors, from 1 to the largest vector of the model. Shorter vectors take less space and compare faster, at some loss of precision. Without dimensions the server default is used; the size actually used is returned in dimensions of the response. Vectors are only comparable with vectors of the same model and the same size, so store both next to your vectors and send dimensions explicitly when you depend on a size.

The vectors are normalized to length 1, so the dot product of two vectors equals their cosine similarity.

Limits

Limit Default
Texts per request 256
Characters per text 16,000
Characters per request (all texts together) 1,000,000

The server can be configured with other limits. A request over a limit is refused with 422 and nothing is charged. A text must not be empty. Independently of the character limit the models read about 8,000 tokens per text; a text that is longer in tokens (possible for dense text such as code or some languages) is refused as well. Split long documents into passages before embedding them, which also gives better search results.

Billing

The request is charged at the price of the embedding model, by the amount of text sent. The credits it consumed are returned in credits, the tokens the model counted in tokens. Credits are checked before the texts are processed, see credits.

With organization_id the request runs in that organization and is paid from the user's credit there, the same way as for files and media. The key's user must be an admin or a member of the organization, not a guest.

A request is all or nothing: when it fails, no vectors are returned. Very large requests are processed in several parts, and a part that was already processed before the failure stays charged.

Request

Field Type Required Description
input array of strings Yes The texts, at least one, none of them empty.
model string No small or large. Default: small.
dimensions integer No Length of the vectors, 1 to the largest vector of the model. Default: the server default.
organization_id UUID No Run the request in this organization and charge it to the user's credit there. Default: none (personal credits).

Response

200 OK with:

Field Type Description
data array One item per text, in the order of input.
data[].index integer Position of the text in input, from 0.
data[].embedding array of numbers The vector.
model string The model used, small or large.
dimensions integer Length of every vector.
tokens integer Tokens the model counted in the texts.
credits number Credits the request consumed.

Errors

Status detail Cause
401 API key is invalid The key lacks the ayeto.embeddings scope, see authentication.
403 User is not a member of the organization organization_id is not one of the user's organizations.
403 User does not have write permissions in the organization The user is a guest in the organization.
422 too many inputs (<count>, at most <limit>) input has more texts than allowed.
422 input <index> is empty The text at that position is empty or only whitespace.
422 input <index> is too long (<length> characters, at most <limit>) The text at that position is over the character limit.
422 the inputs are too long together (<length> characters, at most <limit>) The texts together are over the request limit.
422 dimensions must be at most <limit> for this model dimensions is larger than the largest vector of the model.
422 the embedding model refused the input, a text is probably too long A text is longer than the model reads (about 8,000 tokens).
422 not enough user credit The user's personal credits are used up.
422 not enough organization credit With organization_id: the user's credit in the organization is used up.
422 validation error input is missing or empty, model is not small or large, or dimensions is below 1.
500 Failed to generate embeddings The model could not process the request. Retry later.

Authentication, rate limit and server errors are described in conventions.

Example

bash
curl -X POST "https://ayeto.ai/api/v3/embeddings" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": ["How do I reset my password?", "Opening hours of the Prague office"], "dimensions": 4}'
json
{
  "data": [
    {"index": 0, "embedding": [0.0213, -0.5132, 0.7411, 0.4326]},
    {"index": 1, "embedding": [-0.3391, 0.1207, 0.6614, -0.6579]}
  ],
  "model": "small",
  "dimensions": 4,
  "tokens": 14,
  "credits": 0.0001
}