Свои ключи (BYOK)

Подключение собственных ключей провайдеров (Bring Your Own Key). Все запросы через ваш ключ идут напрямую к провайдеру и не списываются с баланса Вайбкод — вы платите провайдеру по его тарифам.

Поддерживаемые провайдеры: OpenAI, Anthropic, OpenRouter, Google Gemini, Mistral AI, Groq, Together AI, DeepSeek, Fireworks AI, Cerebras, Cohere, Minimax, Qwen, Yi, а также Custom OpenAI-Compatible для подключения любого совместимого по API сервиса (требует указать baseUrl).

Скоуп: vibe:ai

Что нужно знать перед работой

1. Один ключ на провайдера. Повторное подключение того же провайдера через POST /v1/ai/credentials вернёт 409 already_exists. Чтобы заменить ключ — обновите существующий через PATCH.
2. Верификация при сохранении. При создании и при обновлении поля credentials ключ проверяется у провайдера (POST к /chat/completions или GET /v1/models). Некорректный ключ — 422 credential_invalid с сообщением от провайдера.
3. Custom OpenAI-Compatible. Требует baseUrl в формате https://... или http://.... Приватные сети (loopback, RFC 1918, link-local) запрещены, защита от SSRF (Server-Side Request Forgery — подделка серверных запросов).
4. Таблица моделей зависит от провайдера. Для большинства провайдеров каталог фиксирован. Для Custom-сервиса каталог либо загружается с эндпоинта провайдера через fetch-models, либо собирается вручную через models-add.
5. Приоритет ключей. Ваш USER-ключ имеет приоритет над ключом, который администратор портала подключил для всех. Если оба настроены — будет использован ваш.
6. V1 управляет только USER-ключами. Ключи на уровне портала (PORTAL-scope, доступные всем участникам) подключаются администратором в кабинете Вайбкод, не через V1.

Лимиты

Лимиты считаются на портал: все API-ключи одного портала делят единый бакет. При превышении возвращается 429 с заголовком Retry-After.

Ключ не подключается из РФ {#geo-block-faq}

OpenAI, Anthropic и некоторые другие провайдеры блокируют запросы по IP сервера. Если при сохранении ключа вы видите ошибку PROVIDER_GEOBLOCKED, выберите один из двух путей:

1. Использовать OpenRouter — у них POP в Сингапуре, блокировок нет. Заведите свой ключ на openrouter.ai и подключите как BYOK-провайдер «openrouter». Через него работают модели OpenAI, Anthropic, Google, Meta и десятки других.

2. Указать свой прокси — если у вас уже есть HTTP/HTTPS-прокси в неблокируемой юрисдикции, разверните «Расширенные настройки» в форме подключения ключа и укажите URL в формате https://user:pass@host:port. Все запросы по этому ключу будут идти через ваш прокси (включая первичную проверку ключа).

Куда платформа смотрит на geo-block

Признаки, которые срабатывают как «провайдер блокирует по региону»:

• HTTP 403 + текст ответа содержит country / region / territory / unsupported location
• HTTP 451 (Unavailable For Legal Reasons)
• Структурированный код ошибки OpenAI unsupported_country_region_territory
• Сетевой обрыв на api.openai.com / api.anthropic.com (ECONNREFUSED / EHOSTUNREACH / ETIMEDOUT)

Если ключ прошёл первичную проверку, но потом сломался на реальных вызовах /v1/chat/completions, на карточке ключа в /ai появится бейдж «Заблокирован по IP». Это означает, что провайдер начал блокировать запросы после момента сохранения ключа — действия те же: добавить прокси или мигрировать на OpenRouter.

⚠️ Юридическая заметка. Использование прокси для обхода географических ограничений может нарушать Terms of Service провайдера. Ответственность за соответствие условиям использования ключа лежит на вас.

Список провайдеров

GET /v1/ai/providers

Возвращает справочник провайдеров, доступных для подключения BYOK-ключа. Используйте перед POST /v1/ai/credentials, чтобы получить корректный providerId и узнать, какие поля провайдер ожидает в credentials.

Параметры

Параметров запроса нет.

Примеры

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

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

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

curl https://vibecode.bitrix24.tech/v1/ai/providers \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/ai/providers', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
data.forEach((p) => {
  const fields = Object.keys(p.credentialFields).join(', ')
  console.log(`${p.name} (${p.slug}) — нужны поля: ${fields}`)
})

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/ai/providers', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
const openai = data.find((p) => p.slug === 'openai')
console.log('ID OpenAI:', openai.id)

Поля ответа

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

{
  "success": true,
  "data": [
    {
      "id": "anthropic",
      "name": "Anthropic",
      "slug": "anthropic",
      "credentialFields": {
        "apiKey": {
          "type": "password",
          "label": "API Key",
          "required": true
        }
      }
    },
    {
      "id": "cprv_custom_seed",
      "name": "Custom OpenAI-Compatible",
      "slug": "custom-openai-compat",
      "credentialFields": {
        "apiKey": {
          "type": "password",
          "label": "API Key",
          "required": true
        },
        "baseUrl": {
          "type": "url",
          "label": "Base URL",
          "required": true,
          "placeholder": "https://api.example.com/v1",
          "help": "OpenAI-compatible endpoint."
        }
      }
    },
    {
      "id": "openai",
      "name": "OpenAI",
      "slug": "openai",
      "credentialFields": {
        "apiKey": {
          "type": "password",
          "label": "API Key",
          "required": true
        }
      }
    }
  ]
}

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

403 scope_missing — у API-ключа нет скоупа vibe:ai:

{
  "success": false,
  "error": {
    "code": "scope_missing",
    "message": "API key does not have the vibe:ai scope"
  }
}

Ошибки

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

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

Провайдер bitrix исключён. Список не содержит платформенного провайдера bitrix — его модели (BitrixGPT 5.5, GPT-OSS, Whisper и др.) доступны всем без подключения BYOK.

Большинство провайдеров требует только apiKey. Поле baseUrl обязательно только для custom-openai-compat. Для всех остальных провайдеров baseUrl фиксирован платформой и в credentials не передаётся.

Системное имя custom-openai-compat — для произвольных сервисов. Используйте, чтобы подключить любой OpenAI-совместимый сервис: Minimax, Cerebras, Cohere, корпоративный vLLM/Ollama, локальный inference-сервер. После подключения модели либо загружаются автоматически через fetch-models, либо регистрируются вручную через models-add.

Подсказки hint. У части провайдеров поле hint содержит домен страницы получения ключа: platform.deepseek.com, console.groq.com, aistudio.google.com. Показывайте его пользователю рядом с полем ввода ключа.

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

• Подключить ключ
• Свои ключи (BYOK)
• AI Router