# Embeddings

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

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](conventions.md#rate-limits) |

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](account.md#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](files-and-media.md#organizations-and-credits).
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](authentication.md#authentication-errors). |
| `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](conventions.md#errors).

### 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
}
```
