---
title: Эмбеддинги
description: Вызов POST /v1/embeddings — пачка входов, вектор на каждый вход в base64 и то, во что этот вызов обходится.
keywords: эмбеддинги, векторы, base64, батч, encoding_format, usage
group: gateway
---

## Быстро {#quick keywords="curl, python, node, вектор"}

Одна операция принимает пачку входов и отвечает вектором на каждый — в том же порядке, в каком входы были даны. `encoding_format` обязателен и равен `"base64"`.

:::code-group
```bash title=curl
curl https://api.kumorouter.com/v1/embeddings \
  -H "Authorization: Bearer $KUMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "encoding_format": "base64",
    "input": ["первый текст", "второй текст"]
  }'
```
```python title=Python
import base64
import os
import struct

import requests

response = requests.post(
    "https://api.kumorouter.com/v1/embeddings",
    headers={"Authorization": f"Bearer {os.environ['KUMO_API_KEY']}"},
    json={
        "model": "<model>",
        "encoding_format": "base64",
        "input": ["первый текст", "второй текст"],
    },
    timeout=60,
)
body = response.json()

vectors = []
for entry in sorted(body["data"], key=lambda item: item["index"]):
    raw = base64.b64decode(entry["embedding"])
    vectors.append(struct.unpack(f"<{len(raw) // 4}f", raw))
```
```javascript title=Node
const response = await fetch("https://api.kumorouter.com/v1/embeddings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KUMO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "<model>",
    encoding_format: "base64",
    input: ["первый текст", "второй текст"],
  }),
});

const body = await response.json();
const vectors = body.data
  .sort((a, b) => a.index - b.index)
  .map((entry) => {
    const bytes = Buffer.from(entry.embedding, "base64");
    return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.length / 4);
  });
```
:::

## Члены запроса {#request keywords="input, encoding_format, model, батч"}

| Член | Что это |
| --- | --- |
| `model` | Обязателен. Модель каталога, которой считать векторы, в том имени, которым её называет клиент. |
| `input` | Обязателен. Пачка входов: не больше 128 членов и не больше 131 072 байт в сумме. Пустой вход отвергается. |
| `encoding_format` | Обязателен и равен `"base64"`. |

:::note
`"float"` этой поверхностью не обслуживается — ни названный явно, ни полученный умолчанием протокола. Запрос, который просит `float` или не просит ничего, отвергается по имени члена, а не отвечается в другом формате. Так контракт остаётся позиционным: вектор нельзя перепутать со входом, и его нельзя тихо потерять.
:::

Стриминга у этой поверхности нет.

## Ответ {#response keywords="data, embedding, index, usage"}

| Член ответа | Что это |
| --- | --- |
| `object` | Всегда `list`. |
| `data` | По вектору на вход, в том порядке, в каком входы были даны. |
| `model` | Модель, которой векторы посчитаны. |
| `usage` | `prompt_tokens` и `total_tokens`; на этой поверхности они равны. |

Каждый член `data` несёт `object` со значением `embedding`, `index` — позицию своего входа — и `embedding`: компоненты вектора как значения float32 little-endian, закодированные в base64.

```json title=Ответ
{
  "object": "list",
  "model": "<model>",
  "data": [
    { "object": "embedding", "index": 0, "embedding": "AACAPwAAAEAAAEBA" },
    { "object": "embedding", "index": 1, "embedding": "AABAwAAAgL8AAAAA" }
  ],
  "usage": { "prompt_tokens": 9, "total_tokens": 9 }
}
```

## Пачка и её границы {#batching keywords="батч, 128, порядок, index"}

Пачка — не удобство, а способ считать: 128 входов одним вызовом дешевле по накладным расходам, чем 128 вызовов, а порядок ответа гарантирован. Границы проверяются до того, как будет вызван хоть один провайдер, поэтому пачка, вышедшая за них, стоит вам отказа, а не денег.

Считается вызов только по входным токенам: выходных токенов эта поверхность не производит, изображений тоже, и в учёте по обоим стоит ноль.

## Какие модели отвечают {#models keywords="каталог, протокол, возможности"}

Отвечает только модель, у которой в опубликованном каталоге есть протокол эмбеддингов. Каталог — единственный источник этого факта: он же говорит, какие имена и псевдонимы у модели и что она умеет.

> [Каталог моделей →](/ru/models) [Прайс-лист →](https://kumorouter.com/ru/pricing)

## Что дальше {#next keywords="ошибки, лимиты, справочник"}

:::cards
- [Ошибки](/ru/errors) — конверт отказа и коды ответа этой операции.
- [Лимиты](/ru/limits) — потолки запросов и токенов.
- [Справочник API](/ru/api-reference) — операция член за членом, прямо из описания API.
:::