# Свои ключи (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.

## Лимиты

| Лимит | Значение |
|-------|----------|
| Создание ключа | 10 запросов в минуту |
| Проверка ключа | 10 запросов в минуту |
| Изменение ключа (с проверкой) | 10 запросов в минуту |
| Загрузка каталога моделей | 10 запросов в минуту |
| Регистрация / удаление модели вручную | 30 запросов в минуту |

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

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

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

1. **Использовать OpenRouter** — у них POP в Сингапуре, блокировок нет.
   Заведите свой ключ на [openrouter.ai](https://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 провайдера. Ответственность за
> соответствие условиям использования ключа лежит на вас.

## Операции

- [Список провайдеров](./credentials/providers.md) — `GET /v1/ai/providers`
- [Список ключей](./credentials/list.md) — `GET /v1/ai/credentials`
- [Подключить ключ](./credentials/create.md) — `POST /v1/ai/credentials`
- [Обновить ключ](./credentials/update.md) — `PATCH /v1/ai/credentials/:id`
- [Удалить ключ](./credentials/delete.md) — `DELETE /v1/ai/credentials/:id`
- [Проверить ключ](./credentials/test.md) — `POST /v1/ai/credentials/:id/test`
- [Статистика по ключу](./credentials/usage.md) — `GET /v1/ai/credentials/:id/usage`
- [Загрузить каталог моделей](./credentials/fetch-models.md) — `POST /v1/ai/credentials/:id/fetch-models` (Custom)
- [Список моделей ключа](./credentials/models-list.md) — `GET /v1/ai/credentials/:id/models`
- [Добавить модель вручную](./credentials/models-add.md) — `POST /v1/ai/credentials/:id/models` (Custom)
- [Удалить модель ключа](./credentials/models-delete.md) — `DELETE /v1/ai/credentials/:credId/models/:modelRowId`

## Типовой сценарий

### Подключение стандартного провайдера

1. Получите ID провайдера: [`GET /v1/ai/providers`](/docs/ai/credentials/providers).
2. Подключите ключ: [`POST /v1/ai/credentials`](./credentials/create.md). Ключ автоматически проверяется у провайдера до сохранения — если ключ некорректен, возвращается `422`.
3. После подключения модели провайдера появятся в [`GET /v1/models`](/docs/ai/models/list).

### Подключение Custom-сервиса (OpenAI-совместимого)

1. Подключите ключ с указанием `baseUrl`: [`POST /v1/ai/credentials`](./credentials/create.md) c `providerId: cprv_custom_seed`.
2. Загрузите каталог моделей: [`POST /v1/ai/credentials/:id/fetch-models`](./credentials/fetch-models.md). Если сервис не поддерживает `GET /v1/models` — добавьте модели вручную: [`POST /v1/ai/credentials/:id/models`](./credentials/models-add.md).
3. Используйте `modelId` в [чат-комплишене](/docs/ai/chat/completions).

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

- [AI Router](/docs/ai)
- [Список провайдеров](/docs/ai/credentials/providers)
- [Модели](/docs/ai/models)