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

POST /v1/embeddings

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

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

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

Примеры

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

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-приложение

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 — личный ключ

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-приложение

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.

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

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

{
  "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 — у модели нет поддержки эмбеддингов:

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

Ошибки

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

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

Коды ошибок приходят в нижнем регистре. Тело большинства ошибок — сырой OpenAI-формат { "error": { "message", "type", "code" } }, без поля success. В этом же формате приходит отказ 402 company_budget_exhausted — поля scope и canRequest лежат внутри того же объекта error. В конверте { "success": false, "error": { … } } приходят только отказы по квоте и темпу запросов — 402 ai_quota_exhausted и 429 ai_pacing_limited — и непредвиденная ошибка сервера 5xx, у которой код записан в верхнем регистре. Обработчик должен принимать оба конверта.

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

Бюджет обработки запроса — около 850 секунд. По исчерпании бюджета приходит 503 ai_provider_timeout. Заголовка Retry-After в этом ответе нет намеренно: повтор того же запроса упрётся в тот же бюджет. Разбейте массив input на части меньшего размера.

Подсказка о пополнении в ответе 402 ai_quota_exhausted. Только в ветке reason: "wallet_empty" ответ может дополнительно нести строку hint с подсказкой и ссылку topupUrl на пополнение баланса. Оба поля появляются, когда на платформе включены принудительный контроль квоты и подсказка о пополнении, поэтому читайте их как необязательные. Поле hint в этом ответе — строка.

Расход считается только по входным токенам. Поле usage.completion_tokens всегда 0, поэтому платится только вход. Действующая цена входа для каждой модели приходит в GET /v1/models — сверяйтесь с ним, а не с фиксированным значением в документации.

Размерность можно уменьшить. Модель bitrix/embeddings устроена так, что осмысленная часть вектора сосредоточена в его начале: если оставить первые k значений и заново привести вектор к единичной длине, порядок результатов поиска на наших проверках не менялся вплоть до самых коротких размерностей. Это свойство модели, а не гарантия платформы — на своих данных результат нужно замерить. Параметр dimensions делает это на стороне платформы; тот же результат можно получить самостоятельно, обрезав вектор и поделив каждое значение на длину получившегося отрезка. Приводить к единичной длине обязательно: сырой отрезок короче единицы (у вектора на 256 значений длина около 0,26), и без этого шага скалярное произведение перестанет совпадать с косинусной близостью, а сравнение с ранее сохранёнными векторами поедет.

Разумные значения — 256, 512, 1024, 2048; это ориентиры, а не единственные допустимые: подойдёт любое целое от 32 до 4096, включая 1536 и 2000. Чем короче вектор, тем меньше запас между релевантным результатом и близким по смыслу конкурентом, поэтому размерность стоит выбирать замером на своих данных.

Меньшая размерность не делает запрос дешевле или быстрее. Модель всё равно считает полный вектор, а платформа обрезает его уже в ответе: расход по входным токенам и время обработки не меняются. Экономия возникает на вашей стороне — меньше места под индекс, меньше памяти и быстрее сам поиск.

В одном индексе близости нельзя смешивать векторы разной размерности. Векторы на 256 и на 1024 значения лежат в разных пространствах, и расстояния между ними бессмысленны. Меняете размерность — перестраивайте индекс целиком.

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

• Список моделей
• Создать чат-комплишен
• AI-квота компании
• AI Router