#AI Router

Единый OpenAI-совместимый API для работы с языковыми моделями от разных провайдеров. Бесплатные модели Битрикс24 доступны сразу — для платных и для своих ключей провайдеров (BYOK) подключите учётные данные.

Скоуп: vibe:ai (добавляется автоматически ко всем API-ключам) | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: заголовок X-Api-Key или Authorization: Bearer YOUR_API_KEY

#Совместимость с OpenAI SDK

Все ответы возвращаются в сыром OpenAI-формате. Подключите любой OpenAI-совместимый инструмент (Cursor, IDE-агенты, библиотека openai) через стандартные настройки:

Base URL: https://vibecode.bitrix24.tech/v1
API Key:  ваш ключ vibe_api_... или vibe_app_...

SDK по умолчанию передаёт ключ в заголовке Authorization: Bearer — Вайбкод принимает оба варианта (X-Api-Key и Authorization: Bearer). Параметры запроса (model, messages, temperature, tools, stream, response_format) и поля ответа (id, choices, usage) соответствуют контракту POST /v1/chat/completions из OpenAI API.

#Разделы документации

• Чат-комплишены — генерация ответов модели в синхронном или потоковом режиме (Server-Sent Events)
• Модели — список доступных моделей и детали отдельной модели
• Распознавание речи — преобразование аудио в текст через Whisper Large v3 Turbo
• Свои ключи (BYOK) — подключение собственных ключей провайдеров
• Список провайдеров — справочник провайдеров для подключения BYOK
• Статистика использования — расход токенов и стоимость по API-ключу
• Совместимость с OpenAI SDK — настройка Cursor, IDE-агентов и любых OpenAI-совместимых клиентов
• Жизненный цикл моделей — поведение ACTIVE / DEPRECATED / DISABLED и связанные заголовки
• Миграция со старых маршрутов — для проектов, где остались вызовы /v1/ai/chat/completions и аналогичных

#Быстрый старт

#1. Сгенерируйте ответ бесплатной моделью

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": "user", "content": "Что такое CRM?"}]
  }'

Ответ:

{
  "id": "chatcmpl-a1a73c6eb3f180fd",
  "object": "chat.completion",
  "created": 1777289339,
  "model": "bitrix/bitrixgpt-5.5",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "CRM — это система управления взаимоотношениями с клиентами."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 18,
    "total_tokens": 30
  }
}

#2. Посмотрите доступные модели

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/models

Возвращает только те модели, для которых у портала настроены учётные данные провайдера. Бесплатные модели Битрикс24 (bitrix/*) доступны всем.

#3. Проверьте расход токенов

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/ai/usage?days=7"

#Типовые сценарии использования

• Классификация лидов: запросите лиды через `GET /v1/leads`, пропустите через чат-комплишен с response_format: json_object, обновите CRM-поля через `PATCH /v1/leads/:id`.
• Генерация контента: прочитайте товары через `GET /v1/products`, сгенерируйте описания, обновите карточки в каталоге.
• Извлечение данных: возьмите комментарии из `GET /v1/timeline-logs`, извлеките телефон / email / название компании, запишите в CRM.
• Чат-бот: зарегистрируйте бота через `POST /v1/bots`, получайте события через `GET /v1/bots/:botId/events`, генерируйте ответ AI, отправляйте через `POST /v1/bots/:botId/messages`.
• Отчёты: соберите данные через `POST /v1/batch`, сгенерируйте сводку, отправьте уведомление.

#Полный пример: распознавание звонка → классификация → запись в таймлайн

Сценарий: получить аудиозапись звонка, расшифровать через Whisper, классифицировать качество лида через JSON-ответ модели, записать результат в таймлайн сделки.

#Шаг 1. Распознавание речи

curl -X POST https://vibecode.bitrix24.tech/v1/audio/transcriptions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@call-recording.mp3" \
  -F "language=ru" \
  -F "response_format=json"

Ответ:

{
  "text": "Здравствуйте, ООО Вектор. Хотим CRM на 50 пользователей, бюджет до 500 тысяч в месяц."
}

#Шаг 2. Классификация лида с гарантированным `JSON`

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": "Классифицируй лид по тексту звонка. Верни JSON: {\"quality\": \"high|medium|low\", \"score\": 0-100, \"reason\": \"...\"}."
      },
      {
        "role": "user",
        "content": "ООО Вектор. CRM на 50 пользователей, бюджет до 500 тысяч в месяц."
      }
    ],
    "response_format": {"type": "json_object"}
  }'

Ответ:

{
  "id": "chatcmpl-acdb112cf9cdf9f9",
  "object": "chat.completion",
  "model": "bitrix/bitrixgpt-5.5",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "{\"quality\":\"high\",\"score\":88,\"reason\":\"Юрлицо, конкретный объём (50 пользователей) и бюджет 500 тысяч в месяц.\"}"
      }
    }
  ],
  "usage": {"prompt_tokens": 92, "completion_tokens": 36, "total_tokens": 128}
}

#Шаг 3. Запись результата в таймлайн сделки

Парсим choices[0].message.content как JSON и отправляем в таймлайн:

curl -X POST https://vibecode.bitrix24.tech/v1/timeline-logs \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 1234,
    "title": "Классификация AI: high (88/100)",
    "text": "Юрлицо, конкретный объём (50 пользователей) и бюджет 500 тысяч в месяц."
  }'

Все три эндпоинта живут в одном API-ключе и одной авторизации — отдельных интеграций не требуется.

#Справочник эндпоинтов

#Коды ошибок

Эндпоинты делятся на две группы по формату ответа об ошибке:

Сырой OpenAI-формат (/v1/chat/completions, /v1/models, /v1/audio/transcriptions):

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "code": "ai_model_not_found"
  }
}

type принимает значения: invalid_request_error (4xx), insufficient_quota (402), service_unavailable (503), server_error (5xx). code всегда в нижнем регистре.

V1-формат (/v1/ai/usage, /v1/ai/credentials/*, /v1/ai/providers):

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Credential not found"
  }
}

Whisper / /v1/audio/transcriptions: окно обработки — до 15 минут. Длинное / шумное аудио может занять несколько минут. Для аудио длиннее ~30 мин стоит делить на части.

#Системные ошибки

Применимы к любому эндпоинту Vibe API, включая раздел AI Router:

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

#Миграция со старых маршрутов

Если в коде остались вызовы вида /v1/ai/chat/completions, /v1/ai/models, /v1/ai/audio/transcriptions — они продолжают работать в режиме обратной совместимости. В заголовках ответа приходит:

Deprecation: true
X-Deprecated-Use: /v1/chat/completions

X-Deprecated-Use подсказывает канонический путь. Перенесите вызовы на канонические маршруты — это снимает заголовок Deprecation и убирает риск удаления старого пути в будущем.

Маршруты /v1/ai/usage, /v1/ai/credentials/*, /v1/ai/providers устаревшего эквивалента не имеют — это канонические пути.

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

• Лимиты и оптимизация — общие rate-limits Vibe API
• Управление ключами — создание API-ключей и работа со скоупами
• Comментарии таймлайна — запись результатов AI-обработки в карточку CRM
• Бот-платформа — отправка ответов AI в чаты Битрикс24