# AI Router

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

**Это API, а не чат на портале.** Диалогового окна для общения с моделью на портале Вайбкод нет — искать его не нужно. Запрос (промпт) вводится в вашем AI-инструменте, агенте или коде (Cursor, IDE-агент, библиотека `openai`, собственное приложение), который обращается к этому API по адресу ниже. Бесплатные модели Битрикс24 работают так же, как платные и BYOK, — через тот же API.

**Скоуп:** `vibe:ai` | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** заголовок `X-Api-Key` или `Authorization: Bearer YOUR_API_KEY`

**Платить можно подпиской.** Все модели роутера доступны не только с кошелька портала, но и по подписке Cowork/Code — в том числе из вашего собственного агента. Ключ подписки берётся на странице [Cowork/Code](/cowork), настройка популярных агентов — в разделе [Свой агент на подписке](/docs/cowork/harness).

## Совместимость с 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.

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

- [Чат-комплишены](/docs/ai/chat) — генерация ответов модели в синхронном или потоковом режиме (`Server-Sent Events`)
- [Модели](/docs/ai/models) — список доступных моделей и детали отдельной модели
- [Распознавание речи](/docs/ai/audio) — преобразование аудио в текст через Whisper Large v3 Turbo
- [Эмбеддинги](/docs/ai/embeddings) — преобразование текста в векторные представления (формат OpenAI)
- [Свои ключи (BYOK)](/docs/ai/credentials) — подключение собственных ключей провайдеров
- [Расход и лимиты](/docs/ai/consumption) — статистика по ключу, месячная квота компании и выгодные часы
- [Свой агент на подписке](/docs/cowork/harness) — подключение стороннего агента (OpenCode, Crush, Cline, Aider) с оплатой по подписке Cowork/Code вместо кошелька портала
- [Совместимость с OpenAI SDK](#совместимость-с-openai-sdk) — настройка Cursor, IDE-агентов и любых OpenAI-совместимых клиентов
- [Жизненный цикл моделей](/docs/ai/models/lifecycle) — поведение `ACTIVE` / `DEPRECATED` / `DISABLED` и связанные заголовки
- [Миграция со старых маршрутов](#миграция-со-старых-маршрутов) — для проектов, где остались вызовы `/v1/ai/chat/completions` и аналогичных

---

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

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

```bash
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?"}]
  }'
```

Ответ:

```json
{
  "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. Посмотрите доступные модели

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

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

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

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

---

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

- **Классификация лидов:** запросите лиды через [`GET /v1/leads`](/docs/entities/leads/list), пропустите через [чат-комплишен](/docs/ai/chat/completions) с `response_format: json_object`, обновите CRM-поля через [`PATCH /v1/leads/:id`](/docs/entities/leads/update).
- **Генерация контента:** прочитайте товары через [`GET /v1/products`](/docs/entity-api), сгенерируйте описания, обновите карточки в каталоге.
- **Извлечение данных:** возьмите комментарии из [`GET /v1/timeline-logs`](/docs/timeline-logs), извлеките телефон / email / название компании, запишите в CRM.
- **Чат-бот:** зарегистрируйте бота через [`POST /v1/bots`](/docs/bots/management/create), получайте события через [`GET /v1/bots/:botId/events`](/docs/bots/events), генерируйте ответ AI, отправляйте через [`POST /v1/bots/:botId/messages`](/docs/bots/messages).
- **Отчёты:** соберите данные через [`POST /v1/batch`](/docs/batch), сгенерируйте сводку, отправьте уведомление.

---

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

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

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

```bash
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"
```

Ответ:

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

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

```bash
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"}
  }'
```

Ответ:

```json
{
  "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` и отправляем в таймлайн:

```bash
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-ключе и одной авторизации — отдельных интеграций не требуется.

---

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

| Метод | Путь | Описание |
|-------|------|----------|
| POST | [`/v1/chat/completions`](/docs/ai/chat/completions) | Генерация ответа модели — синхронно или потоком |
| GET | [`/v1/models`](/docs/ai/models/list) | Список доступных моделей |
| GET | [`/v1/models/:modelId`](/docs/ai/models/get) | Детали конкретной модели |
| POST | [`/v1/audio/transcriptions`](/docs/ai/audio/transcriptions) | Распознавание речи через Whisper |
| POST | [`/v1/embeddings`](/docs/ai/embeddings) | Векторные эмбеддинги текста |
| GET | [`/v1/ai/usage`](/docs/ai/consumption/usage) | Статистика использования AI по ключу |
| GET | [`/v1/ai/quota`](/docs/ai/consumption/quota) | Процент месячной AI-квоты и разбивка по моделям |
| GET | [`/v1/off-peak`](/docs/ai/consumption/off-peak) | Расписание выгодных часов AI-квоты |
| GET | [`/v1/ai/providers`](/docs/ai/credentials/providers) | Список провайдеров для BYOK |
| GET | [`/v1/ai/credentials`](/docs/ai/credentials/list) | Список собственных ключей провайдеров |
| POST | [`/v1/ai/credentials`](/docs/ai/credentials/create) | Подключить ключ провайдера (с верификацией) |
| PATCH | [`/v1/ai/credentials/:id`](/docs/ai/credentials/update) | Обновить ключ провайдера |
| DELETE | [`/v1/ai/credentials/:id`](/docs/ai/credentials/delete) | Удалить ключ провайдера |
| POST | [`/v1/ai/credentials/:id/test`](/docs/ai/credentials/test) | Проверить ключ провайдера |
| GET | [`/v1/ai/credentials/:id/usage`](/docs/ai/credentials/usage) | Статистика использования по ключу |
| POST | [`/v1/ai/credentials/:id/fetch-models`](/docs/ai/credentials/fetch-models) | Загрузить каталог моделей у Custom-провайдера |
| GET | [`/v1/ai/credentials/:id/models`](/docs/ai/credentials/models-list) | Список моделей, привязанных к ключу |
| POST | [`/v1/ai/credentials/:id/models`](/docs/ai/credentials/models-add) | Добавить модель к ключу вручную |
| DELETE | [`/v1/ai/credentials/:credId/models/:modelRowId`](/docs/ai/credentials/models-delete) | Удалить модель, привязанную к ключу |

---

## Коды ошибок

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

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

```json
{
  "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`):

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

В V1-формате приходят штатные ошибки самих этих эндпоинтов. Непредвиденная ошибка сервера `5xx` на любом маршруте `/v1/ai/*` возвращается в сыром OpenAI-формате. В обратную сторону это тоже работает: отказы по квоте и темпу запросов (`402 ai_quota_exhausted`, `429 ai_pacing_limited`) на OpenAI-совместимых эндпоинтах приходят в конверте с `success: false`. Обработчик ошибок должен принимать оба конверта на любом из маршрутов.

| Код | HTTP | Описание |
|-----|------|----------|
| `scope_missing` | 403 | API-ключу не хватает скоупа `vibe:ai` |
| `invalid_request` | 400 | Некорректные параметры запроса |
| `no_default_model` | 400 | У портала нет ни одной доступной для вызова модели |
| `invalid_image_payload` | 400 | Некорректный `image_url` в массиве `content` |
| `invalid_language` | 400 | Код языка не соответствует `ISO 639` |
| `no_file` | 400 | Аудиофайл не передан |
| `empty_file` | 400 | Файл в multipart присутствует, но тело — 0 байт. Типичная причина — `curl -F "file=path"` без `@` |
| `ai_model_not_found` | 404 | Модель не найдена или отключена |
| `not_found` | 404 | Сущность (BYOK-ключ, модель) не найдена |
| `provider_not_found` | 404 | Провайдер не найден или отключён |
| `ai_credentials_not_configured` | 402 | Для модели нет учётных данных провайдера — подключите `BYOK` |
| `insufficient_balance` | 402 | Недостаточно средств для платной модели |
| `credential_invalid` | 422 | Ключ провайдера не прошёл верификацию |
| `already_exists` | 409 | Ключ для этого провайдера уже существует |
| `base_url_invalid` | 400 | `baseUrl` Custom-провайдера должен использовать `http` или `https` |
| `base_url_private` | 400 | `baseUrl` указывает на приватную сеть или не разрешается в IP-адрес через `DNS` |
| `not_custom_provider` | 400 | Ручная регистрация моделей разрешена только для Custom-провайдера |
| `provider_list_models_unavailable` | 200 | Custom-провайдер не поддерживает `GET /v1/models` — добавьте модели вручную |
| `ai_provider_rejected` | 400 | Провайдер отклонил сам запрос (ответ `400` или `422`). Повторять его без изменений бесполезно |
| `ai_provider_unavailable` | 502 | Внешний провайдер вернул `401`/`403`/`5xx` или сетевую ошибку |
| `ai_provider_timeout` | 503 | Апстрим не ответил вовремя: таймаут Whisper (15 минут), бюджет не-потокового запроса или ответ провайдера `408` |
| `ai_congested` | 429 | Пул AI-кластера перегружен. Запрос не выполнялся, списания нет, повторите его по заголовку `Retry-After` |
| `ai_provider_cooldown` | 429 | Кластер моделей временно недоступен, платформа держит короткую паузу. Запрос не выполнялся, списания нет, повторите его по заголовку `Retry-After`. В отличие от соседних 429 у этого ответа нет ни `X-RateLimit-Scope`, ни `X-AI-Admission` |
| `model_unavailable` | 503 | Модель отключена и резервной нет |

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

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

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

| Код | HTTP | Описание |
|-----|------|----------|
| `MISSING_API_KEY` | 401 | Не передан заголовок `X-Api-Key` или `Authorization: Bearer` |
| `INVALID_API_KEY` | 401 | Ключ не существует или отозван |
| `RATE_LIMITED` | 429 | Превышен общий лимит запросов V1-эндпоинта вне AI Router. Пауза перед повтором — в `Retry-After` |
| `rate_limit_exceeded` | 429 | Превышен минутный лимит AI Router по API-ключу или пользователю. Уровень — в `error.scope` и заголовке `X-RateLimit-Scope`, пауза перед повтором — в `Retry-After` |
| `INTERNAL_ERROR` | 500 | Внутренняя ошибка платформы. Повторите запрос, а если ошибка повторяется — отправьте [заявку](/docs/feedback) |

Полный список общих ошибок API — [Ошибки](/docs/errors).

---

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

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

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

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

| Устаревший путь | Канонический путь |
|-----------------|-------------------|
| `POST /v1/ai/chat/completions` | [`POST /v1/chat/completions`](/docs/ai/chat/completions) |
| `GET /v1/ai/models` | [`GET /v1/models`](/docs/ai/models/list) |
| `GET /v1/ai/models/:modelId` | [`GET /v1/models/:modelId`](/docs/ai/models/get) |
| `POST /v1/ai/audio/transcriptions` | [`POST /v1/audio/transcriptions`](/docs/ai/audio/transcriptions) |

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

---

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

- [Лимиты и оптимизация](/docs/optimization)
- [Ключи и авторизация](/docs/keys-auth)
- [Таймлайн CRM](/docs/timeline-logs)
- [Бот-платформа](/docs/bots)