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
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}'
{
"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
}