Создать эмбеддинги

POST /v1/embeddings

Преобразует текст в векторное представление. Векторы нужны для семантического поиска, кластеризации, поиска дублей и подбора похожих карточек CRM. Формат запроса и ответа совместим с OpenAI API, потоковой передачи нет.

Эмбеддинги умеют только модели, у которых в `GET /v1/models` поле capabilities.embeddings равно true.

Поля запроса (body)

Поле Тип Обяз. По умолч. Описание
model string да — Идентификатор модели с поддержкой эмбеддингов. Список: `GET /v1/models`
input string | string[] да — Текст для векторизации: одна строка или массив строк. На каждую строку возвращается один вектор. Пустая строка и пустой массив отклоняются с 400
encoding_format string нет float Формат значений вектора: float или base64
dimensions integer нет — Желаемая размерность вектора. Применяется только к моделям, которые это поддерживают

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/embeddings \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/embeddings",
    "input": "Хотим CRM на 50 пользователей"
  }'

curl — OAuth-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/embeddings \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/embeddings",
    "input": "Хотим CRM на 50 пользователей"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/embeddings', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bitrix/embeddings',
    input: ['Первый текст', 'Второй текст'],
  }),
})

const result = await res.json()
console.log(result.data.length)        // 2 — по вектору на строку
console.log(result.data[0].embedding)  // [0.0203, 0.0034, ...]

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/embeddings', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bitrix/embeddings',
    input: ['Первый текст', 'Второй текст'],
  }),
})

const result = await res.json()

Поля ответа

Ответ приходит в сыром OpenAI-формате, без обёртки success и data.

Поле Тип Описание
object string Всегда list
data array Массив векторов, по одному на каждую строку input
data[].object string Всегда embedding
data[].embedding number[] Значения вектора
data[].index number Позиция строки в исходном input
model string Модель, обработавшая запрос
usage.prompt_tokens number Токены входного текста. По ним считается расход
usage.completion_tokens number Всегда 0 — эмбеддинги не порождают ответных токенов
usage.total_tokens number Совпадает с prompt_tokens

Пример ответа

Показаны первые три значения вектора. Полная размерность зависит от модели — у bitrix/embeddings это 4096 значений.

JSON 
{
  "object": "list",
  "model": "bitrix/embeddings",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0203, 0.0034, -0.0156]
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 0,
    "total_tokens": 12
  }
}

Пример ответа при ошибке

501 embeddings_unsupported — у модели нет поддержки эмбеддингов:

JSON 
{
  "error": {
    "message": "Model \"bitrix/bitrixgpt-5.5\" does not support embeddings.",
    "type": "server_error",
    "code": "embeddings_unsupported"
  }
}

Ошибки

HTTP Код Описание
400 invalid_request Некорректные параметры — пустой input, неверное тело запроса
404 ai_model_not_found Модель не найдена или отключена
501 embeddings_unsupported Модель или провайдер не поддерживает эмбеддинги
402 ai_credentials_not_configured Для модели нет учётных данных провайдера — подключите свой ключ
402 insufficient_balance Недостаточно средств для платной модели
402 ai_quota_exhausted Месячная AI-квота портала исчерпана. Поле reason различает случай: breaker — сработал часовой предохранитель расходов сверх квоты, wallet_empty — квота исчерпана и на балансе портала нет средств, wallet_off — расход сверх квоты для портала недоступен. resetAt — момент, когда запросы снова начнут проходить, может отсутствовать для wallet_off
403 scope_missing API-ключу не хватает скоупа vibe:ai
429 ai_congested Пул AI-кластера перегружен. Запрос не выполнялся, списания нет, повторите его по заголовку Retry-After. Ответ несёт заголовок X-AI-Admission: shed, а не X-RateLimit-Scope
502 ai_provider_unavailable Внешний провайдер вернул не-2xx или сетевую ошибку
429 ai_pacing_limited Превышено суточное или недельное окно равномерного расходования квоты. Это не исчерпание квоты — повторите запрос по заголовку Retry-After. Подробнее — «Равномерное расходование»

Полный список общих ошибок API — Ошибки.

Известные особенности

Коды ошибок приходят в нижнем регистре. Тело ошибки — сырой OpenAI-формат { "error": { "message", "type", "code" } }, без поля success. Это отличает эндпоинт от остальных маршрутов Вайбкод.

Массив input сохраняет порядок. Вектор data[i] соответствует строке input[i], а поле data[].index дублирует эту позицию — по нему можно сопоставить результат после параллельной обработки.

Расход считается только по входным токенам. Поле usage.completion_tokens всегда 0, поэтому платится только вход. Для модели bitrix/embeddings цена входа нулевая.

Смотрите также