# Embeddings

```
POST https://api.agentapi.ru/v1/ai/embeddings
```

Векторные представления текста — для семантического поиска, RAG и кластеризации.
Совместим с OpenAI Embeddings API.

## Параметры

| Параметр | Тип | Описание |
|---|---|---|
| `input` | string \| string[] | **Обязательный.** Текст или массив текстов |
| `model` | string | **Обязательный.** Модель с поддержкой embeddings, например `openai/text-embedding-3-small` |
| `encoding_format` | string | `float` (по умолчанию) или `base64` |
| `dimensions` | number | Размерность вектора, если модель это поддерживает |
| `input_type` | string | Подсказка типа входа: `query` или `document` |
| `user` | string | Идентификатор конечного пользователя |
| `provider` | object | Предпочтения роутинга |

> В отличие от остальных эндпоинтов, здесь **строгая валидация**: неизвестные поля
> вызывают `400`. Поддерживаются оба написания — `encoding_format` и `encodingFormat`,
> `input_type` и `inputType`.

## Пример запроса

```bash
curl https://api.agentapi.ru/v1/ai/embeddings \
  -H "x-api-key: agentapi-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": "Байкал — самое глубокое озеро в мире"
  }'
```

```python
from openai import OpenAI

client = OpenAI(
    api_key="agentapi-ВАШ_КЛЮЧ",
    base_url="https://api.agentapi.ru/v1/ai",
)

result = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=["Первый документ", "Второй документ"],
)

for item in result.data:
    print(item.index, len(item.embedding))
```

## Ответ

```json
{
  "id": "emb-1753601440-Lp7",
  "object": "list",
  "model": "openai/text-embedding-3-small",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [-0.0142, 0.0318, -0.0071, 0.0455, "…ещё 1532 значения"]
    }
  ],
  "usage": {
    "prompt_tokens": 11,
    "total_tokens": 11
  }
}
```

При массиве на входе элементы `data` идут в том же порядке, а `index` соответствует
позиции во входном массиве.

## Пакетная обработка

Передавайте массив вместо отдельных запросов — это быстрее и дешевле по накладным расходам:

```json
{
  "model": "openai/text-embedding-3-small",
  "input": [
    "Первый документ",
    "Второй документ",
    "Третий документ"
  ]
}
```

## Уменьшение размерности

Некоторые модели позволяют сократить вектор — меньше памяти в векторной базе при
небольшой потере качества:

```json
{
  "model": "openai/text-embedding-3-small",
  "input": "Текст",
  "dimensions": 512
}
```

## Rate limit

Этот эндпоинт **исключён из общего ограничения** запросов в минуту — пакетная
индексация не упирается в лимит. Ограничением остаётся баланс аккаунта.

## Коды ошибок

| Код | Причина |
|---|---|
| 400 | Отсутствует `model`/`input`, неизвестное поле, или нулевой баланс |
| 401 | Проблема с ключом |
| 502 | Ошибка провайдера, либо модель не поддерживает embeddings |

Модели с поддержкой embeddings **не отображаются** в общем списке
[`GET /models`](https://agentapi.ru/docs/models) — он их отфильтровывает. Названия берите из документации
провайдера.