[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-ai":3,"docs-tabs-ai":6},{"content":4,"lastmod":5},"\n# AI Router\n\nЕдиный OpenAI-совместимый API для работы с языковыми моделями от разных провайдеров. Бесплатные модели Битрикс24 доступны сразу — для платных и для своих ключей провайдеров (BYOK) подключите учётные данные.\n\n**Это API, а не чат на портале.** Диалогового окна для общения с моделью на портале Вайбкод нет — искать его не нужно. Запрос (промпт) вводится в вашем AI-инструменте, агенте или коде (Cursor, IDE-агент, библиотека `openai`, собственное приложение), который обращается к этому API по адресу ниже. Бесплатные модели Битрикс24 работают так же, как платные и BYOK, — через тот же API.\n\n**Скоуп:** `vibe:ai` (добавляется автоматически ко всем API-ключам) | **Базовый URL:** `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1` | **Авторизация:** заголовок `X-Api-Key` или `Authorization: Bearer YOUR_API_KEY`\n\n## Совместимость с OpenAI SDK\n\nВсе ответы возвращаются в сыром OpenAI-формате. Подключите любой OpenAI-совместимый инструмент (Cursor, IDE-агенты, библиотека `openai`) через стандартные настройки:\n\n```\nBase URL: https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\nAPI Key:  ваш ключ vibe_api_... или vibe_app_...\n```\n\nSDK по умолчанию передаёт ключ в заголовке `Authorization: Bearer` — Вайбкод принимает оба варианта (`X-Api-Key` и `Authorization: Bearer`). Параметры запроса (`model`, `messages`, `temperature`, `tools`, `stream`, `response_format`) и поля ответа (`id`, `choices`, `usage`) соответствуют контракту `POST \u002Fv1\u002Fchat\u002Fcompletions` из OpenAI API.\n\n## Разделы документации\n\n- [Чат-комплишены](\u002Fdocs\u002Fai\u002Fchat) — генерация ответов модели в синхронном или потоковом режиме (`Server-Sent Events`)\n- [Модели](\u002Fdocs\u002Fai\u002Fmodels) — список доступных моделей и детали отдельной модели\n- [Распознавание речи](\u002Fdocs\u002Fai\u002Faudio) — преобразование аудио в текст через Whisper Large v3 Turbo\n- [Эмбеддинги](\u002Fdocs\u002Fai\u002Fembeddings) — преобразование текста в векторные представления (формат OpenAI)\n- [Свои ключи (BYOK)](\u002Fdocs\u002Fai\u002Fcredentials) — подключение собственных ключей провайдеров\n- [Расход и лимиты](\u002Fdocs\u002Fai\u002Fconsumption) — статистика по ключу, месячная квота компании и выгодные часы\n- [Совместимость с OpenAI SDK](#совместимость-с-openai-sdk) — настройка Cursor, IDE-агентов и любых OpenAI-совместимых клиентов\n- [Жизненный цикл моделей](\u002Fdocs\u002Fai\u002Fmodels\u002Flifecycle) — поведение `ACTIVE` \u002F `DEPRECATED` \u002F `DISABLED` и связанные заголовки\n- [Миграция со старых маршрутов](#миграция-со-старых-маршрутов) — для проектов, где остались вызовы `\u002Fv1\u002Fai\u002Fchat\u002Fcompletions` и аналогичных\n\n---\n\n## Быстрый старт\n\n### 1. Сгенерируйте ответ бесплатной моделью\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fchat\u002Fcompletions \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"bitrix\u002Fbitrixgpt-5.5\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"Что такое CRM?\"}]\n  }'\n```\n\nОтвет:\n\n```json\n{\n  \"id\": \"chatcmpl-a1a73c6eb3f180fd\",\n  \"object\": \"chat.completion\",\n  \"created\": 1777289339,\n  \"model\": \"bitrix\u002Fbitrixgpt-5.5\",\n  \"choices\": [\n    {\n      \"index\": 0,\n      \"finish_reason\": \"stop\",\n      \"message\": {\n        \"role\": \"assistant\",\n        \"content\": \"CRM — это система управления взаимоотношениями с клиентами.\"\n      }\n    }\n  ],\n  \"usage\": {\n    \"prompt_tokens\": 12,\n    \"completion_tokens\": 18,\n    \"total_tokens\": 30\n  }\n}\n```\n\n### 2. Посмотрите доступные модели\n\n```bash\ncurl -H \"X-Api-Key: YOUR_API_KEY\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fmodels\n```\n\nВозвращает только те модели, для которых у портала настроены учётные данные провайдера. Модели Битрикс24 (`bitrix\u002F*`) доступны всем без отдельных BYOK-ключей. Большинство из них бесплатны.\n\n### 3. Проверьте расход токенов\n\n```bash\ncurl -H \"X-Api-Key: YOUR_API_KEY\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fai\u002Fusage?days=7\"\n```\n\n---\n\n## Типовые сценарии использования\n\n- **Классификация лидов:** запросите лиды через [`GET \u002Fv1\u002Fleads`](\u002Fdocs\u002Fentities\u002Fleads\u002Flist), пропустите через [чат-комплишен](\u002Fdocs\u002Fai\u002Fchat\u002Fcompletions) с `response_format: json_object`, обновите CRM-поля через [`PATCH \u002Fv1\u002Fleads\u002F:id`](\u002Fdocs\u002Fentities\u002Fleads\u002Fupdate).\n- **Генерация контента:** прочитайте товары через [`GET \u002Fv1\u002Fproducts`](\u002Fdocs\u002Fentity-api), сгенерируйте описания, обновите карточки в каталоге.\n- **Извлечение данных:** возьмите комментарии из [`GET \u002Fv1\u002Ftimeline-logs`](\u002Fdocs\u002Ftimeline-logs), извлеките телефон \u002F email \u002F название компании, запишите в CRM.\n- **Чат-бот:** зарегистрируйте бота через [`POST \u002Fv1\u002Fbots`](\u002Fdocs\u002Fbots\u002Fmanagement\u002Fcreate), получайте события через [`GET \u002Fv1\u002Fbots\u002F:botId\u002Fevents`](\u002Fdocs\u002Fbots\u002Fevents), генерируйте ответ AI, отправляйте через [`POST \u002Fv1\u002Fbots\u002F:botId\u002Fmessages`](\u002Fdocs\u002Fbots\u002Fmessages).\n- **Отчёты:** соберите данные через [`POST \u002Fv1\u002Fbatch`](\u002Fdocs\u002Fbatch), сгенерируйте сводку, отправьте уведомление.\n\n---\n\n## Полный пример: распознавание звонка → классификация → запись в таймлайн\n\nСценарий: получить аудиозапись звонка, расшифровать через Whisper, классифицировать качество лида через `JSON`-ответ модели, записать результат в таймлайн сделки.\n\n### Шаг 1. Распознавание речи\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Faudio\u002Ftranscriptions \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -F \"file=@call-recording.mp3\" \\\n  -F \"language=ru\" \\\n  -F \"response_format=json\"\n```\n\nОтвет:\n\n```json\n{\n  \"text\": \"Здравствуйте, ООО Вектор. Хотим CRM на 50 пользователей, бюджет до 500 тысяч в месяц.\"\n}\n```\n\n### Шаг 2. Классификация лида с гарантированным `JSON`\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fchat\u002Fcompletions \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"bitrix\u002Fbitrixgpt-5.5\",\n    \"messages\": [\n      {\n        \"role\": \"system\",\n        \"content\": \"Классифицируй лид по тексту звонка. Верни JSON: {\\\"quality\\\": \\\"high|medium|low\\\", \\\"score\\\": 0-100, \\\"reason\\\": \\\"...\\\"}.\"\n      },\n      {\n        \"role\": \"user\",\n        \"content\": \"ООО Вектор. CRM на 50 пользователей, бюджет до 500 тысяч в месяц.\"\n      }\n    ],\n    \"response_format\": {\"type\": \"json_object\"}\n  }'\n```\n\nОтвет:\n\n```json\n{\n  \"id\": \"chatcmpl-acdb112cf9cdf9f9\",\n  \"object\": \"chat.completion\",\n  \"model\": \"bitrix\u002Fbitrixgpt-5.5\",\n  \"choices\": [\n    {\n      \"index\": 0,\n      \"finish_reason\": \"stop\",\n      \"message\": {\n        \"role\": \"assistant\",\n        \"content\": \"{\\\"quality\\\":\\\"high\\\",\\\"score\\\":88,\\\"reason\\\":\\\"Юрлицо, конкретный объём (50 пользователей) и бюджет 500 тысяч в месяц.\\\"}\"\n      }\n    }\n  ],\n  \"usage\": {\"prompt_tokens\": 92, \"completion_tokens\": 36, \"total_tokens\": 128}\n}\n```\n\n### Шаг 3. Запись результата в таймлайн сделки\n\nПарсим `choices[0].message.content` как `JSON` и отправляем в таймлайн:\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftimeline-logs \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"entityType\": \"deal\",\n    \"entityId\": 1234,\n    \"title\": \"Классификация AI: high (88\u002F100)\",\n    \"text\": \"Юрлицо, конкретный объём (50 пользователей) и бюджет 500 тысяч в месяц.\"\n  }'\n```\n\nВсе три эндпоинта живут в одном API-ключе и одной авторизации — отдельных интеграций не требуется.\n\n---\n\n## Справочник эндпоинтов\n\n| Метод | Путь | Описание |\n|-------|------|----------|\n| POST | [`\u002Fv1\u002Fchat\u002Fcompletions`](\u002Fdocs\u002Fai\u002Fchat\u002Fcompletions) | Генерация ответа модели — синхронно или потоком |\n| GET | [`\u002Fv1\u002Fmodels`](\u002Fdocs\u002Fai\u002Fmodels\u002Flist) | Список доступных моделей |\n| GET | [`\u002Fv1\u002Fmodels\u002F:modelId`](\u002Fdocs\u002Fai\u002Fmodels\u002Fget) | Детали конкретной модели |\n| POST | [`\u002Fv1\u002Faudio\u002Ftranscriptions`](\u002Fdocs\u002Fai\u002Faudio\u002Ftranscriptions) | Распознавание речи через Whisper |\n| POST | [`\u002Fv1\u002Fembeddings`](\u002Fdocs\u002Fai\u002Fembeddings) | Векторные эмбеддинги текста |\n| GET | [`\u002Fv1\u002Fai\u002Fusage`](\u002Fdocs\u002Fai\u002Fconsumption\u002Fusage) | Статистика использования AI по ключу |\n| GET | [`\u002Fv1\u002Fai\u002Fquota`](\u002Fdocs\u002Fai\u002Fconsumption\u002Fquota) | Процент месячной AI-квоты и разбивка по моделям |\n| GET | [`\u002Fv1\u002Foff-peak`](\u002Fdocs\u002Fai\u002Fconsumption\u002Foff-peak) | Расписание выгодных часов AI-квоты |\n| GET | [`\u002Fv1\u002Fai\u002Fproviders`](\u002Fdocs\u002Fai\u002Fcredentials\u002Fproviders) | Список провайдеров для BYOK |\n| GET | [`\u002Fv1\u002Fai\u002Fcredentials`](\u002Fdocs\u002Fai\u002Fcredentials\u002Flist) | Список собственных ключей провайдеров |\n| POST | [`\u002Fv1\u002Fai\u002Fcredentials`](\u002Fdocs\u002Fai\u002Fcredentials\u002Fcreate) | Подключить ключ провайдера (с верификацией) |\n| PATCH | [`\u002Fv1\u002Fai\u002Fcredentials\u002F:id`](\u002Fdocs\u002Fai\u002Fcredentials\u002Fupdate) | Обновить ключ провайдера |\n| DELETE | [`\u002Fv1\u002Fai\u002Fcredentials\u002F:id`](\u002Fdocs\u002Fai\u002Fcredentials\u002Fdelete) | Удалить ключ провайдера |\n| POST | [`\u002Fv1\u002Fai\u002Fcredentials\u002F:id\u002Ftest`](\u002Fdocs\u002Fai\u002Fcredentials\u002Ftest) | Проверить ключ провайдера |\n| GET | [`\u002Fv1\u002Fai\u002Fcredentials\u002F:id\u002Fusage`](\u002Fdocs\u002Fai\u002Fcredentials\u002Fusage) | Статистика использования по ключу |\n| POST | [`\u002Fv1\u002Fai\u002Fcredentials\u002F:id\u002Ffetch-models`](\u002Fdocs\u002Fai\u002Fcredentials\u002Ffetch-models) | Загрузить каталог моделей у Custom-провайдера |\n| GET | [`\u002Fv1\u002Fai\u002Fcredentials\u002F:id\u002Fmodels`](\u002Fdocs\u002Fai\u002Fcredentials\u002Fmodels-list) | Список моделей, привязанных к ключу |\n| POST | [`\u002Fv1\u002Fai\u002Fcredentials\u002F:id\u002Fmodels`](\u002Fdocs\u002Fai\u002Fcredentials\u002Fmodels-add) | Добавить модель к ключу вручную |\n| DELETE | [`\u002Fv1\u002Fai\u002Fcredentials\u002F:credId\u002Fmodels\u002F:modelRowId`](\u002Fdocs\u002Fai\u002Fcredentials\u002Fmodels-delete) | Удалить модель, привязанную к ключу |\n\n---\n\n## Коды ошибок\n\nЭндпоинты делятся на две группы по формату ответа об ошибке:\n\n**Сырой OpenAI-формат** (`\u002Fv1\u002Fchat\u002Fcompletions`, `\u002Fv1\u002Fmodels`, `\u002Fv1\u002Faudio\u002Ftranscriptions`):\n\n```json\n{\n  \"error\": {\n    \"message\": \"...\",\n    \"type\": \"invalid_request_error\",\n    \"code\": \"ai_model_not_found\"\n  }\n}\n```\n\n`type` принимает значения: `invalid_request_error` (4xx), `insufficient_quota` (402), `service_unavailable` (503), `server_error` (5xx). `code` всегда в нижнем регистре.\n\n**V1-формат** (`\u002Fv1\u002Fai\u002Fusage`, `\u002Fv1\u002Fai\u002Fcredentials\u002F*`, `\u002Fv1\u002Fai\u002Fproviders`):\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"not_found\",\n    \"message\": \"Credential not found\"\n  }\n}\n```\n\n| Код | HTTP | Описание |\n|-----|------|----------|\n| `scope_missing` | 403 | API-ключу не хватает скоупа `vibe:ai` |\n| `invalid_request` | 400 | Некорректные параметры запроса |\n| `no_default_model` | 400 | У портала нет ни одной доступной для вызова модели |\n| `invalid_image_payload` | 400 | Некорректный `image_url` в массиве `content` |\n| `invalid_language` | 400 | Код языка не соответствует `ISO 639` |\n| `no_file` | 400 | Аудиофайл не передан |\n| `empty_file` | 400 | Файл в multipart присутствует, но тело — 0 байт. Типичная причина — `curl -F \"file=path\"` без `@` |\n| `ai_model_not_found` | 404 | Модель не найдена или отключена |\n| `not_found` | 404 | Сущность (BYOK-ключ, модель) не найдена |\n| `provider_not_found` | 404 | Провайдер не найден или отключён |\n| `ai_credentials_not_configured` | 402 | Для модели нет учётных данных провайдера — подключите `BYOK` |\n| `insufficient_balance` | 402 | Недостаточно средств для платной модели |\n| `credential_invalid` | 422 | Ключ провайдера не прошёл верификацию |\n| `already_exists` | 409 | Ключ для этого провайдера уже существует |\n| `base_url_invalid` | 400 | `baseUrl` Custom-провайдера должен использовать `http` или `https` |\n| `base_url_private` | 400 | `baseUrl` указывает на приватную сеть или не разрешается в IP-адрес через `DNS` |\n| `not_custom_provider` | 400 | Ручная регистрация моделей разрешена только для Custom-провайдера |\n| `provider_list_models_unavailable` | 200 | Custom-провайдер не поддерживает `GET \u002Fv1\u002Fmodels` — добавьте модели вручную |\n| `ai_provider_unavailable` | 502 | Внешний провайдер вернул не-2xx или сетевую ошибку (не таймаут) |\n| `ai_provider_timeout` | 503 | Апстрим Whisper не ответил за 15 минут |\n| `ai_congested` | 429 | Пул AI-кластера перегружен. Запрос не выполнялся, списания нет, повторите его по заголовку `Retry-After` |\n| `model_unavailable` | 503 | Модель отключена и резервной нет |\n\n> **Whisper \u002F `\u002Fv1\u002Faudio\u002Ftranscriptions`:** окно обработки — до 15 минут. Длинное \u002F шумное аудио может занять несколько минут. Для аудио длиннее ~30 мин стоит делить на части.\n\n### Системные ошибки\n\nПрименимы к любому эндпоинту API Вайбкод, включая раздел AI Router:\n\n| Код | HTTP | Описание |\n|-----|------|----------|\n| `MISSING_API_KEY` | 401 | Не передан заголовок `X-Api-Key` или `Authorization: Bearer` |\n| `INVALID_API_KEY` | 401 | Ключ не существует или отозван |\n| `RATE_LIMITED` | 429 | Превышен общий лимит запросов V1-эндпоинта вне AI Router. Пауза перед повтором — в `Retry-After` |\n| `rate_limit_exceeded` | 429 | Превышен минутный лимит AI Router по API-ключу или пользователю. Уровень — в `error.scope` и заголовке `X-RateLimit-Scope`, пауза перед повтором — в `Retry-After` |\n| `INTERNAL_ERROR` | 500 | Внутренняя ошибка платформы. Повторите запрос, а если ошибка повторяется — отправьте [заявку](\u002Fdocs\u002Ffeedback) |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n---\n\n## Миграция со старых маршрутов\n\nЕсли в коде остались вызовы вида `\u002Fv1\u002Fai\u002Fchat\u002Fcompletions`, `\u002Fv1\u002Fai\u002Fmodels`, `\u002Fv1\u002Fai\u002Faudio\u002Ftranscriptions` — они продолжают работать в режиме обратной совместимости. В заголовках ответа приходит:\n\n```\nDeprecation: true\nX-Deprecated-Use: \u002Fv1\u002Fchat\u002Fcompletions\n```\n\n`X-Deprecated-Use` подсказывает канонический путь. Перенесите вызовы на канонические маршруты — это снимает заголовок `Deprecation` и убирает риск удаления старого пути в будущем.\n\n| Устаревший путь | Канонический путь |\n|-----------------|-------------------|\n| `POST \u002Fv1\u002Fai\u002Fchat\u002Fcompletions` | [`POST \u002Fv1\u002Fchat\u002Fcompletions`](\u002Fdocs\u002Fai\u002Fchat\u002Fcompletions) |\n| `GET \u002Fv1\u002Fai\u002Fmodels` | [`GET \u002Fv1\u002Fmodels`](\u002Fdocs\u002Fai\u002Fmodels\u002Flist) |\n| `GET \u002Fv1\u002Fai\u002Fmodels\u002F:modelId` | [`GET \u002Fv1\u002Fmodels\u002F:modelId`](\u002Fdocs\u002Fai\u002Fmodels\u002Fget) |\n| `POST \u002Fv1\u002Fai\u002Faudio\u002Ftranscriptions` | [`POST \u002Fv1\u002Faudio\u002Ftranscriptions`](\u002Fdocs\u002Fai\u002Faudio\u002Ftranscriptions) |\n\nМаршруты `\u002Fv1\u002Fai\u002Fusage`, `\u002Fv1\u002Fai\u002Fcredentials\u002F*`, `\u002Fv1\u002Fai\u002Fproviders` устаревшего эквивалента не имеют — это канонические пути.\n\n---\n\n## Смотрите также\n\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n- [Управление ключами](\u002Fdocs\u002Fkeys-auth)\n- [Комментарии таймлайна](\u002Fdocs\u002Ftimeline-logs)\n- [Бот-платформа](\u002Fdocs\u002Fbots)\n","2026-07-14",{}]