Превращает текст в вектор чисел фиксированной длины — для семантического поиска, RAG, классификации, кластеризации. OpenAI-совместимый формат — без переписывания работают openai Python/TypeScript SDK, LangChain, LlamaIndex и любые клиенты под OpenAI Embeddings API.

Стрима нет: один POST → один JSON-ответ. Полный список embedding-моделей — в каталоге (фильтр «embeddings»).

Эндпоинт

POSThttps://api.hubris.pw/v1/embeddings

Заголовки:

Header	Значение
`Authorization`	`Bearer sk-gw-...` (обязательно)
`Content-Type`	`application/json` (обязательно)

Тело запроса

Поле	Тип	По умолчанию	Описание
`model`	`string`	—	ID embedding-модели, например `openai/text-embedding-3-small`.
`input`	`string \| string[] \| number[] \| number[][]`	—	Текст. Поддерживает: одну строку, массив строк (батч), массив токен-ID или массив массивов токен-ID. Максимум 2048 элементов в батче.
`encoding_format`	`"float" \| "base64"`	`"float"`	`float` — массив чисел в `embedding`. `base64` — base64-строка (~30% меньше трафика).
`dimensions`	`integer` > 0	—	Уменьшенная размерность вектора. Поддерживается только моделями `openai/text-embedding-3-*`.
`user`	`string`	—	Идентификатор конечного пользователя для трекинга абьюза на стороне провайдера.

Минимальный пример

curl -s https://api.hubris.pw/v1/embeddings \
-H "Authorization: Bearer sk-gw-..." \
-H "Content-Type: application/json" \
-d '{
  "model": "openai/text-embedding-3-small",
  "input": "Привет, мир"
}'

curl -s https://api.hubris.pw/v1/embeddings \-H "Authorization: Bearer sk-gw-..." \-H "Content-Type: application/json" \-d '{  "model": "openai/text-embedding-3-small",  "input": "Привет, мир"}'

from openai import OpenAI

client = OpenAI(
  base_url="https://api.hubris.pw/v1",
  api_key="sk-gw-...",
)

r = client.embeddings.create(
  model="openai/text-embedding-3-small",
  input="Привет, мир",
)
print(len(r.data[0].embedding))  # 1536

from openai import OpenAIclient = OpenAI(  base_url="https://api.hubris.pw/v1",  api_key="sk-gw-...",)r = client.embeddings.create(  model="openai/text-embedding-3-small",  input="Привет, мир",)print(len(r.data[0].embedding))  # 1536

import OpenAI from "openai";

const client = new OpenAI({
baseURL: "https://api.hubris.pw/v1",
apiKey: "sk-gw-...",
});

const r = await client.embeddings.create({
model: "openai/text-embedding-3-small",
input: "Привет, мир",
});
console.log(r.data[0].embedding.length); // 1536

import OpenAI from "openai";const client = new OpenAI({baseURL: "https://api.hubris.pw/v1",apiKey: "sk-gw-...",});const r = await client.embeddings.create({model: "openai/text-embedding-3-small",input: "Привет, мир",});console.log(r.data[0].embedding.length); // 1536

Ответ

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [-0.012, 0.034, 0.089, ...]
    }
  ],
  "model": "openai/text-embedding-3-small",
  "usage": {
    "prompt_tokens": 4,
    "total_tokens": 4,
    "cost": 1
  }
}

Поля ответа

Поле	Тип	Описание
`object`	`"list"`	Тип контейнера.
`data[]`	`array<Embedding>`	Векторы в том же порядке что и `input`.
`data[].object`	`"embedding"`	Тип элемента.
`data[].index`	`integer`	Позиция в исходном `input` (0-based). Полезно при батче.
`data[].embedding`	`number[] \| string`	Сам вектор. `number[]` при `float`, base64-строка при `base64`.
`model`	`string`	Фактически использованная модель.
`usage.prompt_tokens`	`integer`	Токены ввода.
`usage.total_tokens`	`integer`	Сумма. У embeddings всегда равна `prompt_tokens` — completion-токенов нет.
`usage.cost`	`integer`	Стоимость в копейках. Hubris-расширение.

Батч

input принимает массив строк — за один запрос до 2048 эмбеддингов. Это значительно быстрее и дешевле, чем 2048 одиночных запросов.

curl -s https://api.hubris.pw/v1/embeddings \
  -H "Authorization: Bearer sk-gw-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": ["первый текст", "второй текст", "третий текст"]
  }'

В ответе data — массив с тем же порядком, что и input. Поле index указывает позицию.

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

Параметр dimensions поддерживается моделями openai/text-embedding-3-small (по умолчанию 1536) и openai/text-embedding-3-large (по умолчанию 3072). Меньшая размерность = меньше места в vector store и быстрее cosine similarity, но падает качество поиска.

curl -s https://api.hubris.pw/v1/embeddings \
  -H "Authorization: Bearer sk-gw-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": "Привет",
    "dimensions": 256
  }'

Base64-encoding

encoding_format: "base64" возвращает вектор как base64-строку вместо массива чисел — экономит ~30% трафика. Многие SDK сами декодируют обратно в float-массив.

curl -s https://api.hubris.pw/v1/embeddings \
  -H "Authorization: Bearer sk-gw-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": "Привет",
    "encoding_format": "base64"
  }'

HTTP-коды

Код	Когда
`200`	Успешный ответ.
`400`	Тело запроса не соответствует схеме (`input` пустой, размер батча > 2048, неподдерживаемый `dimensions`).
`401`	Ключ отсутствует / отозван / невалиден.
`402`	Недостаточно средств на балансе.
`404`	Модели с таким `model` не существует или это не embedding-модель.
`429`	Превышен дневной лимит на ключе.
`502 / 503 / 504`	Транзиентные сбои у провайдера или курса ЦБ.

Формат тела ошибки и стратегия retry — Ошибки.

Биллинг

Embeddings тарифицируются только по входным токенам — completion-токенов нет. Точная формула — на странице Цены. Цены в ₽ за 1 миллион токенов и весь список embedding-моделей — в каталоге с фильтром по выходной модальности «embeddings».

Что дальше

Модели — как выбрать embedding-модель.
Ошибки — что делать на 429/502.
Цены — формула расчёта.

Обновлено: 24 мая 2026 г.

POST /v1/embeddings