Что такое Vibe API и зачем он нужен
Vibe API — это слой REST поверх Битрикс24, заточенный под работу с ИИ-агентами и автоматизацию. Вместо «сырого» REST разработчик получает entity-обёртки, которые берут на себя рутину: маппинг полей, пагинацию, очереди запросов и обработку ошибок.
Платформа покрывает 300+ методов Битрикс24:
- 39 CRM-сущностей: сделки, лиды, контакты, компании, котировки — со всеми пользовательскими полями (
UF_CRM_*). - Чаты (16 методов), боты imbot.v2 (31 метод), бизнес-процессы (5), телефония (10), триггеры, лента новостей, склады, рабочее время.
- CRUD пользовательских полей (
/v1/userfields/{entity}) для сделок, лидов, контактов, компаний, котировок — без отдельного вебхука.
Покрытие расширяется постоянно — новую обёртку под конкретный метод добавляют, по данным команды, в течение дня после запроса.
На схеме показано, как ИИ-агент, вебхук и внешний клиент обращаются к Vibe API, который абстрагирует «сырой» REST Битрикс24, обеспечивает батчинг и очередь, и передаёт запросы в CRM.
flowchart LR
AGENT[ИИ-агент] --> VAPI[Vibe API]
WEBHOOK[Вебхук / событие] --> VAPI
CLIENT[Внешний клиент] --> VAPI
VAPI -->|батчинг + очередь| B24[REST Битрикс24]
B24 --> CRM[CRM / задачи / чаты]
VAPI --> MODELS[ИИ-модели BitrixGPT]
Что Vibe API делает автоматически
Это ключевое отличие от прямых вызовов REST Битрикс24. Разработчику не нужно реализовывать следующее вручную:
| Функция | Как работает |
|---|---|
| Маппинг полей | camelCase в запросах ↔ UPPER_CASE в ответах Битрикс24 автоматически. Исключения: UF_CRM_* / ufCrm_*. |
| Авто-пагинация | limit до 5000; для дат — date windowing по большим диапазонам. |
| Фильтрация в MongoDB-синтаксисе | { closedAt: { $gte: "...", $lte: "..." }, stageSemanticId: "F" } — привычный стиль для ИИ. |
| Очередь и батчинг | Запросы выстраиваются в очередь, батчи собираются от 50 операций. Нет ошибок 503/429, не нужно следить за rate-limit. |
| Обработка ошибок | Трансформация и понятные коды; retryable-ошибки (RATE_LIMIT, BITRIX_UNAVAILABLE) обрабатываются автоматически. |
Битрикс24 намеренно ограничивает частоту запросов к своему API — Vibe API берёт управление этим ограничением на себя.
Самоописание для ИИ-моделей
Vibe API проектировался с учётом того, что его будет вызывать языковая модель, а не человек:
GET /v1/me— ключ возвращает описание своих возможностей и список доступных API. Модель может «прочитать» схему и написать корректный код без дополнительных инструкций.discover(через MCP-сервер) — схема 29 сущностей для модели.- Документация на
https://vibecode.bitrix24.tech/docsнаписана для моделей, а не для людей.
Когда лучше использовать BI-коннектор
Для выгрузки больших объёмов данных (десятки сущностей, до 10 млн строк) без пагинации и лимитов частоты удобнее API BI-коннектора Битрикс24 (ключ — в личном кабинете «Аналитика Битрикс24»). Отдельное BI-API внутри платформы VibeCode находится в разработке (на момент публикации).
Встроенный роутер ИИ-моделей: один эндпоинт, один ключ
Платформа предоставляет AI Model Router — единую точку входа ко всем моделям в OpenAI-совместимом формате. Раньше разработчику нужно было самостоятельно регистрироваться у провайдера и разбираться с разными форматами запросов.
Базовый вызов:
curl -X POST https://vibecode.bitrix24.tech/v1/ai/chat/completions \
-H "X-Api-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"Привет!"}]}'
Без указания поля model подключается бесплатная BitrixGPT 5. Один и тот же Vibe-ключ работает и для Vibe API, и для всех ИИ-моделей.
Список моделей доступен через GET /v1/ai/models.
Бесплатные модели BitrixGPT (хостинг в РФ)
Все модели линейки BitrixGPT размещены в России — данные не выходят за пределы РФ. Лимитов по количеству запросов в рамках подписки нет (на момент публикации).
| Модель | ID | Контекст | Назначение |
|---|---|---|---|
| BitrixGPT 5 | bitrix/bitrixgpt-5 |
262K | Основная: чат-боты, классификация, генерация и извлечение текста. Модель по умолчанию. |
| BitrixGPT 5.5 | bitrix/bitrixgpt-5.5 |
250K | Улучшенная текстовая модель. |
| BitrixGPT 5.5 Agent | bitrix/bitrixgpt-5.5-agent |
— | Флагман для агентов и программирования. |
| GPT-OSS 120B | bitrix/openai/gpt-oss-120b |
131K | Альтернативная бесплатная, 120 млрд параметров. |
| Gemma 4 26B | bitrix/google/gemma-4-26B-A4B-it |
— | Бесплатная. |
| Gemma 4 26B Thinking | bitrix/google/gemma-4-26B-A4B-thinking |
— | Бесплатная, с рассуждением. |
| Kimi K2.5 | bitrix/moonshotai/Kimi-K2.5 |
262K | Большая модель, длинный контекст, подходит для агентов. |
| BitrixGPT 5 Vision | bitrix/bitrixgpt-5-vl |
128K | Анализ изображений: документы, фото товаров, скриншоты. |
| Whisper Large v3 Turbo | bitrix/deepdml/faster-whisper-large-v3-turbo-ct2 |
— | Распознавание речи: аудио → текст. |
Все данные и все перечисленные модели размещены в России. Актуальный список и контекстные окна моделей — сверяйте с
https://vibecode.bitrix24.tech/docs/ai(значения волатильны).
Vision — анализ изображений
BitrixGPT 5 Vision принимает стандартный OpenAI Vision-формат: поле content передаётся массивом из объектов {type:"text"} и {type:"image_url"}.
curl -X POST https://vibecode.bitrix24.tech/v1/chat/completions \
-H "X-Api-Key: vibe_app_..." \
-H "Content-Type: application/json" \
-d '{
"model": "bitrix/bitrixgpt-5-vl",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "Распознай весь текст на картинке."},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
]
}],
"max_tokens": 1000
}'
Поддерживаемые форматы: png, jpeg, gif, webp. SVG отклоняется (XSS-риск). Картинка — до 20 MiB декодированных; всё тело запроса — до 30 MB.
Vision-модели в платформе: bitrix/bitrixgpt-5-vl, а также Anthropic-модели через BYOK (claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001) — платформа сама конвертирует запрос в нативный формат Anthropic.
Типичные применения: - Распознавание визиток и сохранение данных в CRM. - Чтение документов и сканов. - Анализ фотографий товаров для каталога. - Разбор скриншотов ошибок при техподдержке.
Коды ошибок: 400 invalid_image_payload с указанием причины и индекса проблемного вложения (например, image[1]: unsupported mime "image/svg+xml").
Whisper — транскрибация звонков и голосовых
Whisper Large v3 Turbo принимает аудиофайл и возвращает текст:
curl -X POST https://vibecode.bitrix24.tech/v1/ai/audio/transcriptions \
-H "X-Api-Key: YOUR_KEY" \
-F file=@audio.mp3
Типичные применения: - Транскрибация звонков из телефонии по карточке сделки. - Расшифровка голосовых сообщений из чатов. - Автоматические протоколы внутренних встреч.
Важно: разделения по спикерам в базовой модели нет. В агенте Hermes расшифровка по ролям «менеджер/клиент» есть. При больших объёмах расшифровок (десятки тысяч в день) платформа вводит лимиты или тарификацию. Если в вашей подписке Битрикс24 уже есть готовые расшифровки звонков — рекомендуется использовать их, а не прогонять аудио через Whisper повторно.
Подробнее о сценариях ИИ-анализа звонков — в материале AI-анализ звонков в Битрикс24: распознавание, скоринг качества, типичные ошибки менеджеров.
BYOK — подключение своих ключей провайдеров
BYOK (Bring Your Own Key) позволяет использовать платные модели через единый API платформы, не меняя код. Поддерживаемые провайдеры: OpenAI, Anthropic, OpenRouter и любые OpenAI-совместимые эндпоинты.
Доступные платные модели (на момент публикации): GPT-4o (128K), GPT-4o Mini (128K), o3-mini (200K, reasoning), Claude Sonnet 4.5/4.6 (200K), Claude Haiku 4.5 (200K), Claude Opus 4.6. Цены — по тарифам провайдера, списание ежедневно с баланса.
Ограничение для РФ: для доступа к OpenAI и Anthropic из российских IP-адресов требуется прокси. Это нужно учитывать при настройке BYOK.
Идентификаторы моделей в запросах: anthropic/claude-opus-4-6, anthropic/claude-sonnet-4-6, anthropic/claude-haiku-4-5-20251001, openai/gpt-4o-mini — и другие из списка GET /v1/ai/models.
Read-only ключи: защита CRM от ИИ
Каждый Vibe-ключ имеет переключатель «Режим доступа»:
- Чтение и запись — полный доступ.
- Только чтение — любые операции создания, изменения и удаления блокируются на стороне VibeCode до того, как запрос достигает Битрикс24. Ошибка:
WRITE_BLOCKED_READONLY_KEYс указанием заблокированного метода.
Важный контекст: изменения полей CRM не логируются на пользовательском уровне в Битрикс24. ИИ-агент, ошибочно перезаписавший поля массово, может быть замечен поздно, а откат из резервной копии приведёт к потере свежих данных. Именно поэтому для аналитических агентов рекомендуется выдавать read-only ключ — даже если модель решит «оптимизировать воронку» и попробует удалить сделки, запрос не пройдёт.
Администратор в разделе /keys может установить политику: все новые ключи — только чтение, с индивидуальными исключениями. Владелец ключа получает уведомление от Companion-бота при изменении его настроек.
Это особенно актуально при построении AI-помощников в Битрикс24 — аналитических ботов и классификаторов, которым не нужен полный доступ к CRM.
Ключевые эндпоинты: справочник
Базовый URL: https://vibecode.bitrix24.tech
Авторизация: заголовок X-Api-Key: <ключ> (или Authorization: Bearer <ключ>).
ИИ-модели
| Эндпоинт | Описание |
|---|---|
POST /v1/ai/chat/completions |
Чат с моделями (OpenAI-совместимо). Алиас: /v1/chat/completions. |
POST /v1/ai/audio/transcriptions |
Whisper: аудио → текст. Алиас: /v1/audio/transcriptions. |
GET /v1/ai/models |
Список доступных моделей. |
Служебные
| Эндпоинт | Описание |
|---|---|
GET /v1/me |
Самоописание ключа: возможности и доступные API. |
GET /v1/guide |
Гайд по платформе. |
POST /v1/feedback |
Обратная связь от агента. |
GET/POST /v1/keys |
Управление ключами. |
Entity API (CRM и другие сущности)
| Эндпоинт | Описание |
|---|---|
POST /v1/{entity}/search |
Поиск по сущности (deals, leads, contacts, companies, tasks…). |
GET /v1/{entity}/fields |
Поля сущности. |
GET/POST/PATCH/DELETE /v1/{entity}/:id |
CRUD по сущности. |
GET/POST /v1/userfields/{entity} |
Пользовательские поля сущности. |
GET /v1/chats/recent |
Список последних чатов. |
GET /v1/workday/status |
Статус рабочего дня. |
POST /v1/bizproc-activities |
Активности бизнес-процессов (требует OAuth + scope bizproc). |
Намеренно удалён: универсальный
POST /v1/call— заменён entity-обёртками с трансформацией полей и авто-пагинацией.
Для сложных бизнес-процессов, которые вызывают Vibe API, изучите также вебхуки смарт-процессов в Битрикс24 — там описаны рабочие паттерны выборки полей.
Коробочная версия и Vibe Connect
ИИ Битрикс24 (CoPilot / BitrixGPT) доступен и в коробочной (on-premise) версии. Для зоны .ru поддержка появилась в 2026 году. Владелец коробки получает те же AI-сценарии: CoPilot в чатах, генерация текстов в CRM, анализ и расшифровка звонков, умные подсказки в задачах.
Vibe Connect — модуль подключения коробочного Битрикс24 к платформе VibeCode. На момент публикации находится на стадии тестирования. Основной сценарий для VibeCode сейчас — облачный портал (в том числе тестовый).
Преимущество on-premise: данные не покидают инфраструктуру компании, а возможности ИИ при этом сохраняются. Актуальный статус Vibe Connect — на https://vibecode.bitrix24.tech/docs.
Коды ошибок: справочник
| Код | Значение |
|---|---|
WRITE_BLOCKED_READONLY_KEY |
Запись заблокирована read-only ключом; указывает заблокированный метод Б24. |
RATE_LIMIT, BITRIX_UNAVAILABLE |
Временные ошибки (retryable). |
invalid_image_payload (400) |
Проблема с изображением для Vision: неверный MIME или размер; указывает индекс вложения. |
NO_USER_TOKEN |
Для публикации приложения нужен vibe_session_*. |
DEPLOY_FAILED |
Healthcheck не прошёл: приложение не ответило 200 на проверяемом пути. |
TRIAL_PORTAL_LIMIT |
Превышен лимит серверов на триальном портале (1/1). |
APP_RESOLVE_FAILED |
Не удалось сопоставить application_token с приложением. |
NOT_OAUTH_APP, BIND_FAILED, EVENT_BOUND_ELSEWHERE |
Ошибки подписки на события портала. |
VALIDATION_ERROR |
Например, при некорректном placement.bind. |
АС Проект — Платиновый партнёр Битрикс24 — помогает внедрить ИИ-инструменты и собрать приложения на VibeCode под задачи вашего бизнеса.