Создать чат-комплишен

Ответ приходит в сыром OpenAI-формате.

Обёртки {success, data}, которая используется в остальных эндпоинтах Вайбкод — /v1/deals, /v1/tasks и других, — здесь нет.

Так сделано для совместимости с OpenAI SDK. Если у вас единый клиент с проверкой if (!response.success), добавьте для AI Router исключение.

POST /v1/chat/completions

Генерирует ответ AI-модели на массив сообщений. Формат запроса и ответа совместим с POST /v1/chat/completions из OpenAI API.

Возможности эндпоинта вынесены на отдельные страницы: потоковая передача, гарантированный JSON-ответ, вызов функций, анализ изображений и лимиты запросов.

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

Управление рассуждением

Модели с рассуждением думают перед ответом. Токены рассуждения входят в usage.completion_tokens и тарифицируются как выходные по той же ставке — рычаг цены не тариф, а объём. Вайбкод описывает объём пятью ступенями: none — ответ сразу, low — короткая прикидка, medium — стандартное рассуждение модели, когда оно включено, а уровень не задан, high — сильнее стандартного, max — всё, что модель умеет.

Что умеет конкретная модель, показывает поле reasoning в GET /v1/models. Его map — карта ступеней на родные режимы модели, две ступени с одним родным значением — объявленное схлопывание. default — ступень по умолчанию, budgetTokens — поддержка бюджета токенов рассуждения. У модели с reasoning: null управление недоступно: параметр игнорируется с предупреждением REASONING_NOT_SUPPORTED, и в модель ничего не добавляется.

Нормализация входа: minimal → low, xhigh → max. reasoning.enabled: true или chat_template_kwargs.thinking: true без уровня дают medium. reasoning.max_tokens без effort — medium с бюджетом. Пустой reasoning: {} или chat_template_kwargs: {} — то же, что параметра нет. null в любом из трёх полей равнозначен отсутствию. Пришло несколько полей — берётся старшее: сначала reasoning, затем reasoning_effort, затем chat_template_kwargs. Значение вне словаря, неположительный reasoning.max_tokens или chat_template_kwargs не-объект отклоняются с 400 invalid_request.

Если запрошенной ступени у модели нет, применяется ближайшая ниже из ступеней с рассуждением, а в warnings приходит REASONING_EFFORT_ADJUSTED с полями requested, applied, direction. Ступень none округлением не выбирается никогда — выключить рассуждение можно только явно. Если ниже ничего нет, берётся ближайшая выше. Просьба none у модели, где выключить нельзя, даёт низшую ступень и REASONING_CANNOT_BE_DISABLED. Бюджет у модели без budgetTokens игнорируется с REASONING_BUDGET_NOT_SUPPORTED.

Без параметра в запросе платформа передаёт модели с декларацией ступень default явно. Режим не остаётся на усмотрение провайдера модели, поэтому обновление модели на его стороне не меняет поведение запросов без параметра. Поле reasoning ответа сообщает эту ступень.

В ответе: поле reasoning с requested, applied, native и предупреждения в warnings. В потоковом режиме тело предупреждений не несёт — состояние едет заголовками X-Reasoning-Applied, X-Reasoning-Native, X-Reasoning-Warnings с кодами через запятую. У синхронного ответа те же заголовки дублируют тело. Заголовок отсутствует, когда сообщать нечего. При подмене модели — DISABLED-перенаправлении или переключении на резервную — ступень разрешается по модели, которая выполнила запрос, и поле reasoning с заголовками описывают её. reasoning.exclude исполняется у любой модели, в том числе без декларации.

Алиасы моделей

Поле model принимает три значения, которые разрешаются в модель портала по умолчанию — сейчас это bitrix/bitrixgpt-5.5: auto, bitrix/free или пустая строка.

Модели bitrix/bitrixgpt-5 и bitrix/bitrixgpt-5-vl помечены как устаревшие и работают до 31 июля 2026 года. После этой даты запросы к ним прозрачно перенаправляются на bitrix/bitrixgpt-5.5 с заголовком X-Model-Replacement — подробнее в жизненном цикле моделей.

Кроме того, model принимает идентификатор модели без префикса провайдера: bitrixgpt-5.5 разрешается в bitrix/bitrixgpt-5.5. Короткое имя должно целиком и с учётом регистра совпасть с идентификатором из GET /v1/models, у которого отброшен первый сегмент. Поиска по части идентификатора нет: запрос с bitrixgpt получит 404 ai_model_not_found, а не первую модель, идентификатор которой содержит это слово. Короткое имя, под которое подходят несколько доступных ключу моделей, тоже получает 404 — передайте полный идентификатор. Модель, найденная по короткому имени, отмечается в ответе заголовком X-Model-Resolved с её полным идентификатором.

Примеры

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

curl -X POST https://vibecode.bitrix24.tech/v1/chat/completions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/bitrixgpt-5.5",
    "messages": [
      {"role": "system", "content": "Ты эксперт по продажам. Классифицируй лидов по качеству."},
      {"role": "user", "content": "ООО Вектор, 50 пользователей, бюджет 500 тысяч в месяц."}
    ],
    "temperature": 0.3,
    "max_tokens": 300
  }'

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

curl -X POST https://vibecode.bitrix24.tech/v1/chat/completions \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/bitrixgpt-5.5",
    "messages": [
      {"role": "system", "content": "Ты эксперт по продажам. Классифицируй лидов по качеству."},
      {"role": "user", "content": "ООО Вектор, 50 пользователей, бюджет 500 тысяч в месяц."}
    ],
    "temperature": 0.3,
    "max_tokens": 300
  }'

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/chat/completions', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bitrix/bitrixgpt-5.5',
    messages: [
      { role: 'system', content: 'Ты эксперт по продажам. Классифицируй лидов по качеству.' },
      { role: 'user', content: 'ООО Вектор, 50 пользователей, бюджет 500 тысяч в месяц.' },
    ],
    temperature: 0.3,
    max_tokens: 300,
  }),
})

const data = await res.json()
console.log(data.choices[0].message.content)
console.log('Токены:', data.usage.total_tokens)

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/chat/completions', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bitrix/bitrixgpt-5.5',
    messages: [
      { role: 'system', content: 'Ты эксперт по продажам. Классифицируй лидов по качеству.' },
      { role: 'user', content: 'ООО Вектор, 50 пользователей, бюджет 500 тысяч в месяц.' },
    ],
    temperature: 0.3,
    max_tokens: 300,
  }),
})

const data = await res.json()
console.log(data.choices[0].message.content)

Поля ответа

Если запрос с function tools завершился без полезного ответа или вызова, в content может добавиться английское объяснение, а в warnings — { code: "TOOL_CALL_MISSING", message: "..." } с тем же текстом. Если текст уже есть, он сохраняется перед объяснением через пустую строку. HTTP 200, finish_reason: "stop" и usage сохраняются; объяснение не влияет на списание. Оно не добавляется при tool_choice: "none", структурированном ответе или ходе только с рассуждением, завершившемся stop. В потоке это отдельное событие delta.content до финиша, без массива warnings.

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

{
  "id": "chatcmpl-a1a73c6eb3f180fd",
  "object": "chat.completion",
  "created": 1777289339,
  "model": "bitrix/bitrixgpt-5.5",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Качество: ВЫСОКОЕ\n\nОбоснование:\n- Юридическое лицо (ООО) — B2B-клиент\n- Бюджет 500 тысяч в месяц — выше среднего\n- Конкретный объём (50 пользователей) — осознанная потребность\n\nРекомендация: назначить звонок в течение 24 часов."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 85,
    "total_tokens": 127
  }
}

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

404 ai_model_not_found — модель не найдена или у ключа нет доступа к ней:

{
  "error": {
    "message": "Model \"anthropic/claude-imaginary-x\" not found or disabled.",
    "type": "invalid_request_error",
    "code": "ai_model_not_found"
  }
}

Ошибки

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

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

Автоматическое переключение на резервную модель при сбое провайдера. Если у платной модели произошла ошибка 5xx или таймаут, синхронный запрос повторяется с моделью по умолчанию. В ответе появляется заголовок X-Model-Fallback: <исходный modelId>. В потоковом режиме такого переключения нет — клиент получает ошибку в последнем событии перед data: [DONE].

Исчерпанная квота Cowork/Code: ответ объявляет лимит, а не выполняет запрос. Это отдельное состояние, не имеющее отношения к X-Model-Fallback выше: тот заголовок отмечает подмену модели, здесь же квота подписки исчерпана. Когда окно квоты исчерпано, а на платформе настроена резервная модель, запрос отвечает кодом 200, но работа по нему не делается: поля tools, tool_choice и response_format снимаются, системные сообщения запроса не действуют, и модель сообщает, что лимит достигнут и когда он сбросится. Признаки состояния — заголовок X-Cowork-Fallback: true и предупреждение COWORK_QUOTA_FALLBACK в массиве warnings. В потоковом режиме предупреждения в теле нет, состояние видно по заголовку. Списания за такой ответ нет, квота не расходуется. Не ждите здесь tool_calls и JSON по схеме: даже с response_format в запросе придёт обычный текст. Если резервная модель не настроена — или настроенная сама не ответила, — приходит 402 cowork_quota_exhausted. По коду ответа эти два случая не различаются, поэтому обрабатывайте 402 на этом эндпоинте всегда.

Месячная AI-квота портала. На порталах с включённым контролем квоты запрос может вернуть 402 ai_quota_exhausted. Поле reason различает три случая: breaker — сработал часовой предохранитель расходов сверх квоты, wallet_empty — квота исчерпана и на балансе портала нет средств, wallet_off — расход сверх квоты для портала недоступен. Поле resetAt содержит момент, когда запросы снова начнут проходить, для wallet_off оно может отсутствовать. В ветке wallet_empty ответ может дополнительно нести строку hint с подсказкой и ссылку topupUrl на пополнение баланса — оба поля появляются, когда на платформе включены принудительный контроль квоты и подсказка о пополнении, поэтому читайте их как необязательные. Поле hint в этом ответе — строка. Когда у портала нет оплаченного доступа к AI-моделям, ответ с reason: "wallet_off" дополнительно несёт details.learnMoreUrl — страницу с описанием подписки или тарифа Битрикс24, в которые входит AI, а поле message называет нужный продукт. При других причинах wallet_off поля details.learnMoreUrl нет. Пока расход укладывается в квоту, поведение эндпоинта не меняется. Сверх квоты, если такой расход для портала разрешён, запросы списываются с денежного баланса портала по базовой цене модели из каталога.

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

Лимит размера тела запроса. У моделей bitrix/* предел задаёт кластер моделей, для тела с изображениями он ниже, чем для текста. Действующий предел называет сообщение ответа 413. Изображения data: в теле больше предела платформа уменьшает сама, а тело, которое не уложилось и после этого, получает 413 ai_payload_too_large. У моделей через свой ключ провайдера — 30 MiB, этого хватает на одно изображение до 20 MiB. Как платформа уменьшает изображения — анализ изображений.

Передача content массивом. Для текстовых моделей передавайте content строкой. Массив с одним элементом text тоже работает, но избыточен. Массив обязателен только для запросов с изображениями.

Завершение хода Cowork/Code у пятичасового лимита. У успешного шага модели по подписке может прийти заголовок X-Cowork-Completion-Mode: landing-finish означает просьбу сервера завершить уже начатый ход перед исчерпанием окна, reserve — шаг допущен из запаса на завершение после исчерпания окна. Вместе с ним приходит X-Cowork-Completion-Reset-At с ISO-временем сброса этого окна. Заголовки приходят и с JSON-ответом, и в начале потока SSE. Отсутствие заголовка не доказывает, что ход завершён; итог определяйте по обычному завершению ответа модели.

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

• Потоковая передача
• Гарантированный JSON-ответ
• Вызов функций
• Анализ изображений
• Лимиты запросов
• Жизненный цикл моделей
• Список моделей
• AI Router
• Бот-помощник по сделкам и процессам