1 line
392 KiB
JSON
1 line
392 KiB
JSON
{"repo": "basaltcode/neurogate", "files": {"docs/providers-setup.md": {"9223694687c837664c9f551600eef17cbcdc4a6f": {"t": 1785746555.8734715, "n": 39784, "h": "70901a4625a29f2e", "c": "# Как получить API-ключи провайдеров\n\nПошаговая инструкция для всех провайдеров из [config.yaml.example](../config.yaml.example) — где зарегистрироваться, где взять ключ, какая переменная в [.env.example](../.env.example), важные нюансы.\n\n**Минимум для старта**: достаточно 1-2 ключей — neurogate пропустит позиции, у которых ключ пустой, и пойдёт дальше по цепочке. Стартап-репорт на консоли подскажет, какие именно env-vars не заполнены и какие провайдеры это включит. Начать проще всего с **Groq** (самый быстрый onboarding) + **Gemini** (самая жирная квота на 1 ключ).\n\n## Free quota at a glance\n\nСводная таблица. Две колонки маркеров:\n\n**Cap (квота):**\n- 🟢 **effectively unlimited** — нет суточного/месячного потолка по запросам, ограничение только на RPM (или concurrency). Можно жечь хоть 24/7.\n- 🟡 **RPD-capped** — есть суточный потолок (счётчик ресетится 00:00 UTC, обычно).\n- 🔵 **monthly / token quota** — потолок по токенам или вызовам в месяц / в год.\n- 🟣 **anonymous / no key** — без ключа.\n\n**Privacy (что провайдер делает с твоими промптами):**\n- 🔒 **private** — провайдер заявляет «не обучаем на твоих данных» (free tier).\n- ⚠️ **trains on free tier** — на free-тире промпты/ответы могут уходить в обучение. Не клади чувствительное.\n- 🟣 **public-by-design** — community-инфраструктура, твои промпты видны другим.\n\nЦифры на free-тирах часто меняются — `/v1/models` и dashboard покажут реальную картину. Privacy-метки взяты из публично заявленных политик; они не аудит, а ориентир.\n\n| Cap | Privacy | Провайдер | ENV-переменная | Лимит | Phone | Card | Особенность |\n|---|---|---|---|---|---|---|---|\n| 🟢 | 🔒 | **NVIDIA NIM** | `NVIDIA_API_KEY` | 40 RPM, без RPD | нет | нет | TTFB медленный — в `unlimited`/фоллбэк. |\n| 🟢 | 🔒 | **Z.ai** | `ZAI_API_KEY` | concurrency-only | нет | нет | GLM-4.5-Flash permanent free. China upstream — оф. заявляет «no training», но юрисдикция КНР. |\n| 🟢 | 🔒 | **Cerebras** | `CEREBRAS_API_KEY` | 5–30 RPM, без RPD | да | нет | Узкий выбор моделей, но потолка нет. Enterprise-friendly TOS. |\n| 🟢 | ⚠️ | **Mistral** | `MISTRAL_API_KEY` | ~4 RPM, без RPD | да | нет | Experiment plan. На free тренируется на твоих промптах. Paid plan — opt-out. |\n| 🟡 | 🔒 | **SambaNova** | `SAMBANOVA_API_KEY` | 20 RPD **на модель** | нет | нет | 4 модели = 80 RPD на ключ. Enterprise-friendly. |\n| 🟡 | ⚠️ | **Groq** | `GROQ_API_KEY` | 30 RPM, 1k–14.4k RPD | нет | нет | Самый быстрый onboarding. Privacy policy позволяет использовать промпты для improvements. |\n| 🟡 | ⚠️ | **Gemini (AI Studio)** | `GEMINI_API_KEY` | 10 RPM, 250-1500 RPD | нет | нет | Per-project: 2-3 GCP-проекта = ×N квота. **На free tier Google использует промпты для улучшения моделей.** Paid Vertex — opt-out. |\n| 🟡 | 🔒 | **Cloudflare Workers AI** | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` | 300 RPD (Llama 70B) | нет | нет | Edge inference, image gen бесплатно. CF не тренирует. |\n| 🟡 | 🔒 | **GitHub Models** | `GITHUB_MODELS_TOKEN` | 50–150 RPD | нет | нет | gpt-5-mini в free tier. Microsoft не тренирует на промптах GitHub Models. |\n| 🟡 | ⚠️ | **OpenRouter (free)** | `OPENROUTER_API_KEY` | 20 RPM, 50 RPD (1000 с $10) | нет | нет\\* | Каждая `:free`-модель имеет свою policy — у некоторых тренировка включена. Читай каточку модели. |\n| 🟡 | ⚠️ | **FreeTheAi** | `FREETHEAI_API_KEY` | 10 RPM, 1 concurrent | нет (Discord) | нет | **Требует daily Discord `/checkin`**. Privacy не задекларирована — считай что промпты видят. |\n| 🟡 | 🔒 | **OVHcloud** | — (anon) | 2 RPM на IP | нет | нет | EU-инфра, без ключа, не тренирует. |\n| 🔵 | ⚠️ | **GigaChat (Sber)** | `GIGACHAT_AUTH_KEY` | Freemium quota / год | да (РФ) | нет | Чат слабоват, но **есть бесплатная Kandinsky image gen**. Free tier — обучаются. См. §11. |\n| 🔵 | ⚠️ | **HuggingFace** | `HF_TOKEN` | ~$0.10/мес общий кредит | нет | нет | Кредит на paid sub-providers. Каждый sub-provider — своя privacy policy. |\n| 🔵 | ⚠️ | **DeepSeek** | `DEEPSEEK_API_KEY` | 5M tok signup credits, дальше PAYG | да | нет | Off-peak 50–75% скидка. **CN-юрисдикция, тренируются на промптах.** |\n| 🔵 | ⚠️ | **Alibaba DashScope Intl** | `DASHSCOPE_API_KEY` | 1M tok / model × 90 дней | да | да | Singapore region, 1M context на флагманах. CN-юрисдикция. |\n| 🔵 | 🔒 | **Cohere** | `COHERE_API_KEY` | 20 RPM, 1000 calls/мес | нет | нет | **Non-commercial only** на free tier (ToS). Не тренируются. |\n| 🟣 | 🟣 | **LibreTranslate** | — (anon) | varies | нет | нет | Public mirror. Логи могут вестись на стороне зеркала. |\n| 🟣 | 🟣 | **MyMemory** | `MYMEMORY_CONTACT_EMAIL` (опц) | 5k–50k chars/IP | нет | нет | Community translation memory — твои тексты могут пополнять корпус. |\n| 🟣 | 🔒 | **Edge TTS** | — (anon) | без лимита | нет | нет | MS Edge — голос синтезируется serverside, текст не сохраняется. |\n| 🟣 | 🟣 | **AIhorde** | — (anon) | community queue | нет | нет | Распределённый inference — твой prompt видит worker, который на нём генерирует картинку. |\n\n\\* OpenRouter не требует карту для базового free tier, но $10 однократный депозит поднимает лимиты в 20 раз.\n\n**TL;DR (квоты).** Если нужен **24/7-бэкбон** — собирай цепочку из 🟢 (NVIDIA + Z.ai + Cerebras + Mistral): они не упираются в суточный потолок. Если нужен **широкий пул моделей** — добавляй 🟡 (Groq, Gemini, OpenRouter, GitHub) — они дают разнообразие, но ресетятся каждые 24ч. 🔵 — на конкретные ниши (Cohere для не-коммерческого RU, DeepSeek для signup-кредитов, GigaChat для Kandinsky).\n\n**TL;DR (privacy).** Для **чувствительного трафика** (внутренние документы, персональные данные клиентов) бери только 🔒: NVIDIA, Cerebras, Cloudflare, GitHub Models, Cohere, SambaNova. Z.ai заявляет no-training, но юрисдикция КНР — для коммерческой тайны не годится. Всё что 🟣 — public-by-design, такие провайдеры можно использовать только для безличных текстов (переводы общего назначения, генерация фоновых картинок). Если в чейне смешаны провайдеры — фоллбэк может уйти на ⚠️-провайдера; для строгого режима оставь только 🔒-провайдеров либо подними отдельный `chains: private:` под чувствительный трафик.\n\n### Quick suggestion: какие 2-3 ключа добавить первыми\n\n- **Самый быстрый старт:** Groq (без верификаций) → мгновенный отклик и приличная квота.\n- **Долгий контекст / vision:** Gemini.\n- **Бэкбон без RPD-капа:** Cerebras (одно подтверждение телефона) или NVIDIA.\n- **Русский:** Yandex Alice (`yandex_foundation` kind) — на наш опыт лучше GigaChat для RU.\n- **Картинки бесплатно:** Cloudflare (FLUX/SDXL без RPD на image gen) или GigaChat (Kandinsky — фотореализм держит лучше FLUX).\n\n## Провайдеры\n\n### 1. Gemini (Google)\n\n- **Регистрация**: любой Google-аккаунт\n- **Получить ключ**: https://aistudio.google.com/apikey → *Create API key*\n- **ENV**: `GEMINI_API_KEY`\n- **Нюанс**: квота считается **per-project**, не per-key. Если завести 2-3 GCP-проекта на том же Google-аккаунте и сгенерить по ключу в каждом, получишь 2-3× квоту легально (TOS это разрешает — дубликаты запрещены только на уровне аккаунтов). Дополнительные ключи можно прописать как `GEMINI_API_KEY_2`, `GEMINI_API_KEY_3` и завести дубликаты провайдеров в `config.yaml` с разными `api_key_env`.\n\n### 2. Groq\n\n- **Регистрация**: https://console.groq.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Create API Key*\n- **ENV**: `GROQ_API_KEY`\n- **Нюанс**: самый быстрый провайдер в цепочке (300-1000+ токенов/сек). Free tier даёт 1000 RPD на `llama-3.3-70b-versatile` и 14400 RPD на `llama-3.1-8b-instant`. Дубликаты аккаунтов Groq ловит и банит оба — **не регистрируй второй аккаунт** с того же IP/телефона/карты.\n\n### 3. Cerebras\n\n- **Регистрация**: https://cloud.cerebras.ai (требует подтверждение телефона)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `CEREBRAS_API_KEY`\n- **Нюанс**: нет суточного лимита, но free tier сейчас узкий — реально работают только `qwen-3-235b-a22b-instruct-2507` (5 RPM) и `llama3.1-8b` (30 RPM). Более крупные модели (llama-3.3-70b, gpt-oss-120b) депрекейтнуты или paid-only.\n\n### 4. SambaNova\n\n- **Регистрация**: https://cloud.sambanova.ai (Google / email)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `SAMBANOVA_API_KEY`\n- **Нюанс**: 20 RPD **на каждую модель**, а не на аккаунт — 4 SambaNova-позиции в цепочке дают суммарно 80 RPD на один ключ. Лимит читается из заголовка `x-ratelimit-limit-requests-day` в ответе.\n\n### 5. NVIDIA NIM\n\n- **Регистрация**: https://build.nvidia.com (email, developer-программа)\n- **Получить ключ**: профиль справа вверху → *Get API Key* → выдают ключ вида `nvapi-...`\n- **ENV**: `NVIDIA_API_KEY`\n- **Нюанс**: формально **только для research/dev/test** — production TOS требует AI Enterprise license (~$4500/GPU/год). Для личного бота не критично. Нет суточного лимита, только RPM (40 на большинстве моделей).\n\n### 6. Z.ai (GLM)\n\n- **Регистрация**: https://z.ai (international) или https://open.bigmodel.cn (Китай — для аккаунтов из РФ/СНГ)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `ZAI_API_KEY`\n- **Нюанс**: `glm-4.5-flash` — **permanent free**, без RPD-лимита. В конфиге стоит `extra_body: { thinking: { type: disabled } }` — это принудительно отключает reasoning-режим (по умолчанию модель тратит токены на chain-of-thought, что режет скорость). Z.ai официально заявляет «no training on API data» — ок для чувствительного трафика.\n\n### 7. OpenRouter\n\n- **Регистрация**: https://openrouter.ai (Google / GitHub / MetaMask)\n- **Получить ключ**: https://openrouter.ai/keys → *Create Key*\n- **ENV**: `OPENROUTER_API_KEY`\n- **Нюанс**: `:free` модели делят глобальный пул 50 RPD на всех пользователей планеты — часто упирается в лимит к вечеру UTC. **Однократный депозит $10** поднимает RPD → 1000 на все `:free` модели (сами $10 не сгорают, лежат на балансе). Это единственное действие с 20× ROI на лимиты — см. «Платные расширения».\n\n### 8. Cloudflare Workers AI\n\n- **Регистрация**: https://dash.cloudflare.com (email)\n- **Получить ключ**: *My Profile* (правый верх) → *API Tokens* → *Create Token* → шаблон *Workers AI* (или custom: permission `Account → Workers AI → Read` + `Edit`)\n- **Получить Account ID**: на главной странице dashboard в правом сайдбаре — строка *Account ID*\n- **ENV**: `CLOUDFLARE_API_KEY` (токен) + `CLOUDFLARE_ACCOUNT_ID`\n- **Нюанс**: единственный провайдер, которому нужны **две** переменные. Account ID нельзя передать как env — Cloudflare вшивает его в URL запроса. 300 RPD на Llama 70B fp8-fast.\n\n### 9. GitHub Models\n\n- **Регистрация**: любой GitHub-аккаунт\n- **Получить токен**: https://github.com/settings/personal-access-tokens → *Generate new token (fine-grained)* → Account permissions → **Models: Read-only**\n- Классический PAT (`settings/tokens`) тоже работает, но fine-grained безопаснее — скоуп только на Models, не трогает репы.\n- **ENV**: `GITHUB_MODELS_TOKEN`\n- **Нюанс**: endpoint `https://models.github.ai/inference`, жёсткий потолок 8K токенов на запрос (input+output). Лимиты 50-150 RPD по моделям, считаются на токен.\n\n### 10. Mistral La Plateforme\n\n- **Регистрация**: https://console.mistral.ai (email + SMS-верификация)\n- **Получить ключ**: *API Keys*\n- **План**: выбрать **Experiment** (бесплатный) — даёт доступ к `mistral-large-latest` и остальным флагманам\n- **ENV**: `MISTRAL_API_KEY`\n- **Нюанс**: **обязательно зайти** в *Admin* → *Privacy* и **выключить опцию использования данных для обучения** — по умолчанию она включена. Без этого твои запросы уходят на training. Лимит ~4 RPM (заголовок `x-ratelimit-limit-req-minute`), не 60 как в старых доках.\n\n### 11. HuggingFace Inference Providers Router\n\n- **Регистрация**: любой HuggingFace-аккаунт https://huggingface.co\n- **Получить токен**: *Settings* → *Access Tokens* → *Create new token* → тип **Read**\n- **ENV**: `HF_TOKEN`\n- **Нюанс**: HF проксирует запросы к paid sub-providers (Novita, Cerebras, Together, …) через единый OpenAI-совместимый endpoint. Free tier даёт **~$0.10/мес общего кредита** на все sub-providers — этого хватает на эксперименты, не на постоянный трафик. **PRO-подписка ($9/мес)** даёт $2 кредита/мес. Модель указывается как `<repo>:<sub-provider>`, например `meta-llama/Llama-3.3-70B-Instruct:novita`.\n\n### 12. GigaChat (SberDevices)\n\n- **Регистрация**: https://developers.sber.ru/studio (требует подтверждённый аккаунт Сбера, телефон РФ)\n- **Получить ключ**: *Личное пространство* → *Мой GigaChat API* → *Получить новый ключ* → выдают `Authorization key` (это уже base64 от `client_id:client_secret`, готовый для `Basic`-авторизации)\n- **ENV**: `GIGACHAT_AUTH_KEY` (значение строки *Authorization key* как есть)\n- **Scope**: `GIGACHAT_API_PERS` — **Freemium** для физлиц с годовой квотой токенов (точные цифры Сбер периодически меняет — смотри актуальное на странице тарифа). По нашему опыту, на личное использование хватает с запасом.\n- **Чат vs картинки**: текстовые модели (GigaChat 2 / 2-Pro / 2-Max) на наш опыт **слабее даже отдельных Qwen / GLM** на русском, и заметно отстают от Yandex Alice. Но **бесплатная Kandinsky image gen** в этом же ключе — единственный способ получить русскоязычно-обученную text-to-image модель «из коробки», и она хорошо держит фотореализм когда в промпте есть «digital painting» / «oil painting» (где FLUX даёт «пластик»). Стоит держать в `image_gen` chain ради этого.\n- **Нюанс 1**: GigaChat отдаёт сертификат, подписанный *Russian Trusted Root CA* — стандартные системные truststore (на macOS/Linux вне РФ) его не знают. В конфиге для `kind: gigachat` стоит `verify_ssl: false`. Для прода — добавить Russian Trusted Sub CA в системный truststore.\n- **Нюанс 2**: авторизация двухступенчатая — провайдер обменивает `Authorization key` на короткоживущий OAuth access-token и кэширует его. Этот flow реализован внутри `kind: gigachat`, ничего вручную делать не нужно.\n- **Биллинг и расход**: https://developers.sber.ru/studio (раздел *Проекты* → *Лицевой счёт*).\n\n### 13. FreeTheAi\n\n- **Регистрация**: только через Discord. Зайти на сервер → https://discord.gg/secrets → команда `/signup` в канале #api-keys (https://discord.com/channels/1461555807731585158/1473159205048553705) → бот пришлёт ключ вида `sta_…` в DM. Если потерял — `/resetkey`.\n- **ENV**: `FREETHEAI_API_KEY`\n- **Лимиты**: 10 RPM + **1 concurrent** на ключ — последовательные вызовы, никакого parallel.\n- **Каталог**: ~16 252 алиасов. Префиксы: `cat/*` (gpt-5/claude/gemini frontier через прокси), `bbg/*` (DeepSeek/GLM/Kimi/MiniMax reasoning), `bbl/*` (Gemini/GPT non-reasoning), `or/*` (OpenRouter passthrough), `vhr/*` (image-gen scrap из Vheer), `img/gpt-image-2` (image gen+edit b64), `fth/*` (16k случайных HF моделей — почти всегда мусор). Не все алиасы реально работают — `glm/glm-5.1` (#1 в leaderboard) и `cat/gemini-3-1-pro` возвращают 400/timeout. Перед использованием — пробовать.\n- **⚠️ Главный нюанс — DAILY /checkin**: ключ блокируется **каждые 24 часа**. Чтобы разлочить — заходишь в Discord, в тот же канал #api-keys пишешь `/checkin`, бот возвращает «ключ активен на 24h». Без этого все запросы получают `HTTP 403 daily_checkin_required`.\n- **Автоматизировать /checkin НЕЛЬЗЯ**:\n 1. Discord ToS запрещает self-bot'ы (использование своего user-токена для скриптов) — ловят и банят аккаунт.\n 2. Обычные боты Discord не могут вызывать slash-команды других ботов (by design платформы).\n 3. Browser-automation поверх web-Discord — та же категория self-bot, ban guarantied.\n 4. FreeTheAi специально поставили /checkin как защиту от abuse — обходить = бан и от них тоже.\n- **Когда использовать**:\n - Ad-hoc-запросы для тестов (`model: \"freetheai:cat/gpt-5\"`) — 24h cooldown терпим, если не забыл сделать /checkin утром.\n - Не для продовых chains (без daily-checkin сервис ляжет).\n- **Bait-and-switch**: проверка identity показала, что `cat/claude-4-6-sonnet` отвечает «built by Tiny» — это НЕ Claude. `cat/gpt-5` идентифицируется как OpenAI, но без гарантий. `bbg/deepseek-v4-pro` выдаёт gibberish. Перед интеграцией каждой модели в логику — прогнать identity-test.\n- **Image-gen**: `vhr/*` модели возвращают URL'ы на `access.vheer.com` — это прокси на бесплатный Vheer.com сервис, файлы хранятся у них. `img/gpt-image-2` отдаёт b64 (~650KB на запрос) — единственная модель, поддерживающая edits.\n\n### 14. DeepSeek (direct API)\n\n**Пошагово (получить ключ):**\n\n1. Открой https://platform.deepseek.com → *Sign Up* (Google или email)\n2. Phone verify — российские номера принимает (МТС/Мегафон/Билайн/Tele2). Если по какой-то причине не принимает твой номер — попробуй через Google-аккаунт.\n3. После входа: левое меню → *API Keys* → *Create new API key* → дать любое имя → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается **один раз** — потом только regenerate.\n4. В `.env` локально и на проде:\n ```\n DEEPSEEK_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **5M токенов signup credits** + 7-14 дней без RPM-лимитов. Этого хватит на много экспериментов.\n- Модели: `deepseek-chat` (V3.2) и `deepseek-reasoner` (R1/R2).\n\n**Когда signup credits закончатся (опционально):**\n\n- $2 топ-ап ≈ 170 ₽ → месяцы PAYG-работы (`deepseek-chat` $0.28/$0.42 за 1M, `deepseek-reasoner` сопоставимо).\n- Off-peak 16:30–00:30 UTC — скидка 50% на V3, 75% на R1.\n- Prefix caching: cache hit в 4–10× дешевле miss. Структурируй промпты так, чтобы стабильный префикс (system + RAG) шёл первым, юзер-ввод — последним.\n- ⚠️ **Не включай auto-recharge** — карта будет молча докидывать каждый раз когда баланс падает.\n- ⚠️ Российские карты Visa/MC топ-ап **не примет**. Варианты: карта дружественной страны (Казахстан/Армения/Грузия), Wise/Revolut, виртуалка от иностранного fintech.\n\n**Подводные камни:**\n\n- **Privacy**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**. Если через шлюз идут чувствительные данные клиентов — либо удали DeepSeek из chain, либо ставь его последним позади cohere/openrouter/sambanova.\n- **Из России без VPN**: иногда нестабильные 5xx-ответы. Держи fallback в той же chain ниже — он сработает автоматически.\n\n**kind**: `deepseek`. Provider в config.yaml — простая запись с `model: deepseek-chat` или `model: deepseek-reasoner`. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 15. Alibaba DashScope International (Qwen)\n\n**⚠️ Самый муторный из четырёх. Делай утром, на это уйдёт 20-30 минут.**\n\n**Пошагово (получить ключ):**\n\n1. Открой https://accountclient.alibabacloud.com/intl → *Sign Up*\n2. **Регион — обязательно Singapore.** US/HK/EU/China версии free quota НЕ дают. Если на этапе onboarding спрашивает регион — выбирай Singapore. Если уже зарегистрировался в другом регионе — придётся завести отдельный аккаунт.\n3. Phone verify (российские номера принимает).\n4. **Карта обязательна** — для Real-name Verification. С карты ничего не списывается, но без привязки free quota не активируется.\n - ⚠️ Российские карты Visa/MC **не пройдут**.\n - Варианты:\n - Карта дружественной страны (Казахстан / Армения / Грузия)\n - Wise / Revolut если есть\n - Виртуальная карта от иностранного fintech (Pyypl, Genome, etc.)\n5. После Real-name Verification → открыть https://bailian.console.alibabacloud.com (Model Studio, регион Singapore)\n6. Левое меню → *API-KEY* → *Create* → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается полностью один раз.\n7. В `.env` локально и на проде:\n ```\n DASHSCOPE_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **1M токенов на каждую модель** × **90 дней** с момента активации. Десятки моделей в каталоге → десятки миллионов токенов суммарно.\n- Флагманы: `qwen3.6-plus` (топ-3 на OpenRouter trafficу, 1M context, всегда-вкл CoT), `qwen3.6-max-preview`, `qwen3-coder-480b-a35b-instruct`, `qwen3-next-80b-a3b-instruct/thinking`, `qwen3-vl-plus`.\n\n**После 90 дней**: paid-only. Поставь напоминание `/schedule` за неделю до истечения — посмотрим использование и решим продлять или уйти на DashScope-paid.\n\n**Подводные камни:**\n\n- **Регион Singapore ОБЯЗАТЕЛЬНО**. Endpoint в config.py уже забит: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. Если у тебя аккаунт в другом регионе — ключ будет работать, но free quota = 0.\n- **Privacy**: Alibaba явно заявляет «will never use your data for model training», данные в Сингапуре → **можно использовать с PII** в отличие от китайского endpoint DeepSeek.\n- **Real-name Verification может зависнуть на сутки** — в первый раз. Если статус «pending» больше 24ч — открыть тикет в support.\n\n**kind**: `dashscope`. Provider в config.yaml — простая запись с `model: qwen3.6-plus` или другой моделью. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 16. Cohere (Command-A / c4ai-aya — для русского)\n\n- **Регистрация**: https://dashboard.cohere.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Generate Trial Key*\n- **ENV**: `COHERE_API_KEY`\n- **Free tier**: 20 RPM на модель, 1000 calls/месяц (≈33 RPD safe-floor).\n- **Модели**: `c4ai-aya-expanse-32b/8b` — multilingual, **сильный русский**. `c4ai-aya-vision-32b/8b` — vision. `command-a-03-2025` — флагман общего назначения. `command-a-reasoning-08-2025` — reasoning. `command-a-translate-08-2025` — translation.\n- **ToS**: free tier — **non-commercial only**. Для open-source / личных проектов ок. Если кто-то форкнет коммерчески — нарушение. Помечай в README.\n- **Особенность реализации**: Cohere v2 /chat — собственный response shape (`{message: {content: [{type:'text', text:...}]}}`), не OpenAI-compat. Streaming эмулируется одним SSE chunk'ом из полного ответа (Cohere v2 SSE имеет свой формат, дешевле fake-stream чем переводить).\n- **kind**: `cohere_chat` (для chat) или `cohere` (для translate-only). Эмбеддинги отдельно — `cohere_embed`.\n\n### 17. OVHcloud AI Endpoints (anonymous, без ключа)\n\n- **Регистрация**: НЕ ТРЕБУЕТСЯ. Endpoint анонимный.\n- **ENV**: НЕТ. В config.yaml запись `kind: ovhcloud` без `api_key_env`.\n- **Endpoint**: `https://oai.endpoints.kepler.ai.cloud.ovh.net/v1` — OpenAI-совместимый.\n- **Лимит**: 2 RPM **на IP** на модель. Без ключа — прозрачный rate-limit, при превышении 429.\n- **Каталог**: 40+ open-моделей, EU-host (Франция/Германия). Llama 3.x, Mistral, Qwen, Mixtral, gpt-oss-120b, и т.д.\n- **Когда использовать**: исключительно как **deep fallback / last-resort** в конце chain — «лучше отдать что-то, чем 503». В основной chain ставить нет смысла из-за 2 RPM на IP.\n- **Реализация**: `OpenAICompatProvider` пропускает `Authorization` header при пустом `api_key` (см. providers.py — изменение из этого PR).\n- **kind**: `ovhcloud`.\n\n## Платные расширения (опционально)\n\nНиже — одноразовые или recurring платные действия с непропорционально большим профитом на лимиты.\n\n### OpenRouter — $10 депозит → 20× квоты\n\n**Что делает**: однократный пополнение на $10 поднимает 50 RPD → **1000 RPD** на все `:free` модели (DeepSeek R1/V3.2, Llama 4 Maverick/Scout, Qwen3 235B, GLM-5 `:free`, Kimi K2 `:free`, MiniMax M2 `:free`, Qwen3-Coder 480B `:free`).\n\n**Как**: *Settings* → *Credits* → пополнить любую сумму ≥ $10. Сами $10 остаются на балансе и тратятся только если ты явно вызовешь платную модель. Для `:free` — это просто unlock лимита.\n\n**После депозита**: в `config.yaml` обновить `rpd: 50` → `rpd: 1000` на всех позициях с `kind: openrouter`.\n\n### xAI Grok — $25 signup + $150/мес recurring\n\n- **Регистрация**: https://console.x.ai (phone verify)\n- **Signup**: $25 кредитов на 30 дней\n- **Data-sharing program**: opt-in на sharing → $150/мес recurring (обновляется пока включено, требует минимум $5 spend за период)\n- **Зачем**: Grok 4.1 Fast — уникальный **2M context window**, никто больше такого не даёт\n- **В конфиг**: нужен `kind: xai` провайдер (OpenAI-compat endpoint `https://api.x.ai/v1`). **Пока не реализован** в neurogate.\n\n### Alibaba Qwen Singapore — 1M токенов × десятки моделей на 90 дней\n\n- **Регистрация**: https://accountclient.alibabacloud.com/intl (требует телефон и карту, +966 работает)\n- **Регион критичен**: Singapore. Endpoint `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. US/HK/EU версии free quota не дают.\n- **Квота**: 1M токенов **на каждую модель** на 90 дней → десятки моделей × 1M = десятки миллионов токенов суммарно. Флагманы: `qwen3-max`, `qwen-plus`, `qwen-flash`, `qwen3-coder-plus`, `qwen3.5-plus`.\n- **Privacy**: официально «will never use your data for model training», данные в Сингапуре.\n- **После 90 дней**: paid-only.\n- **В конфиг**: `kind: dashscope` — нативно поддерживается, см. секцию #15 выше для деталей.\n\n### DeepSeek direct — 5M signup credits + off-peak 50-75%\n\n- **Регистрация**: https://platform.deepseek.com (phone verify)\n- **Signup**: 5M токенов + 7-14 дней без rate limits\n- **Off-peak**: 16:30-00:30 UTC — **50% скидка на V3, 75% на R1**. Годится для batch-задач, не для realtime-чата.\n- **Privacy-блокер**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**.\n- **В конфиг**: `kind: deepseek` — нативно поддерживается, см. секцию #14 выше для деталей.\n\n### Anthropic Claude direct — $5 signup\n\n- **Регистрация**: https://console.anthropic.com (phone verify)\n- **Signup**: $5 кредитов на 30 дней после phone verify\n- **Зачем**: единственный способ добавить frontier Claude Sonnet/Opus в цепочку без Bedrock/Databricks\n- **Нюанс**: Anthropic API не OpenAI-compat — нужен отдельный `kind: anthropic`. В neurogate **пока не реализован**.\n\n### Claude CLI — через подписку Claude.ai без API-ключа\n\nЕсли у тебя уже оплачена подписка **Claude.ai Pro/Max** и установлен **Claude Code**, neurogate может ходить в Opus/Sonnet/Haiku через локальный `claude -p` — никакого Anthropic API-ключа не нужно, расход идёт из подписочной квоты.\n\n**Когда брать:**\n- Локальная разработка: подписка уже оплачена, хочется чтобы и пет-проекты на neurogate ходили через неё.\n- Не нужны streaming / tool calling / vision (v1 ограничение).\n- Готов мириться с ~0.4–1с холодным стартом `claude` процесса на каждый запрос.\n\n**Когда НЕ брать:**\n- Продакшен на VPS — `claude` бинаря обычно нет, провайдер авто-скипнется.\n- High-volume / latency-sensitive — каждый запрос форкает Node-процесс.\n- Нужны streaming / tools / vision — провайдер их не поддерживает (router автоматически отскочит на следующего в chain).\n\n**Setup:**\n\n1. Установи Claude Code — https://docs.claude.com/en/docs/claude-code\n2. Авторизуйся: `claude /login` (откроет браузер, залогинит через claude.ai). Токен сохранится в `~/.claude/` и переживёт ребут.\n3. Smoke test:\n ```bash\n claude -p \"say hi\" --output-format json | jq .result\n ```\n Должен вернуть строку с приветствием.\n4. (Опц.) если бинарь не в `PATH` — пропиши абсолютный путь в `NEUROGATE_CLAUDE_CLI_PATH=` в `.env`.\n\n**Использование в neurogate:**\n\n```bash\n# Прямой выбор модели:\ncurl -s http://127.0.0.1:8765/v1/chat/completions \\\n -H 'Content-Type: application/json' \\\n -d '{\"model\":\"claude_cli:opus\",\"messages\":[{\"role\":\"user\",\"content\":\"привет\"}]}'\n\n# Через chain `local` (opus → sonnet → haiku фоллбэк):\ncurl -s http://127.0.0.1:8765/v1/chat/completions \\\n -H 'Content-Type: application/json' \\\n -d '{\"model\":\"local\",\"messages\":[{\"role\":\"user\",\"content\":\"привет\"}]}'\n```\n\n**Ограничения v1 (намеренно):**\n- **Text-only**: streaming, tool calling, vision — не поддерживаются. Router пре-флайт перенаправит запросы с `stream:true` / `tools:[...]` / image-content на следующего провайдера в chain.\n- **`temperature` и `max_tokens` игнорируются** — `claude -p` их не принимает. Если тебе важна детерминированность через `temperature=0` — этот провайдер не подойдёт.\n- **Каждый запрос — отдельный subprocess**: ~0.4–1с cold-start (форк Node-процесса), плюс собственно генерация. Не для high-volume.\n- **Квота подписки не видна neurogate** — `rate_tracker` считает локальные RPM/RPD из YAML (по умолчанию 30/500 для Opus), реальный остаток квоты Claude.ai не виден до получения 429.\n- **Multi-turn flattening**: история сообщений сериализуется в `Human:/Assistant:` транскрипт и отправляется как единый prompt. На длинных диалогах качество может проседать сильнее чем при native messages API.\n\n**На сервере (VPS) ничего настраивать не нужно** — если `claude` не установлен, все три `claude_cli:*` записи и chain `local` пропустятся на старте с понятной записью в логе (`skipping claude_cli:opus : claude binary not found`).\n\n#### Подключить `claude_cli` на VPS (headless, без браузера на сервере)\n\nЕсли хочешь чтобы `model=local` работал и с прод-сервера тоже (квота подписки тратится одна — общая с ноутом):\n\n**1. Установить Claude Code:**\n\n```bash\n# нужен Node 18+ — на Ubuntu 24.04 обычно уже есть\nnpm install -g @anthropic-ai/claude-code\nclaude --version # → 2.x.x\n```\n\n**2. Сгенерировать long-lived OAuth token из подписки** (не интерактивный `/login`, а специальный headless-режим):\n\n```bash\nclaude setup-token\n```\n\nCLI откроет URL вида `https://claude.ai/oauth/authorize?…`. Скопируй URL из терминала → открой в браузере **на ноуте** → залогинься в claude.ai → подтверди → CLI на сервере напечатает токен:\n\n```\n✓ Long-lived authentication token created successfully!\nsk-ant-oat01-yA6U85mCJsuJN7...\n\nUse this token by setting: export CLAUDE_CODE_OAUTH_TOKEN=<token>\n```\n\n**Токен показывается ровно один раз** — скопируй сразу. Действует 1 год, можно ротировать тем же `claude setup-token` (старый автоматически инвалидируется).\n\n**3. Положить токен в `/opt/neurogate/.env`** (или куда у тебя `EnvironmentFile=` systemd-юнита):\n\n```bash\necho \"CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-…\" >> /opt/neurogate/.env\nchmod 600 /opt/neurogate/.env # на всякий\n```\n\n**4. Подвох под systemd:** если у тебя стоит `ProtectHome=yes` (как в шаблоне `neurogate.service` из docs), `/root/.claude/` будет скрыт от subprocess и `claude -p` молча вернёт пустой stdout. Neurogate поймает `claude_cli:* server error: invalid JSON: b''`. Лечение — переопределить `HOME` на путь внутри `ReadWritePaths`:\n\n```ini\n# В /etc/systemd/system/neurogate.service, в секции [Service]:\nEnvironment=HOME=/opt/neurogate\n```\n\nИ `mkdir -p /opt/neurogate/.claude && chmod 700 /opt/neurogate/.claude` перед рестартом — `claude` будет писать туда session-state.\n\n**5. Перезапустить:**\n\n```bash\nsystemctl daemon-reload\nsystemctl restart neurogate\njournalctl -u neurogate -n 30 --no-pager | grep -iE \"claude_cli|chain local\"\n# должно показать: chain local: claude_cli:opus → claude_cli:sonnet → claude_cli:haiku\n```\n\n**6. Smoke с сервера:**\n\n```bash\nTOKEN=$(grep ^NEUROGATE_API_TOKEN= /opt/neurogate/.env | cut -d= -f2)\ncurl -s -H \"Authorization: Bearer $TOKEN\" -H 'Content-Type: application/json' \\\n -d '{\"model\":\"local\",\"messages\":[{\"role\":\"user\",\"content\":\"reply with OK\"}]}' \\\n http://127.0.0.1:8765/v1/chat/completions | jq .choices[0].message.content\n# → \"OK\"\n```\n\n**Цена ошибки:** квота подписки одна на всё. Если на проде идёт боевой трафик через `model=local`, он будет конкурировать с твоим локальным Claude Code за тот же лимит (Pro ~$20/мес-эквивалент токенов, Max в 5× больше). Не подключай `local` в дефолтные chains (`chat`/`code`/`quality`) на проде — оставь явный opt-in, как сейчас.\n\n### OpenAI direct — единоразово $5 ради бесплатной модерации (text + image)\n\n**TL;DR — зачем подключать OpenAI вообще:** ради **бесплатной модерации**. Текстовая (`text-moderation-latest`) и multimodal text+image (`omni-moderation-latest`) у OpenAI **бесплатны навсегда** и качественнее всех альтернатив. Платные модели ($0.05–$10 per 1M токенов) — опционально, если иногда понадобится высокое качество в `paid` chain. **На бесплатные chat / embed / image-gen цепочки OpenAI подключать не нужно** — у Groq / Gemini / Z.ai лимиты щедрее и без депозита.\n\n**Регистрация:**\n\n- https://platform.openai.com (Google / Microsoft / email)\n- https://platform.openai.com/api-keys → *Create new secret key*\n- **ENV**: `OPENAI_API_KEY` (для бесплатной модерации) и опционально `OPENAI_API_KEY_PAID` (для paid-моделей; можно тот же ключ — разделение нужно лишь чтобы случайно не сжечь baseline-баланс)\n\n**Критично — почему без $5 ничего не работает:**\n\nНа Free tier (без привязанной карты) OpenAI режет **все** запросы через `429 Too Many Requests` с `type: invalid_request_error` — **включая бесплатную модерацию**. Это не rate-limit моды, это аккаунт-уровневая блокировка. В ответе нет ни одного `x-ratelimit-*` хедера — это диагностический признак, что блок именно account-level, а не лимит модели. Лечится только депозитом.\n\n**Депозит — единоразово $5:**\n\n1. https://platform.openai.com/settings/organization/billing/overview → *Add payment details*\n2. Введи **`5`** в *Initial credit purchase* (минимум).\n3. ⚠️ **Снять галочку *Automatically add credits when your balance runs low***. По умолчанию она включена. Если оставить — карта будет молча докидывать $5 каждый раз когда баланс упадёт. Это главная ловушка для тех, кто хотел «только бесплатно».\n4. Подтвердить (банк может попросить 3DS).\n5. За 1-5 минут Tier поднимается `Free` → `Tier 1`, лимиты на moderation вырастают с 3 RPM до ~500 RPM.\n\n**Где следить за лимитами и расходом:**\n\n- **Rate limits per model** (RPM/RPD/TPM): https://platform.openai.com/settings/organization/limits — таблица с текущим тиром и лимитами по каждой модели. Полезно проверить после оплаты, что Tier действительно поднялся до 1.\n- **Usage (расход токенов и запросов):** https://platform.openai.com/usage — графики по дням/моделям, что именно сжигало баланс. Здесь же видно, что moderation идёт нулевой строкой.\n- **Billing & balance:** https://platform.openai.com/settings/organization/billing/overview — текущий остаток депозита, история платежей, настройки auto-recharge.\n\n**Стратегия использования $5:**\n\n- **Основной use-case (бесплатно):** модерация — `omni-moderation-latest` (text+image, 13 категорий) и `text-moderation-latest` (legacy text-only, 7 категорий) **не списываются с баланса**. $5 просто лежат бессрочно.\n- **Опционально (платно):** редкие вызовы `paid` chain через `gpt-5-mini` для случаев когда бесплатные провайдеры упёрлись или не справляются с качеством. При умеренном трафике $5 хватает на месяцы.\n- **Не подключать:** chat / embed / image_gen цепочки — у бесплатных провайдеров (Groq / Gemini / Z.ai / Cohere / Voyage / Cloudflare / Pollinations) лимиты на порядки больше.\n\n**Бесплатно после депозита:**\n\n| Модель | Что делает | Цена |\n|---|---|---|\n| `omni-moderation-latest` | Text + image moderation, 13 категорий, native scores | $0 / $0 |\n| `text-moderation-latest` | Legacy text-only, 7 категорий | $0 / $0 |\n\nВ neurogate реализованы как `kind: openai_moderation` в [config.py:118](../src/neurogate/config.py#L118), провайдер [`OpenAIModerationProvider`](../src/neurogate/providers.py#L3205). Обе уже в дефолтных цепочках `moderation` и `moderation_image`.\n\n**Платные модели — опциональный subset для `paid` chain (используя `OPENAI_API_KEY_PAID`):**\n\n| Модель | Цена in/out (per 1M) | Когда нужна |\n|---|---|---|\n| `gpt-5-mini` | $0.25 / $2.00 | Основной paid-fallback. Уже добавлен во вторую позицию `paid` после Claude Opus. |\n| `gpt-5-nano` | $0.05 / $0.40 | Если нужен ультра-дешёвый paid-fallback. На простых запросах хватает. |\n| `gpt-4.1-mini` | $0.40 / $1.60 | **1M контекст** — для длинных документов / RAG. Подключать только если упираешься в context window других моделей. |\n| `whisper-1` | $0.006/мин | STT-fallback после Groq Whisper. Только если делаешь транскрипцию серьёзных объёмов. |\n\n**Не брать:** `o3` (есть `o4-mini` в 4× дешевле), `dall-e-3` (устарел против `gpt-image-1`), `gpt-4o` / `gpt-4o-mini` (`gpt-5-mini`/`nano` дешевле и не хуже), `text-embedding-3-small/large` (Voyage даёт 200M tok permanent free на каждую модель — OpenAI embeddings подключать смысла мало), `gpt-image-1` (Kandinsky / YandexART лучше на фотореализме, см. отдельную заметку).\n\n**В конфиге:** OpenAI-нативный endpoint `https://api.openai.com/v1` — `kind: openai` для chat (`gpt-5-mini` и др.), `kind: openai_moderation` для модерации. Конкретные провайдеры см. в [config.yaml](../config.yaml) (`openai:moderation`, `openai:text-moderation`, `openai:gpt-5-mini`).\n\n## После получения ключей\n\n1. Скопировать: `cp .env.example .env`\n2. Вписать ключи в `.env` (пустые строки neurogate просто пропустит — провайдеры без ключа исключаются из цепочки)\n3. Запустить: `uv run neurogate`\n4. Проверить, какие провайдеры реально доступны: `curl -s -H \"Authorization: Bearer $TOKEN\" http://127.0.0.1:8765/v1/models`\n\nЕсли провайдер упирается в 429 — neurogate автоматически перейдёт к следующему. Если все упали — вернётся HTTP 502 `upstream_exhausted` (на free-тирах в сумме с 1 ключа это ~20-25k сообщений/сутки, так что до потолка надо постараться).\n\n## Если что-то не работает — как сообщить о баге\n\nБез следующих данных мы не можем отделить баг шлюза от проблемы провайдера / твоего соединения / клиента, и фикс затягивается на дни. Скинь всё одним сообщением:\n\n### Чек-лист (минимум)\n\n- [ ] **Что произошло** — одна-две фразы. Что должно было быть, что получилось вместо.\n- [ ] **Скриншот или видео** — обязательно. На скрине должно быть видно: само сообщение об ошибке, время, и (если применимо) URL/endpoint.\n- [ ] **Текст ошибки целиком** — копи-паст, не пересказ. Если приложение режет текст — скрин консоли / network tab из DevTools.\n- [ ] **Когда произошло** — точное время с часовым поясом (например, `2026-05-09 14:32 МСК`). Это нужно чтобы найти запись в логах.\n- [ ] **Что делал до ошибки** — последовательность действий. Например: «открыл Cursor → задал вопрос про код → пошёл стрим, на 3-й секунде оборвался». Или: «отправил длинный документ через Continue → сразу 502». **Воспроизводится повторно или один раз?**\n- [ ] **Тип соединения**:\n - Wi-Fi (домашний роутер / офис / публичный)\n - мобильный интернет (4G/5G)\n - смешанно (когда переключался с одного на другое — отметь)\n- [ ] **Провайдер/оператор**:\n - для мобильного: МТС / Мегафон / Билайн / Tele2 / Yota / другой\n - для домашнего: Ростелеком / МТС / Билайн / ТТК / Дом.ру / другой\n - если за VPN — **обязательно укажи**, какой VPN и какая страна выхода\n- [ ] **Город** (грубо — Москва / СПб / регион / зарубежье). Не для слежки, а потому что некоторые провайдеры блокируют upstream-эндпоинты только в части регионов.\n- [ ] **Какой клиент** и его версия:\n - Cursor / Claude Code / Codex / OpenCode / Continue / Cline / curl / собственный скрипт / браузер\n - версия (например, `Cursor 1.4.2`)\n- [ ] **Какая модель / chain** была запрошена — посмотри в настройках клиента, поле `model:`. Например: `auto`, `chat`, `deepseek:reasoner`, `paid`.\n\n### Желательно (если можешь)\n\n- **Request ID** — если ошибка вернулась с шлюза (HTTP-ответ), там в headers должен быть `x-request-id`. Скинь его — найдём конкретный запрос в логах за миллисекунды.\n- **Скрин Network tab** браузера или вывод `curl -v` — видны заголовки и точный путь.\n- **Размер промпта** — короткий вопрос или длинный документ на 50K токенов? Длинный context часто выявляет баги, которых нет на коротком.\n- **Stream или non-stream** — обычно стрим по умолчанию, но некоторые клиенты выключают.\n\n### Шаблон сообщения\n\nСкопируй и заполни:\n\n```\nЧто произошло:\nСкриншот/видео: (приложить файл)\nТекст ошибки:\n <вставить текст>\nКогда: 2026-05-09 HH:MM МСК\nЧто делал до:\nВоспроизводится: да / нет / иногда\nСоединение: Wi-Fi / мобильный\nОператор:\nVPN: нет / да (страна: ...)\nГород:\nКлиент: ... версия ...\nМодель/chain:\nRequest ID:\n```\n\n### Почему мы спрашиваем про оператора\n\nneurogate за собой держит 15+ upstream-провайдеров (Groq, Cerebras, SambaNova, Gemini, OpenRouter, DeepSeek, …). Часть из них **блокируется или режется на уровне отдельных российских операторов** — эта блокировка не от шлюза, а от твоего ISP. Признаки: connection reset / timeout / SSL handshake fail на конкретный домен. На разных операторах живут разные подмножества upstream'ов:\n\n- МТС иногда режет HuggingFace и часть Cloudflare-эндпоинтов\n- Мегафон блокирует часть Google IP-блоков → Gemini нестабильна\n- Ростелеком блокирует часть международного трафика по DPI\n- Из мобильного интернета бывает странный SNI-фильтр\n\nБез информации про оператора мы будем час крутить логи в поисках бага в коде, которого нет.\n"}, "1e8dfeb9453ebc4066a74d94746a0349fe581ff0": {"t": 1785765652.8854892, "n": 39784, "h": "70901a4625a29f2e", "c": "# Как получить API-ключи провайдеров\n\nПошаговая инструкция для всех провайдеров из [config.yaml.example](../config.yaml.example) — где зарегистрироваться, где взять ключ, какая переменная в [.env.example](../.env.example), важные нюансы.\n\n**Минимум для старта**: достаточно 1-2 ключей — neurogate пропустит позиции, у которых ключ пустой, и пойдёт дальше по цепочке. Стартап-репорт на консоли подскажет, какие именно env-vars не заполнены и какие провайдеры это включит. Начать проще всего с **Groq** (самый быстрый onboarding) + **Gemini** (самая жирная квота на 1 ключ).\n\n## Free quota at a glance\n\nСводная таблица. Две колонки маркеров:\n\n**Cap (квота):**\n- 🟢 **effectively unlimited** — нет суточного/месячного потолка по запросам, ограничение только на RPM (или concurrency). Можно жечь хоть 24/7.\n- 🟡 **RPD-capped** — есть суточный потолок (счётчик ресетится 00:00 UTC, обычно).\n- 🔵 **monthly / token quota** — потолок по токенам или вызовам в месяц / в год.\n- 🟣 **anonymous / no key** — без ключа.\n\n**Privacy (что провайдер делает с твоими промптами):**\n- 🔒 **private** — провайдер заявляет «не обучаем на твоих данных» (free tier).\n- ⚠️ **trains on free tier** — на free-тире промпты/ответы могут уходить в обучение. Не клади чувствительное.\n- 🟣 **public-by-design** — community-инфраструктура, твои промпты видны другим.\n\nЦифры на free-тирах часто меняются — `/v1/models` и dashboard покажут реальную картину. Privacy-метки взяты из публично заявленных политик; они не аудит, а ориентир.\n\n| Cap | Privacy | Провайдер | ENV-переменная | Лимит | Phone | Card | Особенность |\n|---|---|---|---|---|---|---|---|\n| 🟢 | 🔒 | **NVIDIA NIM** | `NVIDIA_API_KEY` | 40 RPM, без RPD | нет | нет | TTFB медленный — в `unlimited`/фоллбэк. |\n| 🟢 | 🔒 | **Z.ai** | `ZAI_API_KEY` | concurrency-only | нет | нет | GLM-4.5-Flash permanent free. China upstream — оф. заявляет «no training», но юрисдикция КНР. |\n| 🟢 | 🔒 | **Cerebras** | `CEREBRAS_API_KEY` | 5–30 RPM, без RPD | да | нет | Узкий выбор моделей, но потолка нет. Enterprise-friendly TOS. |\n| 🟢 | ⚠️ | **Mistral** | `MISTRAL_API_KEY` | ~4 RPM, без RPD | да | нет | Experiment plan. На free тренируется на твоих промптах. Paid plan — opt-out. |\n| 🟡 | 🔒 | **SambaNova** | `SAMBANOVA_API_KEY` | 20 RPD **на модель** | нет | нет | 4 модели = 80 RPD на ключ. Enterprise-friendly. |\n| 🟡 | ⚠️ | **Groq** | `GROQ_API_KEY` | 30 RPM, 1k–14.4k RPD | нет | нет | Самый быстрый onboarding. Privacy policy позволяет использовать промпты для improvements. |\n| 🟡 | ⚠️ | **Gemini (AI Studio)** | `GEMINI_API_KEY` | 10 RPM, 250-1500 RPD | нет | нет | Per-project: 2-3 GCP-проекта = ×N квота. **На free tier Google использует промпты для улучшения моделей.** Paid Vertex — opt-out. |\n| 🟡 | 🔒 | **Cloudflare Workers AI** | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` | 300 RPD (Llama 70B) | нет | нет | Edge inference, image gen бесплатно. CF не тренирует. |\n| 🟡 | 🔒 | **GitHub Models** | `GITHUB_MODELS_TOKEN` | 50–150 RPD | нет | нет | gpt-5-mini в free tier. Microsoft не тренирует на промптах GitHub Models. |\n| 🟡 | ⚠️ | **OpenRouter (free)** | `OPENROUTER_API_KEY` | 20 RPM, 50 RPD (1000 с $10) | нет | нет\\* | Каждая `:free`-модель имеет свою policy — у некоторых тренировка включена. Читай каточку модели. |\n| 🟡 | ⚠️ | **FreeTheAi** | `FREETHEAI_API_KEY` | 10 RPM, 1 concurrent | нет (Discord) | нет | **Требует daily Discord `/checkin`**. Privacy не задекларирована — считай что промпты видят. |\n| 🟡 | 🔒 | **OVHcloud** | — (anon) | 2 RPM на IP | нет | нет | EU-инфра, без ключа, не тренирует. |\n| 🔵 | ⚠️ | **GigaChat (Sber)** | `GIGACHAT_AUTH_KEY` | Freemium quota / год | да (РФ) | нет | Чат слабоват, но **есть бесплатная Kandinsky image gen**. Free tier — обучаются. См. §11. |\n| 🔵 | ⚠️ | **HuggingFace** | `HF_TOKEN` | ~$0.10/мес общий кредит | нет | нет | Кредит на paid sub-providers. Каждый sub-provider — своя privacy policy. |\n| 🔵 | ⚠️ | **DeepSeek** | `DEEPSEEK_API_KEY` | 5M tok signup credits, дальше PAYG | да | нет | Off-peak 50–75% скидка. **CN-юрисдикция, тренируются на промптах.** |\n| 🔵 | ⚠️ | **Alibaba DashScope Intl** | `DASHSCOPE_API_KEY` | 1M tok / model × 90 дней | да | да | Singapore region, 1M context на флагманах. CN-юрисдикция. |\n| 🔵 | 🔒 | **Cohere** | `COHERE_API_KEY` | 20 RPM, 1000 calls/мес | нет | нет | **Non-commercial only** на free tier (ToS). Не тренируются. |\n| 🟣 | 🟣 | **LibreTranslate** | — (anon) | varies | нет | нет | Public mirror. Логи могут вестись на стороне зеркала. |\n| 🟣 | 🟣 | **MyMemory** | `MYMEMORY_CONTACT_EMAIL` (опц) | 5k–50k chars/IP | нет | нет | Community translation memory — твои тексты могут пополнять корпус. |\n| 🟣 | 🔒 | **Edge TTS** | — (anon) | без лимита | нет | нет | MS Edge — голос синтезируется serverside, текст не сохраняется. |\n| 🟣 | 🟣 | **AIhorde** | — (anon) | community queue | нет | нет | Распределённый inference — твой prompt видит worker, который на нём генерирует картинку. |\n\n\\* OpenRouter не требует карту для базового free tier, но $10 однократный депозит поднимает лимиты в 20 раз.\n\n**TL;DR (квоты).** Если нужен **24/7-бэкбон** — собирай цепочку из 🟢 (NVIDIA + Z.ai + Cerebras + Mistral): они не упираются в суточный потолок. Если нужен **широкий пул моделей** — добавляй 🟡 (Groq, Gemini, OpenRouter, GitHub) — они дают разнообразие, но ресетятся каждые 24ч. 🔵 — на конкретные ниши (Cohere для не-коммерческого RU, DeepSeek для signup-кредитов, GigaChat для Kandinsky).\n\n**TL;DR (privacy).** Для **чувствительного трафика** (внутренние документы, персональные данные клиентов) бери только 🔒: NVIDIA, Cerebras, Cloudflare, GitHub Models, Cohere, SambaNova. Z.ai заявляет no-training, но юрисдикция КНР — для коммерческой тайны не годится. Всё что 🟣 — public-by-design, такие провайдеры можно использовать только для безличных текстов (переводы общего назначения, генерация фоновых картинок). Если в чейне смешаны провайдеры — фоллбэк может уйти на ⚠️-провайдера; для строгого режима оставь только 🔒-провайдеров либо подними отдельный `chains: private:` под чувствительный трафик.\n\n### Quick suggestion: какие 2-3 ключа добавить первыми\n\n- **Самый быстрый старт:** Groq (без верификаций) → мгновенный отклик и приличная квота.\n- **Долгий контекст / vision:** Gemini.\n- **Бэкбон без RPD-капа:** Cerebras (одно подтверждение телефона) или NVIDIA.\n- **Русский:** Yandex Alice (`yandex_foundation` kind) — на наш опыт лучше GigaChat для RU.\n- **Картинки бесплатно:** Cloudflare (FLUX/SDXL без RPD на image gen) или GigaChat (Kandinsky — фотореализм держит лучше FLUX).\n\n## Провайдеры\n\n### 1. Gemini (Google)\n\n- **Регистрация**: любой Google-аккаунт\n- **Получить ключ**: https://aistudio.google.com/apikey → *Create API key*\n- **ENV**: `GEMINI_API_KEY`\n- **Нюанс**: квота считается **per-project**, не per-key. Если завести 2-3 GCP-проекта на том же Google-аккаунте и сгенерить по ключу в каждом, получишь 2-3× квоту легально (TOS это разрешает — дубликаты запрещены только на уровне аккаунтов). Дополнительные ключи можно прописать как `GEMINI_API_KEY_2`, `GEMINI_API_KEY_3` и завести дубликаты провайдеров в `config.yaml` с разными `api_key_env`.\n\n### 2. Groq\n\n- **Регистрация**: https://console.groq.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Create API Key*\n- **ENV**: `GROQ_API_KEY`\n- **Нюанс**: самый быстрый провайдер в цепочке (300-1000+ токенов/сек). Free tier даёт 1000 RPD на `llama-3.3-70b-versatile` и 14400 RPD на `llama-3.1-8b-instant`. Дубликаты аккаунтов Groq ловит и банит оба — **не регистрируй второй аккаунт** с того же IP/телефона/карты.\n\n### 3. Cerebras\n\n- **Регистрация**: https://cloud.cerebras.ai (требует подтверждение телефона)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `CEREBRAS_API_KEY`\n- **Нюанс**: нет суточного лимита, но free tier сейчас узкий — реально работают только `qwen-3-235b-a22b-instruct-2507` (5 RPM) и `llama3.1-8b` (30 RPM). Более крупные модели (llama-3.3-70b, gpt-oss-120b) депрекейтнуты или paid-only.\n\n### 4. SambaNova\n\n- **Регистрация**: https://cloud.sambanova.ai (Google / email)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `SAMBANOVA_API_KEY`\n- **Нюанс**: 20 RPD **на каждую модель**, а не на аккаунт — 4 SambaNova-позиции в цепочке дают суммарно 80 RPD на один ключ. Лимит читается из заголовка `x-ratelimit-limit-requests-day` в ответе.\n\n### 5. NVIDIA NIM\n\n- **Регистрация**: https://build.nvidia.com (email, developer-программа)\n- **Получить ключ**: профиль справа вверху → *Get API Key* → выдают ключ вида `nvapi-...`\n- **ENV**: `NVIDIA_API_KEY`\n- **Нюанс**: формально **только для research/dev/test** — production TOS требует AI Enterprise license (~$4500/GPU/год). Для личного бота не критично. Нет суточного лимита, только RPM (40 на большинстве моделей).\n\n### 6. Z.ai (GLM)\n\n- **Регистрация**: https://z.ai (international) или https://open.bigmodel.cn (Китай — для аккаунтов из РФ/СНГ)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `ZAI_API_KEY`\n- **Нюанс**: `glm-4.5-flash` — **permanent free**, без RPD-лимита. В конфиге стоит `extra_body: { thinking: { type: disabled } }` — это принудительно отключает reasoning-режим (по умолчанию модель тратит токены на chain-of-thought, что режет скорость). Z.ai официально заявляет «no training on API data» — ок для чувствительного трафика.\n\n### 7. OpenRouter\n\n- **Регистрация**: https://openrouter.ai (Google / GitHub / MetaMask)\n- **Получить ключ**: https://openrouter.ai/keys → *Create Key*\n- **ENV**: `OPENROUTER_API_KEY`\n- **Нюанс**: `:free` модели делят глобальный пул 50 RPD на всех пользователей планеты — часто упирается в лимит к вечеру UTC. **Однократный депозит $10** поднимает RPD → 1000 на все `:free` модели (сами $10 не сгорают, лежат на балансе). Это единственное действие с 20× ROI на лимиты — см. «Платные расширения».\n\n### 8. Cloudflare Workers AI\n\n- **Регистрация**: https://dash.cloudflare.com (email)\n- **Получить ключ**: *My Profile* (правый верх) → *API Tokens* → *Create Token* → шаблон *Workers AI* (или custom: permission `Account → Workers AI → Read` + `Edit`)\n- **Получить Account ID**: на главной странице dashboard в правом сайдбаре — строка *Account ID*\n- **ENV**: `CLOUDFLARE_API_KEY` (токен) + `CLOUDFLARE_ACCOUNT_ID`\n- **Нюанс**: единственный провайдер, которому нужны **две** переменные. Account ID нельзя передать как env — Cloudflare вшивает его в URL запроса. 300 RPD на Llama 70B fp8-fast.\n\n### 9. GitHub Models\n\n- **Регистрация**: любой GitHub-аккаунт\n- **Получить токен**: https://github.com/settings/personal-access-tokens → *Generate new token (fine-grained)* → Account permissions → **Models: Read-only**\n- Классический PAT (`settings/tokens`) тоже работает, но fine-grained безопаснее — скоуп только на Models, не трогает репы.\n- **ENV**: `GITHUB_MODELS_TOKEN`\n- **Нюанс**: endpoint `https://models.github.ai/inference`, жёсткий потолок 8K токенов на запрос (input+output). Лимиты 50-150 RPD по моделям, считаются на токен.\n\n### 10. Mistral La Plateforme\n\n- **Регистрация**: https://console.mistral.ai (email + SMS-верификация)\n- **Получить ключ**: *API Keys*\n- **План**: выбрать **Experiment** (бесплатный) — даёт доступ к `mistral-large-latest` и остальным флагманам\n- **ENV**: `MISTRAL_API_KEY`\n- **Нюанс**: **обязательно зайти** в *Admin* → *Privacy* и **выключить опцию использования данных для обучения** — по умолчанию она включена. Без этого твои запросы уходят на training. Лимит ~4 RPM (заголовок `x-ratelimit-limit-req-minute`), не 60 как в старых доках.\n\n### 11. HuggingFace Inference Providers Router\n\n- **Регистрация**: любой HuggingFace-аккаунт https://huggingface.co\n- **Получить токен**: *Settings* → *Access Tokens* → *Create new token* → тип **Read**\n- **ENV**: `HF_TOKEN`\n- **Нюанс**: HF проксирует запросы к paid sub-providers (Novita, Cerebras, Together, …) через единый OpenAI-совместимый endpoint. Free tier даёт **~$0.10/мес общего кредита** на все sub-providers — этого хватает на эксперименты, не на постоянный трафик. **PRO-подписка ($9/мес)** даёт $2 кредита/мес. Модель указывается как `<repo>:<sub-provider>`, например `meta-llama/Llama-3.3-70B-Instruct:novita`.\n\n### 12. GigaChat (SberDevices)\n\n- **Регистрация**: https://developers.sber.ru/studio (требует подтверждённый аккаунт Сбера, телефон РФ)\n- **Получить ключ**: *Личное пространство* → *Мой GigaChat API* → *Получить новый ключ* → выдают `Authorization key` (это уже base64 от `client_id:client_secret`, готовый для `Basic`-авторизации)\n- **ENV**: `GIGACHAT_AUTH_KEY` (значение строки *Authorization key* как есть)\n- **Scope**: `GIGACHAT_API_PERS` — **Freemium** для физлиц с годовой квотой токенов (точные цифры Сбер периодически меняет — смотри актуальное на странице тарифа). По нашему опыту, на личное использование хватает с запасом.\n- **Чат vs картинки**: текстовые модели (GigaChat 2 / 2-Pro / 2-Max) на наш опыт **слабее даже отдельных Qwen / GLM** на русском, и заметно отстают от Yandex Alice. Но **бесплатная Kandinsky image gen** в этом же ключе — единственный способ получить русскоязычно-обученную text-to-image модель «из коробки», и она хорошо держит фотореализм когда в промпте есть «digital painting» / «oil painting» (где FLUX даёт «пластик»). Стоит держать в `image_gen` chain ради этого.\n- **Нюанс 1**: GigaChat отдаёт сертификат, подписанный *Russian Trusted Root CA* — стандартные системные truststore (на macOS/Linux вне РФ) его не знают. В конфиге для `kind: gigachat` стоит `verify_ssl: false`. Для прода — добавить Russian Trusted Sub CA в системный truststore.\n- **Нюанс 2**: авторизация двухступенчатая — провайдер обменивает `Authorization key` на короткоживущий OAuth access-token и кэширует его. Этот flow реализован внутри `kind: gigachat`, ничего вручную делать не нужно.\n- **Биллинг и расход**: https://developers.sber.ru/studio (раздел *Проекты* → *Лицевой счёт*).\n\n### 13. FreeTheAi\n\n- **Регистрация**: только через Discord. Зайти на сервер → https://discord.gg/secrets → команда `/signup` в канале #api-keys (https://discord.com/channels/1461555807731585158/1473159205048553705) → бот пришлёт ключ вида `sta_…` в DM. Если потерял — `/resetkey`.\n- **ENV**: `FREETHEAI_API_KEY`\n- **Лимиты**: 10 RPM + **1 concurrent** на ключ — последовательные вызовы, никакого parallel.\n- **Каталог**: ~16 252 алиасов. Префиксы: `cat/*` (gpt-5/claude/gemini frontier через прокси), `bbg/*` (DeepSeek/GLM/Kimi/MiniMax reasoning), `bbl/*` (Gemini/GPT non-reasoning), `or/*` (OpenRouter passthrough), `vhr/*` (image-gen scrap из Vheer), `img/gpt-image-2` (image gen+edit b64), `fth/*` (16k случайных HF моделей — почти всегда мусор). Не все алиасы реально работают — `glm/glm-5.1` (#1 в leaderboard) и `cat/gemini-3-1-pro` возвращают 400/timeout. Перед использованием — пробовать.\n- **⚠️ Главный нюанс — DAILY /checkin**: ключ блокируется **каждые 24 часа**. Чтобы разлочить — заходишь в Discord, в тот же канал #api-keys пишешь `/checkin`, бот возвращает «ключ активен на 24h». Без этого все запросы получают `HTTP 403 daily_checkin_required`.\n- **Автоматизировать /checkin НЕЛЬЗЯ**:\n 1. Discord ToS запрещает self-bot'ы (использование своего user-токена для скриптов) — ловят и банят аккаунт.\n 2. Обычные боты Discord не могут вызывать slash-команды других ботов (by design платформы).\n 3. Browser-automation поверх web-Discord — та же категория self-bot, ban guarantied.\n 4. FreeTheAi специально поставили /checkin как защиту от abuse — обходить = бан и от них тоже.\n- **Когда использовать**:\n - Ad-hoc-запросы для тестов (`model: \"freetheai:cat/gpt-5\"`) — 24h cooldown терпим, если не забыл сделать /checkin утром.\n - Не для продовых chains (без daily-checkin сервис ляжет).\n- **Bait-and-switch**: проверка identity показала, что `cat/claude-4-6-sonnet` отвечает «built by Tiny» — это НЕ Claude. `cat/gpt-5` идентифицируется как OpenAI, но без гарантий. `bbg/deepseek-v4-pro` выдаёт gibberish. Перед интеграцией каждой модели в логику — прогнать identity-test.\n- **Image-gen**: `vhr/*` модели возвращают URL'ы на `access.vheer.com` — это прокси на бесплатный Vheer.com сервис, файлы хранятся у них. `img/gpt-image-2` отдаёт b64 (~650KB на запрос) — единственная модель, поддерживающая edits.\n\n### 14. DeepSeek (direct API)\n\n**Пошагово (получить ключ):**\n\n1. Открой https://platform.deepseek.com → *Sign Up* (Google или email)\n2. Phone verify — российские номера принимает (МТС/Мегафон/Билайн/Tele2). Если по какой-то причине не принимает твой номер — попробуй через Google-аккаунт.\n3. После входа: левое меню → *API Keys* → *Create new API key* → дать любое имя → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается **один раз** — потом только regenerate.\n4. В `.env` локально и на проде:\n ```\n DEEPSEEK_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **5M токенов signup credits** + 7-14 дней без RPM-лимитов. Этого хватит на много экспериментов.\n- Модели: `deepseek-chat` (V3.2) и `deepseek-reasoner` (R1/R2).\n\n**Когда signup credits закончатся (опционально):**\n\n- $2 топ-ап ≈ 170 ₽ → месяцы PAYG-работы (`deepseek-chat` $0.28/$0.42 за 1M, `deepseek-reasoner` сопоставимо).\n- Off-peak 16:30–00:30 UTC — скидка 50% на V3, 75% на R1.\n- Prefix caching: cache hit в 4–10× дешевле miss. Структурируй промпты так, чтобы стабильный префикс (system + RAG) шёл первым, юзер-ввод — последним.\n- ⚠️ **Не включай auto-recharge** — карта будет молча докидывать каждый раз когда баланс падает.\n- ⚠️ Российские карты Visa/MC топ-ап **не примет**. Варианты: карта дружественной страны (Казахстан/Армения/Грузия), Wise/Revolut, виртуалка от иностранного fintech.\n\n**Подводные камни:**\n\n- **Privacy**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**. Если через шлюз идут чувствительные данные клиентов — либо удали DeepSeek из chain, либо ставь его последним позади cohere/openrouter/sambanova.\n- **Из России без VPN**: иногда нестабильные 5xx-ответы. Держи fallback в той же chain ниже — он сработает автоматически.\n\n**kind**: `deepseek`. Provider в config.yaml — простая запись с `model: deepseek-chat` или `model: deepseek-reasoner`. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 15. Alibaba DashScope International (Qwen)\n\n**⚠️ Самый муторный из четырёх. Делай утром, на это уйдёт 20-30 минут.**\n\n**Пошагово (получить ключ):**\n\n1. Открой https://accountclient.alibabacloud.com/intl → *Sign Up*\n2. **Регион — обязательно Singapore.** US/HK/EU/China версии free quota НЕ дают. Если на этапе onboarding спрашивает регион — выбирай Singapore. Если уже зарегистрировался в другом регионе — придётся завести отдельный аккаунт.\n3. Phone verify (российские номера принимает).\n4. **Карта обязательна** — для Real-name Verification. С карты ничего не списывается, но без привязки free quota не активируется.\n - ⚠️ Российские карты Visa/MC **не пройдут**.\n - Варианты:\n - Карта дружественной страны (Казахстан / Армения / Грузия)\n - Wise / Revolut если есть\n - Виртуальная карта от иностранного fintech (Pyypl, Genome, etc.)\n5. После Real-name Verification → открыть https://bailian.console.alibabacloud.com (Model Studio, регион Singapore)\n6. Левое меню → *API-KEY* → *Create* → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается полностью один раз.\n7. В `.env` локально и на проде:\n ```\n DASHSCOPE_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **1M токенов на каждую модель** × **90 дней** с момента активации. Десятки моделей в каталоге → десятки миллионов токенов суммарно.\n- Флагманы: `qwen3.6-plus` (топ-3 на OpenRouter trafficу, 1M context, всегда-вкл CoT), `qwen3.6-max-preview`, `qwen3-coder-480b-a35b-instruct`, `qwen3-next-80b-a3b-instruct/thinking`, `qwen3-vl-plus`.\n\n**После 90 дней**: paid-only. Поставь напоминание `/schedule` за неделю до истечения — посмотрим использование и решим продлять или уйти на DashScope-paid.\n\n**Подводные камни:**\n\n- **Регион Singapore ОБЯЗАТЕЛЬНО**. Endpoint в config.py уже забит: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. Если у тебя аккаунт в другом регионе — ключ будет работать, но free quota = 0.\n- **Privacy**: Alibaba явно заявляет «will never use your data for model training», данные в Сингапуре → **можно использовать с PII** в отличие от китайского endpoint DeepSeek.\n- **Real-name Verification может зависнуть на сутки** — в первый раз. Если статус «pending» больше 24ч — открыть тикет в support.\n\n**kind**: `dashscope`. Provider в config.yaml — простая запись с `model: qwen3.6-plus` или другой моделью. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 16. Cohere (Command-A / c4ai-aya — для русского)\n\n- **Регистрация**: https://dashboard.cohere.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Generate Trial Key*\n- **ENV**: `COHERE_API_KEY`\n- **Free tier**: 20 RPM на модель, 1000 calls/месяц (≈33 RPD safe-floor).\n- **Модели**: `c4ai-aya-expanse-32b/8b` — multilingual, **сильный русский**. `c4ai-aya-vision-32b/8b` — vision. `command-a-03-2025` — флагман общего назначения. `command-a-reasoning-08-2025` — reasoning. `command-a-translate-08-2025` — translation.\n- **ToS**: free tier — **non-commercial only**. Для open-source / личных проектов ок. Если кто-то форкнет коммерчески — нарушение. Помечай в README.\n- **Особенность реализации**: Cohere v2 /chat — собственный response shape (`{message: {content: [{type:'text', text:...}]}}`), не OpenAI-compat. Streaming эмулируется одним SSE chunk'ом из полного ответа (Cohere v2 SSE имеет свой формат, дешевле fake-stream чем переводить).\n- **kind**: `cohere_chat` (для chat) или `cohere` (для translate-only). Эмбеддинги отдельно — `cohere_embed`.\n\n### 17. OVHcloud AI Endpoints (anonymous, без ключа)\n\n- **Регистрация**: НЕ ТРЕБУЕТСЯ. Endpoint анонимный.\n- **ENV**: НЕТ. В config.yaml запись `kind: ovhcloud` без `api_key_env`.\n- **Endpoint**: `https://oai.endpoints.kepler.ai.cloud.ovh.net/v1` — OpenAI-совместимый.\n- **Лимит**: 2 RPM **на IP** на модель. Без ключа — прозрачный rate-limit, при превышении 429.\n- **Каталог**: 40+ open-моделей, EU-host (Франция/Германия). Llama 3.x, Mistral, Qwen, Mixtral, gpt-oss-120b, и т.д.\n- **Когда использовать**: исключительно как **deep fallback / last-resort** в конце chain — «лучше отдать что-то, чем 503». В основной chain ставить нет смысла из-за 2 RPM на IP.\n- **Реализация**: `OpenAICompatProvider` пропускает `Authorization` header при пустом `api_key` (см. providers.py — изменение из этого PR).\n- **kind**: `ovhcloud`.\n\n## Платные расширения (опционально)\n\nНиже — одноразовые или recurring платные действия с непропорционально большим профитом на лимиты.\n\n### OpenRouter — $10 депозит → 20× квоты\n\n**Что делает**: однократный пополнение на $10 поднимает 50 RPD → **1000 RPD** на все `:free` модели (DeepSeek R1/V3.2, Llama 4 Maverick/Scout, Qwen3 235B, GLM-5 `:free`, Kimi K2 `:free`, MiniMax M2 `:free`, Qwen3-Coder 480B `:free`).\n\n**Как**: *Settings* → *Credits* → пополнить любую сумму ≥ $10. Сами $10 остаются на балансе и тратятся только если ты явно вызовешь платную модель. Для `:free` — это просто unlock лимита.\n\n**После депозита**: в `config.yaml` обновить `rpd: 50` → `rpd: 1000` на всех позициях с `kind: openrouter`.\n\n### xAI Grok — $25 signup + $150/мес recurring\n\n- **Регистрация**: https://console.x.ai (phone verify)\n- **Signup**: $25 кредитов на 30 дней\n- **Data-sharing program**: opt-in на sharing → $150/мес recurring (обновляется пока включено, требует минимум $5 spend за период)\n- **Зачем**: Grok 4.1 Fast — уникальный **2M context window**, никто больше такого не даёт\n- **В конфиг**: нужен `kind: xai` провайдер (OpenAI-compat endpoint `https://api.x.ai/v1`). **Пока не реализован** в neurogate.\n\n### Alibaba Qwen Singapore — 1M токенов × десятки моделей на 90 дней\n\n- **Регистрация**: https://accountclient.alibabacloud.com/intl (требует телефон и карту, +966 работает)\n- **Регион критичен**: Singapore. Endpoint `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. US/HK/EU версии free quota не дают.\n- **Квота**: 1M токенов **на каждую модель** на 90 дней → десятки моделей × 1M = десятки миллионов токенов суммарно. Флагманы: `qwen3-max`, `qwen-plus`, `qwen-flash`, `qwen3-coder-plus`, `qwen3.5-plus`.\n- **Privacy**: официально «will never use your data for model training», данные в Сингапуре.\n- **После 90 дней**: paid-only.\n- **В конфиг**: `kind: dashscope` — нативно поддерживается, см. секцию #15 выше для деталей.\n\n### DeepSeek direct — 5M signup credits + off-peak 50-75%\n\n- **Регистрация**: https://platform.deepseek.com (phone verify)\n- **Signup**: 5M токенов + 7-14 дней без rate limits\n- **Off-peak**: 16:30-00:30 UTC — **50% скидка на V3, 75% на R1**. Годится для batch-задач, не для realtime-чата.\n- **Privacy-блокер**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**.\n- **В конфиг**: `kind: deepseek` — нативно поддерживается, см. секцию #14 выше для деталей.\n\n### Anthropic Claude direct — $5 signup\n\n- **Регистрация**: https://console.anthropic.com (phone verify)\n- **Signup**: $5 кредитов на 30 дней после phone verify\n- **Зачем**: единственный способ добавить frontier Claude Sonnet/Opus в цепочку без Bedrock/Databricks\n- **Нюанс**: Anthropic API не OpenAI-compat — нужен отдельный `kind: anthropic`. В neurogate **пока не реализован**.\n\n### Claude CLI — через подписку Claude.ai без API-ключа\n\nЕсли у тебя уже оплачена подписка **Claude.ai Pro/Max** и установлен **Claude Code**, neurogate может ходить в Opus/Sonnet/Haiku через локальный `claude -p` — никакого Anthropic API-ключа не нужно, расход идёт из подписочной квоты.\n\n**Когда брать:**\n- Локальная разработка: подписка уже оплачена, хочется чтобы и пет-проекты на neurogate ходили через неё.\n- Не нужны streaming / tool calling / vision (v1 ограничение).\n- Готов мириться с ~0.4–1с холодным стартом `claude` процесса на каждый запрос.\n\n**Когда НЕ брать:**\n- Продакшен на VPS — `claude` бинаря обычно нет, провайдер авто-скипнется.\n- High-volume / latency-sensitive — каждый запрос форкает Node-процесс.\n- Нужны streaming / tools / vision — провайдер их не поддерживает (router автоматически отскочит на следующего в chain).\n\n**Setup:**\n\n1. Установи Claude Code — https://docs.claude.com/en/docs/claude-code\n2. Авторизуйся: `claude /login` (откроет браузер, залогинит через claude.ai). Токен сохранится в `~/.claude/` и переживёт ребут.\n3. Smoke test:\n ```bash\n claude -p \"say hi\" --output-format json | jq .result\n ```\n Должен вернуть строку с приветствием.\n4. (Опц.) если бинарь не в `PATH` — пропиши абсолютный путь в `NEUROGATE_CLAUDE_CLI_PATH=` в `.env`.\n\n**Использование в neurogate:**\n\n```bash\n# Прямой выбор модели:\ncurl -s http://127.0.0.1:8765/v1/chat/completions \\\n -H 'Content-Type: application/json' \\\n -d '{\"model\":\"claude_cli:opus\",\"messages\":[{\"role\":\"user\",\"content\":\"привет\"}]}'\n\n# Через chain `local` (opus → sonnet → haiku фоллбэк):\ncurl -s http://127.0.0.1:8765/v1/chat/completions \\\n -H 'Content-Type: application/json' \\\n -d '{\"model\":\"local\",\"messages\":[{\"role\":\"user\",\"content\":\"привет\"}]}'\n```\n\n**Ограничения v1 (намеренно):**\n- **Text-only**: streaming, tool calling, vision — не поддерживаются. Router пре-флайт перенаправит запросы с `stream:true` / `tools:[...]` / image-content на следующего провайдера в chain.\n- **`temperature` и `max_tokens` игнорируются** — `claude -p` их не принимает. Если тебе важна детерминированность через `temperature=0` — этот провайдер не подойдёт.\n- **Каждый запрос — отдельный subprocess**: ~0.4–1с cold-start (форк Node-процесса), плюс собственно генерация. Не для high-volume.\n- **Квота подписки не видна neurogate** — `rate_tracker` считает локальные RPM/RPD из YAML (по умолчанию 30/500 для Opus), реальный остаток квоты Claude.ai не виден до получения 429.\n- **Multi-turn flattening**: история сообщений сериализуется в `Human:/Assistant:` транскрипт и отправляется как единый prompt. На длинных диалогах качество может проседать сильнее чем при native messages API.\n\n**На сервере (VPS) ничего настраивать не нужно** — если `claude` не установлен, все три `claude_cli:*` записи и chain `local` пропустятся на старте с понятной записью в логе (`skipping claude_cli:opus : claude binary not found`).\n\n#### Подключить `claude_cli` на VPS (headless, без браузера на сервере)\n\nЕсли хочешь чтобы `model=local` работал и с прод-сервера тоже (квота подписки тратится одна — общая с ноутом):\n\n**1. Установить Claude Code:**\n\n```bash\n# нужен Node 18+ — на Ubuntu 24.04 обычно уже есть\nnpm install -g @anthropic-ai/claude-code\nclaude --version # → 2.x.x\n```\n\n**2. Сгенерировать long-lived OAuth token из подписки** (не интерактивный `/login`, а специальный headless-режим):\n\n```bash\nclaude setup-token\n```\n\nCLI откроет URL вида `https://claude.ai/oauth/authorize?…`. Скопируй URL из терминала → открой в браузере **на ноуте** → залогинься в claude.ai → подтверди → CLI на сервере напечатает токен:\n\n```\n✓ Long-lived authentication token created successfully!\nsk-ant-oat01-yA6U85mCJsuJN7...\n\nUse this token by setting: export CLAUDE_CODE_OAUTH_TOKEN=<token>\n```\n\n**Токен показывается ровно один раз** — скопируй сразу. Действует 1 год, можно ротировать тем же `claude setup-token` (старый автоматически инвалидируется).\n\n**3. Положить токен в `/opt/neurogate/.env`** (или куда у тебя `EnvironmentFile=` systemd-юнита):\n\n```bash\necho \"CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-…\" >> /opt/neurogate/.env\nchmod 600 /opt/neurogate/.env # на всякий\n```\n\n**4. Подвох под systemd:** если у тебя стоит `ProtectHome=yes` (как в шаблоне `neurogate.service` из docs), `/root/.claude/` будет скрыт от subprocess и `claude -p` молча вернёт пустой stdout. Neurogate поймает `claude_cli:* server error: invalid JSON: b''`. Лечение — переопределить `HOME` на путь внутри `ReadWritePaths`:\n\n```ini\n# В /etc/systemd/system/neurogate.service, в секции [Service]:\nEnvironment=HOME=/opt/neurogate\n```\n\nИ `mkdir -p /opt/neurogate/.claude && chmod 700 /opt/neurogate/.claude` перед рестартом — `claude` будет писать туда session-state.\n\n**5. Перезапустить:**\n\n```bash\nsystemctl daemon-reload\nsystemctl restart neurogate\njournalctl -u neurogate -n 30 --no-pager | grep -iE \"claude_cli|chain local\"\n# должно показать: chain local: claude_cli:opus → claude_cli:sonnet → claude_cli:haiku\n```\n\n**6. Smoke с сервера:**\n\n```bash\nTOKEN=$(grep ^NEUROGATE_API_TOKEN= /opt/neurogate/.env | cut -d= -f2)\ncurl -s -H \"Authorization: Bearer $TOKEN\" -H 'Content-Type: application/json' \\\n -d '{\"model\":\"local\",\"messages\":[{\"role\":\"user\",\"content\":\"reply with OK\"}]}' \\\n http://127.0.0.1:8765/v1/chat/completions | jq .choices[0].message.content\n# → \"OK\"\n```\n\n**Цена ошибки:** квота подписки одна на всё. Если на проде идёт боевой трафик через `model=local`, он будет конкурировать с твоим локальным Claude Code за тот же лимит (Pro ~$20/мес-эквивалент токенов, Max в 5× больше). Не подключай `local` в дефолтные chains (`chat`/`code`/`quality`) на проде — оставь явный opt-in, как сейчас.\n\n### OpenAI direct — единоразово $5 ради бесплатной модерации (text + image)\n\n**TL;DR — зачем подключать OpenAI вообще:** ради **бесплатной модерации**. Текстовая (`text-moderation-latest`) и multimodal text+image (`omni-moderation-latest`) у OpenAI **бесплатны навсегда** и качественнее всех альтернатив. Платные модели ($0.05–$10 per 1M токенов) — опционально, если иногда понадобится высокое качество в `paid` chain. **На бесплатные chat / embed / image-gen цепочки OpenAI подключать не нужно** — у Groq / Gemini / Z.ai лимиты щедрее и без депозита.\n\n**Регистрация:**\n\n- https://platform.openai.com (Google / Microsoft / email)\n- https://platform.openai.com/api-keys → *Create new secret key*\n- **ENV**: `OPENAI_API_KEY` (для бесплатной модерации) и опционально `OPENAI_API_KEY_PAID` (для paid-моделей; можно тот же ключ — разделение нужно лишь чтобы случайно не сжечь baseline-баланс)\n\n**Критично — почему без $5 ничего не работает:**\n\nНа Free tier (без привязанной карты) OpenAI режет **все** запросы через `429 Too Many Requests` с `type: invalid_request_error` — **включая бесплатную модерацию**. Это не rate-limit моды, это аккаунт-уровневая блокировка. В ответе нет ни одного `x-ratelimit-*` хедера — это диагностический признак, что блок именно account-level, а не лимит модели. Лечится только депозитом.\n\n**Депозит — единоразово $5:**\n\n1. https://platform.openai.com/settings/organization/billing/overview → *Add payment details*\n2. Введи **`5`** в *Initial credit purchase* (минимум).\n3. ⚠️ **Снять галочку *Automatically add credits when your balance runs low***. По умолчанию она включена. Если оставить — карта будет молча докидывать $5 каждый раз когда баланс упадёт. Это главная ловушка для тех, кто хотел «только бесплатно».\n4. Подтвердить (банк может попросить 3DS).\n5. За 1-5 минут Tier поднимается `Free` → `Tier 1`, лимиты на moderation вырастают с 3 RPM до ~500 RPM.\n\n**Где следить за лимитами и расходом:**\n\n- **Rate limits per model** (RPM/RPD/TPM): https://platform.openai.com/settings/organization/limits — таблица с текущим тиром и лимитами по каждой модели. Полезно проверить после оплаты, что Tier действительно поднялся до 1.\n- **Usage (расход токенов и запросов):** https://platform.openai.com/usage — графики по дням/моделям, что именно сжигало баланс. Здесь же видно, что moderation идёт нулевой строкой.\n- **Billing & balance:** https://platform.openai.com/settings/organization/billing/overview — текущий остаток депозита, история платежей, настройки auto-recharge.\n\n**Стратегия использования $5:**\n\n- **Основной use-case (бесплатно):** модерация — `omni-moderation-latest` (text+image, 13 категорий) и `text-moderation-latest` (legacy text-only, 7 категорий) **не списываются с баланса**. $5 просто лежат бессрочно.\n- **Опционально (платно):** редкие вызовы `paid` chain через `gpt-5-mini` для случаев когда бесплатные провайдеры упёрлись или не справляются с качеством. При умеренном трафике $5 хватает на месяцы.\n- **Не подключать:** chat / embed / image_gen цепочки — у бесплатных провайдеров (Groq / Gemini / Z.ai / Cohere / Voyage / Cloudflare / Pollinations) лимиты на порядки больше.\n\n**Бесплатно после депозита:**\n\n| Модель | Что делает | Цена |\n|---|---|---|\n| `omni-moderation-latest` | Text + image moderation, 13 категорий, native scores | $0 / $0 |\n| `text-moderation-latest` | Legacy text-only, 7 категорий | $0 / $0 |\n\nВ neurogate реализованы как `kind: openai_moderation` в [config.py:118](../src/neurogate/config.py#L118), провайдер [`OpenAIModerationProvider`](../src/neurogate/providers.py#L3205). Обе уже в дефолтных цепочках `moderation` и `moderation_image`.\n\n**Платные модели — опциональный subset для `paid` chain (используя `OPENAI_API_KEY_PAID`):**\n\n| Модель | Цена in/out (per 1M) | Когда нужна |\n|---|---|---|\n| `gpt-5-mini` | $0.25 / $2.00 | Основной paid-fallback. Уже добавлен во вторую позицию `paid` после Claude Opus. |\n| `gpt-5-nano` | $0.05 / $0.40 | Если нужен ультра-дешёвый paid-fallback. На простых запросах хватает. |\n| `gpt-4.1-mini` | $0.40 / $1.60 | **1M контекст** — для длинных документов / RAG. Подключать только если упираешься в context window других моделей. |\n| `whisper-1` | $0.006/мин | STT-fallback после Groq Whisper. Только если делаешь транскрипцию серьёзных объёмов. |\n\n**Не брать:** `o3` (есть `o4-mini` в 4× дешевле), `dall-e-3` (устарел против `gpt-image-1`), `gpt-4o` / `gpt-4o-mini` (`gpt-5-mini`/`nano` дешевле и не хуже), `text-embedding-3-small/large` (Voyage даёт 200M tok permanent free на каждую модель — OpenAI embeddings подключать смысла мало), `gpt-image-1` (Kandinsky / YandexART лучше на фотореализме, см. отдельную заметку).\n\n**В конфиге:** OpenAI-нативный endpoint `https://api.openai.com/v1` — `kind: openai` для chat (`gpt-5-mini` и др.), `kind: openai_moderation` для модерации. Конкретные провайдеры см. в [config.yaml](../config.yaml) (`openai:moderation`, `openai:text-moderation`, `openai:gpt-5-mini`).\n\n## После получения ключей\n\n1. Скопировать: `cp .env.example .env`\n2. Вписать ключи в `.env` (пустые строки neurogate просто пропустит — провайдеры без ключа исключаются из цепочки)\n3. Запустить: `uv run neurogate`\n4. Проверить, какие провайдеры реально доступны: `curl -s -H \"Authorization: Bearer $TOKEN\" http://127.0.0.1:8765/v1/models`\n\nЕсли провайдер упирается в 429 — neurogate автоматически перейдёт к следующему. Если все упали — вернётся HTTP 502 `upstream_exhausted` (на free-тирах в сумме с 1 ключа это ~20-25k сообщений/сутки, так что до потолка надо постараться).\n\n## Если что-то не работает — как сообщить о баге\n\nБез следующих данных мы не можем отделить баг шлюза от проблемы провайдера / твоего соединения / клиента, и фикс затягивается на дни. Скинь всё одним сообщением:\n\n### Чек-лист (минимум)\n\n- [ ] **Что произошло** — одна-две фразы. Что должно было быть, что получилось вместо.\n- [ ] **Скриншот или видео** — обязательно. На скрине должно быть видно: само сообщение об ошибке, время, и (если применимо) URL/endpoint.\n- [ ] **Текст ошибки целиком** — копи-паст, не пересказ. Если приложение режет текст — скрин консоли / network tab из DevTools.\n- [ ] **Когда произошло** — точное время с часовым поясом (например, `2026-05-09 14:32 МСК`). Это нужно чтобы найти запись в логах.\n- [ ] **Что делал до ошибки** — последовательность действий. Например: «открыл Cursor → задал вопрос про код → пошёл стрим, на 3-й секунде оборвался». Или: «отправил длинный документ через Continue → сразу 502». **Воспроизводится повторно или один раз?**\n- [ ] **Тип соединения**:\n - Wi-Fi (домашний роутер / офис / публичный)\n - мобильный интернет (4G/5G)\n - смешанно (когда переключался с одного на другое — отметь)\n- [ ] **Провайдер/оператор**:\n - для мобильного: МТС / Мегафон / Билайн / Tele2 / Yota / другой\n - для домашнего: Ростелеком / МТС / Билайн / ТТК / Дом.ру / другой\n - если за VPN — **обязательно укажи**, какой VPN и какая страна выхода\n- [ ] **Город** (грубо — Москва / СПб / регион / зарубежье). Не для слежки, а потому что некоторые провайдеры блокируют upstream-эндпоинты только в части регионов.\n- [ ] **Какой клиент** и его версия:\n - Cursor / Claude Code / Codex / OpenCode / Continue / Cline / curl / собственный скрипт / браузер\n - версия (например, `Cursor 1.4.2`)\n- [ ] **Какая модель / chain** была запрошена — посмотри в настройках клиента, поле `model:`. Например: `auto`, `chat`, `deepseek:reasoner`, `paid`.\n\n### Желательно (если можешь)\n\n- **Request ID** — если ошибка вернулась с шлюза (HTTP-ответ), там в headers должен быть `x-request-id`. Скинь его — найдём конкретный запрос в логах за миллисекунды.\n- **Скрин Network tab** браузера или вывод `curl -v` — видны заголовки и точный путь.\n- **Размер промпта** — короткий вопрос или длинный документ на 50K токенов? Длинный context часто выявляет баги, которых нет на коротком.\n- **Stream или non-stream** — обычно стрим по умолчанию, но некоторые клиенты выключают.\n\n### Шаблон сообщения\n\nСкопируй и заполни:\n\n```\nЧто произошло:\nСкриншот/видео: (приложить файл)\nТекст ошибки:\n <вставить текст>\nКогда: 2026-05-09 HH:MM МСК\nЧто делал до:\nВоспроизводится: да / нет / иногда\nСоединение: Wi-Fi / мобильный\nОператор:\nVPN: нет / да (страна: ...)\nГород:\nКлиент: ... версия ...\nМодель/chain:\nRequest ID:\n```\n\n### Почему мы спрашиваем про оператора\n\nneurogate за собой держит 15+ upstream-провайдеров (Groq, Cerebras, SambaNova, Gemini, OpenRouter, DeepSeek, …). Часть из них **блокируется или режется на уровне отдельных российских операторов** — эта блокировка не от шлюза, а от твоего ISP. Признаки: connection reset / timeout / SSL handshake fail на конкретный домен. На разных операторах живут разные подмножества upstream'ов:\n\n- МТС иногда режет HuggingFace и часть Cloudflare-эндпоинтов\n- Мегафон блокирует часть Google IP-блоков → Gemini нестабильна\n- Ростелеком блокирует часть международного трафика по DPI\n- Из мобильного интернета бывает странный SNI-фильтр\n\nБез информации про оператора мы будем час крутить логи в поисках бага в коде, которого нет.\n"}, "84605fcea100cef076a8ade91ac981b850664826": {"t": 1785765654.5060852, "n": 37044, "h": "4d0f8022ddf3d854", "c": "# Как получить API-ключи провайдеров\n\nПошаговая инструкция для всех провайдеров из [config.yaml.example](../config.yaml.example) — где зарегистрироваться, где взять ключ, какая переменная в [.env.example](../.env.example), важные нюансы.\n\n**Минимум для старта**: достаточно 1-2 ключей — neurogate пропустит позиции, у которых ключ пустой, и пойдёт дальше по цепочке. Стартап-репорт на консоли подскажет, какие именно env-vars не заполнены и какие провайдеры это включит. Начать проще всего с **Groq** (самый быстрый onboarding) + **Gemini** (самая жирная квота на 1 ключ).\n\n## Free quota at a glance\n\nСводная таблица. Две колонки маркеров:\n\n**Cap (квота):**\n- 🟢 **effectively unlimited** — нет суточного/месячного потолка по запросам, ограничение только на RPM (или concurrency). Можно жечь хоть 24/7.\n- 🟡 **RPD-capped** — есть суточный потолок (счётчик ресетится 00:00 UTC, обычно).\n- 🔵 **monthly / token quota** — потолок по токенам или вызовам в месяц / в год.\n- 🟣 **anonymous / no key** — без ключа.\n\n**Privacy (что провайдер делает с твоими промптами):**\n- 🔒 **private** — провайдер заявляет «не обучаем на твоих данных» (free tier).\n- ⚠️ **trains on free tier** — на free-тире промпты/ответы могут уходить в обучение. Не клади чувствительное.\n- 🟣 **public-by-design** — community-инфраструктура, твои промпты видны другим.\n\nЦифры на free-тирах часто меняются — `/v1/models` и dashboard покажут реальную картину. Privacy-метки взяты из публично заявленных политик; они не аудит, а ориентир.\n\n| Cap | Privacy | Провайдер | ENV-переменная | Лимит | Phone | Card | Особенность |\n|---|---|---|---|---|---|---|---|\n| 🟢 | 🔒 | **NVIDIA NIM** | `NVIDIA_API_KEY` | 40 RPM, без RPD | нет | нет | TTFB медленный — в `unlimited`/фоллбэк. |\n| 🟢 | 🔒 | **Z.ai** | `ZAI_API_KEY` | concurrency-only | нет | нет | GLM-4.5-Flash permanent free. China upstream — оф. заявляет «no training», но юрисдикция КНР. |\n| 🟢 | 🔒 | **Cerebras** | `CEREBRAS_API_KEY` | 5–30 RPM, без RPD | да | нет | Узкий выбор моделей, но потолка нет. Enterprise-friendly TOS. |\n| 🟢 | ⚠️ | **Mistral** | `MISTRAL_API_KEY` | ~4 RPM, без RPD | да | нет | Experiment plan. На free тренируется на твоих промптах. Paid plan — opt-out. |\n| 🟡 | 🔒 | **SambaNova** | `SAMBANOVA_API_KEY` | 20 RPD **на модель** | нет | нет | 4 модели = 80 RPD на ключ. Enterprise-friendly. |\n| 🟡 | ⚠️ | **Groq** | `GROQ_API_KEY` | 30 RPM, 1k–14.4k RPD | нет | нет | Самый быстрый onboarding. Privacy policy позволяет использовать промпты для improvements. |\n| 🟡 | ⚠️ | **Gemini (AI Studio)** | `GEMINI_API_KEY` | 10 RPM, 250-1500 RPD | нет | нет | Per-project: 2-3 GCP-проекта = ×N квота. **На free tier Google использует промпты для улучшения моделей.** Paid Vertex — opt-out. |\n| 🟡 | 🔒 | **Cloudflare Workers AI** | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` | 300 RPD (Llama 70B) | нет | нет | Edge inference, image gen бесплатно. CF не тренирует. |\n| 🟡 | 🔒 | **GitHub Models** | `GITHUB_MODELS_TOKEN` | 50–150 RPD | нет | нет | gpt-5-mini в free tier. Microsoft не тренирует на промптах GitHub Models. |\n| 🟡 | ⚠️ | **OpenRouter (free)** | `OPENROUTER_API_KEY` | 20 RPM, 50 RPD (1000 с $10) | нет | нет\\* | Каждая `:free`-модель имеет свою policy — у некоторых тренировка включена. Читай каточку модели. |\n| 🟡 | ⚠️ | **FreeTheAi** | `FREETHEAI_API_KEY` | 10 RPM, 1 concurrent | нет (Discord) | нет | **Требует daily Discord `/checkin`**. Privacy не задекларирована — считай что промпты видят. |\n| 🟡 | 🔒 | **OVHcloud** | — (anon) | 2 RPM на IP | нет | нет | EU-инфра, без ключа, не тренирует. |\n| 🔵 | ⚠️ | **GigaChat (Sber)** | `GIGACHAT_AUTH_KEY` | Freemium quota / год | да (РФ) | нет | Чат слабоват, но **есть бесплатная Kandinsky image gen**. Free tier — обучаются. См. §11. |\n| 🔵 | ⚠️ | **HuggingFace** | `HF_TOKEN` | ~$0.10/мес общий кредит | нет | нет | Кредит на paid sub-providers. Каждый sub-provider — своя privacy policy. |\n| 🔵 | ⚠️ | **DeepSeek** | `DEEPSEEK_API_KEY` | 5M tok signup credits, дальше PAYG | да | нет | Off-peak 50–75% скидка. **CN-юрисдикция, тренируются на промптах.** |\n| 🔵 | ⚠️ | **Alibaba DashScope Intl** | `DASHSCOPE_API_KEY` | 1M tok / model × 90 дней | да | да | Singapore region, 1M context на флагманах. CN-юрисдикция. |\n| 🔵 | 🔒 | **Cohere** | `COHERE_API_KEY` | 20 RPM, 1000 calls/мес | нет | нет | **Non-commercial only** на free tier (ToS). Не тренируются. |\n| 🟣 | 🟣 | **LibreTranslate** | — (anon) | varies | нет | нет | Public mirror. Логи могут вестись на стороне зеркала. |\n| 🟣 | 🟣 | **MyMemory** | `MYMEMORY_CONTACT_EMAIL` (опц) | 5k–50k chars/IP | нет | нет | Community translation memory — твои тексты могут пополнять корпус. |\n| 🟣 | 🔒 | **Edge TTS** | — (anon) | без лимита | нет | нет | MS Edge — голос синтезируется serverside, текст не сохраняется. |\n| 🟣 | 🟣 | **AIhorde** | — (anon) | community queue | нет | нет | Распределённый inference — твой prompt видит worker, который на нём генерирует картинку. |\n\n\\* OpenRouter не требует карту для базового free tier, но $10 однократный депозит поднимает лимиты в 20 раз.\n\n**TL;DR (квоты).** Если нужен **24/7-бэкбон** — собирай цепочку из 🟢 (NVIDIA + Z.ai + Cerebras + Mistral): они не упираются в суточный потолок. Если нужен **широкий пул моделей** — добавляй 🟡 (Groq, Gemini, OpenRouter, GitHub) — они дают разнообразие, но ресетятся каждые 24ч. 🔵 — на конкретные ниши (Cohere для не-коммерческого RU, DeepSeek для signup-кредитов, GigaChat для Kandinsky).\n\n**TL;DR (privacy).** Для **чувствительного трафика** (внутренние документы, персональные данные клиентов) бери только 🔒: NVIDIA, Cerebras, Cloudflare, GitHub Models, Cohere, SambaNova. Z.ai заявляет no-training, но юрисдикция КНР — для коммерческой тайны не годится. Всё что 🟣 — public-by-design, такие провайдеры можно использовать только для безличных текстов (переводы общего назначения, генерация фоновых картинок). Если в чейне смешаны провайдеры — фоллбэк может уйти на ⚠️-провайдера; для строгого режима оставь только 🔒-провайдеров либо подними отдельный `chains: private:` под чувствительный трафик.\n\n### Quick suggestion: какие 2-3 ключа добавить первыми\n\n- **Самый быстрый старт:** Groq (без верификаций) → мгновенный отклик и приличная квота.\n- **Долгий контекст / vision:** Gemini.\n- **Бэкбон без RPD-капа:** Cerebras (одно подтверждение телефона) или NVIDIA.\n- **Русский:** Yandex Alice (`yandex_foundation` kind) — на наш опыт лучше GigaChat для RU.\n- **Картинки бесплатно:** Cloudflare (FLUX/SDXL без RPD на image gen) или GigaChat (Kandinsky — фотореализм держит лучше FLUX).\n\n## Провайдеры\n\n### 1. Gemini (Google)\n\n- **Регистрация**: любой Google-аккаунт\n- **Получить ключ**: https://aistudio.google.com/apikey → *Create API key*\n- **ENV**: `GEMINI_API_KEY`\n- **Нюанс**: квота считается **per-project**, не per-key. Если завести 2-3 GCP-проекта на том же Google-аккаунте и сгенерить по ключу в каждом, получишь 2-3× квоту легально (TOS это разрешает — дубликаты запрещены только на уровне аккаунтов). Дополнительные ключи можно прописать как `GEMINI_API_KEY_2`, `GEMINI_API_KEY_3` и завести дубликаты провайдеров в `config.yaml` с разными `api_key_env`.\n\n### 2. Groq\n\n- **Регистрация**: https://console.groq.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Create API Key*\n- **ENV**: `GROQ_API_KEY`\n- **Нюанс**: самый быстрый провайдер в цепочке (300-1000+ токенов/сек). Free tier даёт 1000 RPD на `llama-3.3-70b-versatile` и 14400 RPD на `llama-3.1-8b-instant`. Дубликаты аккаунтов Groq ловит и банит оба — **не регистрируй второй аккаунт** с того же IP/телефона/карты.\n\n### 3. Cerebras\n\n- **Регистрация**: https://cloud.cerebras.ai (требует подтверждение телефона)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `CEREBRAS_API_KEY`\n- **Нюанс**: нет суточного лимита, но free tier сейчас узкий — реально работают только `qwen-3-235b-a22b-instruct-2507` (5 RPM) и `llama3.1-8b` (30 RPM). Более крупные модели (llama-3.3-70b, gpt-oss-120b) депрекейтнуты или paid-only.\n\n### 4. SambaNova\n\n- **Регистрация**: https://cloud.sambanova.ai (Google / email)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `SAMBANOVA_API_KEY`\n- **Нюанс**: 20 RPD **на каждую модель**, а не на аккаунт — 4 SambaNova-позиции в цепочке дают суммарно 80 RPD на один ключ. Лимит читается из заголовка `x-ratelimit-limit-requests-day` в ответе.\n\n### 5. NVIDIA NIM\n\n- **Регистрация**: https://build.nvidia.com (email, developer-программа)\n- **Получить ключ**: профиль справа вверху → *Get API Key* → выдают ключ вида `nvapi-...`\n- **ENV**: `NVIDIA_API_KEY`\n- **Нюанс**: формально **только для research/dev/test** — production TOS требует AI Enterprise license (~$4500/GPU/год). Для личного бота не критично. Нет суточного лимита, только RPM (40 на большинстве моделей).\n\n### 6. Z.ai (GLM)\n\n- **Регистрация**: https://z.ai (international) или https://open.bigmodel.cn (Китай — для аккаунтов из РФ/СНГ)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `ZAI_API_KEY`\n- **Нюанс**: `glm-4.5-flash` — **permanent free**, без RPD-лимита. В конфиге стоит `extra_body: { thinking: { type: disabled } }` — это принудительно отключает reasoning-режим (по умолчанию модель тратит токены на chain-of-thought, что режет скорость). Z.ai официально заявляет «no training on API data» — ок для чувствительного трафика.\n\n### 7. OpenRouter\n\n- **Регистрация**: https://openrouter.ai (Google / GitHub / MetaMask)\n- **Получить ключ**: https://openrouter.ai/keys → *Create Key*\n- **ENV**: `OPENROUTER_API_KEY`\n- **Нюанс**: `:free` модели делят глобальный пул 50 RPD на всех пользователей планеты — часто упирается в лимит к вечеру UTC. **Однократный депозит $10** поднимает RPD → 1000 на все `:free` модели (сами $10 не сгорают, лежат на балансе). Это единственное действие с 20× ROI на лимиты — см. «Платные расширения».\n\n### 8. Cloudflare Workers AI\n\n- **Регистрация**: https://dash.cloudflare.com (email)\n- **Получить ключ**: *My Profile* (правый верх) → *API Tokens* → *Create Token* → шаблон *Workers AI* (или custom: permission `Account → Workers AI → Read` + `Edit`)\n- **Получить Account ID**: на главной странице dashboard в правом сайдбаре — строка *Account ID*\n- **ENV**: `CLOUDFLARE_API_KEY` (токен) + `CLOUDFLARE_ACCOUNT_ID`\n- **Нюанс**: единственный провайдер, которому нужны **две** переменные. Account ID нельзя передать как env — Cloudflare вшивает его в URL запроса. 300 RPD на Llama 70B fp8-fast.\n\n### 9. GitHub Models\n\n- **Регистрация**: любой GitHub-аккаунт\n- **Получить токен**: https://github.com/settings/personal-access-tokens → *Generate new token (fine-grained)* → Account permissions → **Models: Read-only**\n- Классический PAT (`settings/tokens`) тоже работает, но fine-grained безопаснее — скоуп только на Models, не трогает репы.\n- **ENV**: `GITHUB_MODELS_TOKEN`\n- **Нюанс**: endpoint `https://models.github.ai/inference`, жёсткий потолок 8K токенов на запрос (input+output). Лимиты 50-150 RPD по моделям, считаются на токен.\n\n### 10. Mistral La Plateforme\n\n- **Регистрация**: https://console.mistral.ai (email + SMS-верификация)\n- **Получить ключ**: *API Keys*\n- **План**: выбрать **Experiment** (бесплатный) — даёт доступ к `mistral-large-latest` и остальным флагманам\n- **ENV**: `MISTRAL_API_KEY`\n- **Нюанс**: **обязательно зайти** в *Admin* → *Privacy* и **выключить опцию использования данных для обучения** — по умолчанию она включена. Без этого твои запросы уходят на training. Лимит ~4 RPM (заголовок `x-ratelimit-limit-req-minute`), не 60 как в старых доках.\n\n### 11. HuggingFace Inference Providers Router\n\n- **Регистрация**: любой HuggingFace-аккаунт https://huggingface.co\n- **Получить токен**: *Settings* → *Access Tokens* → *Create new token* → тип **Read**\n- **ENV**: `HF_TOKEN`\n- **Нюанс**: HF проксирует запросы к paid sub-providers (Novita, Cerebras, Together, …) через единый OpenAI-совместимый endpoint. Free tier даёт **~$0.10/мес общего кредита** на все sub-providers — этого хватает на эксперименты, не на постоянный трафик. **PRO-подписка ($9/мес)** даёт $2 кредита/мес. Модель указывается как `<repo>:<sub-provider>`, например `meta-llama/Llama-3.3-70B-Instruct:novita`.\n\n### 12. GigaChat (SberDevices)\n\n- **Регистрация**: https://developers.sber.ru/studio (требует подтверждённый аккаунт Сбера, телефон РФ)\n- **Получить ключ**: *Личное пространство* → *Мой GigaChat API* → *Получить новый ключ* → выдают `Authorization key` (это уже base64 от `client_id:client_secret`, готовый для `Basic`-авторизации)\n- **ENV**: `GIGACHAT_AUTH_KEY` (значение строки *Authorization key* как есть)\n- **Scope**: `GIGACHAT_API_PERS` — **Freemium** для физлиц с годовой квотой токенов (точные цифры Сбер периодически меняет — смотри актуальное на странице тарифа). По нашему опыту, на личное использование хватает с запасом.\n- **Чат vs картинки**: текстовые модели (GigaChat 2 / 2-Pro / 2-Max) на наш опыт **слабее даже отдельных Qwen / GLM** на русском, и заметно отстают от Yandex Alice. Но **бесплатная Kandinsky image gen** в этом же ключе — единственный способ получить русскоязычно-обученную text-to-image модель «из коробки», и она хорошо держит фотореализм когда в промпте есть «digital painting» / «oil painting» (где FLUX даёт «пластик»). Стоит держать в `image_gen` chain ради этого.\n- **Нюанс 1**: GigaChat отдаёт сертификат, подписанный *Russian Trusted Root CA* — стандартные системные truststore (на macOS/Linux вне РФ) его не знают. В конфиге для `kind: gigachat` стоит `verify_ssl: false`. Для прода — добавить Russian Trusted Sub CA в системный truststore.\n- **Нюанс 2**: авторизация двухступенчатая — провайдер обменивает `Authorization key` на короткоживущий OAuth access-token и кэширует его. Этот flow реализован внутри `kind: gigachat`, ничего вручную делать не нужно.\n- **Биллинг и расход**: https://developers.sber.ru/studio (раздел *Проекты* → *Лицевой счёт*).\n\n### 13. FreeTheAi\n\n- **Регистрация**: только через Discord. Зайти на сервер → https://discord.gg/secrets → команда `/signup` в канале #api-keys (https://discord.com/channels/1461555807731585158/1473159205048553705) → бот пришлёт ключ вида `sta_…` в DM. Если потерял — `/resetkey`.\n- **ENV**: `FREETHEAI_API_KEY`\n- **Лимиты**: 10 RPM + **1 concurrent** на ключ — последовательные вызовы, никакого parallel.\n- **Каталог**: ~16 252 алиасов. Префиксы: `cat/*` (gpt-5/claude/gemini frontier через прокси), `bbg/*` (DeepSeek/GLM/Kimi/MiniMax reasoning), `bbl/*` (Gemini/GPT non-reasoning), `or/*` (OpenRouter passthrough), `vhr/*` (image-gen scrap из Vheer), `img/gpt-image-2` (image gen+edit b64), `fth/*` (16k случайных HF моделей — почти всегда мусор). Не все алиасы реально работают — `glm/glm-5.1` (#1 в leaderboard) и `cat/gemini-3-1-pro` возвращают 400/timeout. Перед использованием — пробовать.\n- **⚠️ Главный нюанс — DAILY /checkin**: ключ блокируется **каждые 24 часа**. Чтобы разлочить — заходишь в Discord, в тот же канал #api-keys пишешь `/checkin`, бот возвращает «ключ активен на 24h». Без этого все запросы получают `HTTP 403 daily_checkin_required`.\n- **Автоматизировать /checkin НЕЛЬЗЯ**:\n 1. Discord ToS запрещает self-bot'ы (использование своего user-токена для скриптов) — ловят и банят аккаунт.\n 2. Обычные боты Discord не могут вызывать slash-команды других ботов (by design платформы).\n 3. Browser-automation поверх web-Discord — та же категория self-bot, ban guarantied.\n 4. FreeTheAi специально поставили /checkin как защиту от abuse — обходить = бан и от них тоже.\n- **Когда использовать**:\n - Ad-hoc-запросы для тестов (`model: \"freetheai:cat/gpt-5\"`) — 24h cooldown терпим, если не забыл сделать /checkin утром.\n - Не для продовых chains (без daily-checkin сервис ляжет).\n- **Bait-and-switch**: проверка identity показала, что `cat/claude-4-6-sonnet` отвечает «built by Tiny» — это НЕ Claude. `cat/gpt-5` идентифицируется как OpenAI, но без гарантий. `bbg/deepseek-v4-pro` выдаёт gibberish. Перед интеграцией каждой модели в логику — прогнать identity-test.\n- **Image-gen**: `vhr/*` модели возвращают URL'ы на `access.vheer.com` — это прокси на бесплатный Vheer.com сервис, файлы хранятся у них. `img/gpt-image-2` отдаёт b64 (~650KB на запрос) — единственная модель, поддерживающая edits.\n\n### 14. DeepSeek (direct API)\n\n**Пошагово (получить ключ):**\n\n1. Открой https://platform.deepseek.com → *Sign Up* (Google или email)\n2. Phone verify — российские номера принимает (МТС/Мегафон/Билайн/Tele2). Если по какой-то причине не принимает твой номер — попробуй через Google-аккаунт.\n3. После входа: левое меню → *API Keys* → *Create new API key* → дать любое имя → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается **один раз** — потом только regenerate.\n4. В `.env` локально и на проде:\n ```\n DEEPSEEK_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **5M токенов signup credits** + 7-14 дней без RPM-лимитов. Этого хватит на много экспериментов.\n- Модели: `deepseek-chat` (V3.2) и `deepseek-reasoner` (R1/R2).\n\n**Когда signup credits закончатся (опционально):**\n\n- $2 топ-ап ≈ 170 ₽ → месяцы PAYG-работы (`deepseek-chat` $0.28/$0.42 за 1M, `deepseek-reasoner` сопоставимо).\n- Off-peak 16:30–00:30 UTC — скидка 50% на V3, 75% на R1.\n- Prefix caching: cache hit в 4–10× дешевле miss. Структурируй промпты так, чтобы стабильный префикс (system + RAG) шёл первым, юзер-ввод — последним.\n- ⚠️ **Не включай auto-recharge** — карта будет молча докидывать каждый раз когда баланс падает.\n- ⚠️ Российские карты Visa/MC топ-ап **не примет**. Варианты: карта дружественной страны (Казахстан/Армения/Грузия), Wise/Revolut, виртуалка от иностранного fintech.\n\n**Подводные камни:**\n\n- **Privacy**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**. Если через шлюз идут чувствительные данные клиентов — либо удали DeepSeek из chain, либо ставь его последним позади cohere/openrouter/sambanova.\n- **Из России без VPN**: иногда нестабильные 5xx-ответы. Держи fallback в той же chain ниже — он сработает автоматически.\n\n**kind**: `deepseek`. Provider в config.yaml — простая запись с `model: deepseek-chat` или `model: deepseek-reasoner`. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 15. Alibaba DashScope International (Qwen)\n\n**⚠️ Самый муторный из четырёх. Делай утром, на это уйдёт 20-30 минут.**\n\n**Пошагово (получить ключ):**\n\n1. Открой https://accountclient.alibabacloud.com/intl → *Sign Up*\n2. **Регион — обязательно Singapore.** US/HK/EU/China версии free quota НЕ дают. Если на этапе onboarding спрашивает регион — выбирай Singapore. Если уже зарегистрировался в другом регионе — придётся завести отдельный аккаунт.\n3. Phone verify (российские номера принимает).\n4. **Карта обязательна** — для Real-name Verification. С карты ничего не списывается, но без привязки free quota не активируется.\n - ⚠️ Российские карты Visa/MC **не пройдут**.\n - Варианты:\n - Карта дружественной страны (Казахстан / Армения / Грузия)\n - Wise / Revolut если есть\n - Виртуальная карта от иностранного fintech (Pyypl, Genome, etc.)\n5. После Real-name Verification → открыть https://bailian.console.alibabacloud.com (Model Studio, регион Singapore)\n6. Левое меню → *API-KEY* → *Create* → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается полностью один раз.\n7. В `.env` локально и на проде:\n ```\n DASHSCOPE_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **1M токенов на каждую модель** × **90 дней** с момента активации. Десятки моделей в каталоге → десятки миллионов токенов суммарно.\n- Флагманы: `qwen3.6-plus` (топ-3 на OpenRouter trafficу, 1M context, всегда-вкл CoT), `qwen3.6-max-preview`, `qwen3-coder-480b-a35b-instruct`, `qwen3-next-80b-a3b-instruct/thinking`, `qwen3-vl-plus`.\n\n**После 90 дней**: paid-only. Поставь напоминание `/schedule` за неделю до истечения — посмотрим использование и решим продлять или уйти на DashScope-paid.\n\n**Подводные камни:**\n\n- **Регион Singapore ОБЯЗАТЕЛЬНО**. Endpoint в config.py уже забит: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. Если у тебя аккаунт в другом регионе — ключ будет работать, но free quota = 0.\n- **Privacy**: Alibaba явно заявляет «will never use your data for model training», данные в Сингапуре → **можно использовать с PII** в отличие от китайского endpoint DeepSeek.\n- **Real-name Verification может зависнуть на сутки** — в первый раз. Если статус «pending» больше 24ч — открыть тикет в support.\n\n**kind**: `dashscope`. Provider в config.yaml — простая запись с `model: qwen3.6-plus` или другой моделью. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 16. Cohere (Command-A / c4ai-aya — для русского)\n\n- **Регистрация**: https://dashboard.cohere.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Generate Trial Key*\n- **ENV**: `COHERE_API_KEY`\n- **Free tier**: 20 RPM на модель, 1000 calls/месяц (≈33 RPD safe-floor).\n- **Модели**: `c4ai-aya-expanse-32b/8b` — multilingual, **сильный русский**. `c4ai-aya-vision-32b/8b` — vision. `command-a-03-2025` — флагман общего назначения. `command-a-reasoning-08-2025` — reasoning. `command-a-translate-08-2025` — translation.\n- **ToS**: free tier — **non-commercial only**. Для open-source / личных проектов ок. Если кто-то форкнет коммерчески — нарушение. Помечай в README.\n- **Особенность реализации**: Cohere v2 /chat — собственный response shape (`{message: {content: [{type:'text', text:...}]}}`), не OpenAI-compat. Streaming эмулируется одним SSE chunk'ом из полного ответа (Cohere v2 SSE имеет свой формат, дешевле fake-stream чем переводить).\n- **kind**: `cohere_chat` (для chat) или `cohere` (для translate-only). Эмбеддинги отдельно — `cohere_embed`.\n\n### 17. OVHcloud AI Endpoints (anonymous, без ключа)\n\n- **Регистрация**: НЕ ТРЕБУЕТСЯ. Endpoint анонимный.\n- **ENV**: НЕТ. В config.yaml запись `kind: ovhcloud` без `api_key_env`.\n- **Endpoint**: `https://oai.endpoints.kepler.ai.cloud.ovh.net/v1` — OpenAI-совместимый.\n- **Лимит**: 2 RPM **на IP** на модель. Без ключа — прозрачный rate-limit, при превышении 429.\n- **Каталог**: 40+ open-моделей, EU-host (Франция/Германия). Llama 3.x, Mistral, Qwen, Mixtral, gpt-oss-120b, и т.д.\n- **Когда использовать**: исключительно как **deep fallback / last-resort** в конце chain — «лучше отдать что-то, чем 503». В основной chain ставить нет смысла из-за 2 RPM на IP.\n- **Реализация**: `OpenAICompatProvider` пропускает `Authorization` header при пустом `api_key` (см. providers.py — изменение из этого PR).\n- **kind**: `ovhcloud`.\n\n## Платные расширения (опционально)\n\nНиже — одноразовые или recurring платные действия с непропорционально большим профитом на лимиты.\n\n### OpenRouter — $10 депозит → 20× квоты\n\n**Что делает**: однократный пополнение на $10 поднимает 50 RPD → **1000 RPD** на все `:free` модели (DeepSeek R1/V3.2, Llama 4 Maverick/Scout, Qwen3 235B, GLM-5 `:free`, Kimi K2 `:free`, MiniMax M2 `:free`, Qwen3-Coder 480B `:free`).\n\n**Как**: *Settings* → *Credits* → пополнить любую сумму ≥ $10. Сами $10 остаются на балансе и тратятся только если ты явно вызовешь платную модель. Для `:free` — это просто unlock лимита.\n\n**После депозита**: в `config.yaml` обновить `rpd: 50` → `rpd: 1000` на всех позициях с `kind: openrouter`.\n\n### xAI Grok — $25 signup + $150/мес recurring\n\n- **Регистрация**: https://console.x.ai (phone verify)\n- **Signup**: $25 кредитов на 30 дней\n- **Data-sharing program**: opt-in на sharing → $150/мес recurring (обновляется пока включено, требует минимум $5 spend за период)\n- **Зачем**: Grok 4.1 Fast — уникальный **2M context window**, никто больше такого не даёт\n- **В конфиг**: нужен `kind: xai` провайдер (OpenAI-compat endpoint `https://api.x.ai/v1`). **Пока не реализован** в neurogate.\n\n### Alibaba Qwen Singapore — 1M токенов × десятки моделей на 90 дней\n\n- **Регистрация**: https://accountclient.alibabacloud.com/intl (требует телефон и карту, +966 работает)\n- **Регион критичен**: Singapore. Endpoint `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. US/HK/EU версии free quota не дают.\n- **Квота**: 1M токенов **на каждую модель** на 90 дней → десятки моделей × 1M = десятки миллионов токенов суммарно. Флагманы: `qwen3-max`, `qwen-plus`, `qwen-flash`, `qwen3-coder-plus`, `qwen3.5-plus`.\n- **Privacy**: официально «will never use your data for model training», данные в Сингапуре.\n- **После 90 дней**: paid-only.\n- **В конфиг**: `kind: dashscope` — нативно поддерживается, см. секцию #15 выше для деталей.\n\n### DeepSeek direct — 5M signup credits + off-peak 50-75%\n\n- **Регистрация**: https://platform.deepseek.com (phone verify)\n- **Signup**: 5M токенов + 7-14 дней без rate limits\n- **Off-peak**: 16:30-00:30 UTC — **50% скидка на V3, 75% на R1**. Годится для batch-задач, не для realtime-чата.\n- **Privacy-блокер**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**.\n- **В конфиг**: `kind: deepseek` — нативно поддерживается, см. секцию #14 выше для деталей.\n\n### Anthropic Claude direct — $5 signup\n\n- **Регистрация**: https://console.anthropic.com (phone verify)\n- **Signup**: $5 кредитов на 30 дней после phone verify\n- **Зачем**: единственный способ добавить frontier Claude Sonnet/Opus в цепочку без Bedrock/Databricks\n- **Нюанс**: Anthropic API не OpenAI-compat — нужен отдельный `kind: anthropic`. В neurogate **пока не реализован**.\n\n### Claude CLI — через подписку Claude.ai без API-ключа\n\nЕсли у тебя уже оплачена подписка **Claude.ai Pro/Max** и установлен **Claude Code**, neurogate может ходить в Opus/Sonnet/Haiku через локальный `claude -p` — никакого Anthropic API-ключа не нужно, расход идёт из подписочной квоты.\n\n**Когда брать:**\n- Локальная разработка: подписка уже оплачена, хочется чтобы и пет-проекты на neurogate ходили через неё.\n- Не нужны streaming / tool calling / vision (v1 ограничение).\n- Готов мириться с ~0.4–1с холодным стартом `claude` процесса на каждый запрос.\n\n**Когда НЕ брать:**\n- Продакшен на VPS — `claude` бинаря обычно нет, провайдер авто-скипнется.\n- High-volume / latency-sensitive — каждый запрос форкает Node-процесс.\n- Нужны streaming / tools / vision — провайдер их не поддерживает (router автоматически отскочит на следующего в chain).\n\n**Setup:**\n\n1. Установи Claude Code — https://docs.claude.com/en/docs/claude-code\n2. Авторизуйся: `claude /login` (откроет браузер, залогинит через claude.ai). Токен сохранится в `~/.claude/` и переживёт ребут.\n3. Smoke test:\n ```bash\n claude -p \"say hi\" --output-format json | jq .result\n ```\n Должен вернуть строку с приветствием.\n4. (Опц.) если бинарь не в `PATH` — пропиши абсолютный путь в `NEUROGATE_CLAUDE_CLI_PATH=` в `.env`.\n\n**Использование в neurogate:**\n\n```bash\n# Прямой выбор модели:\ncurl -s http://127.0.0.1:8765/v1/chat/completions \\\n -H 'Content-Type: application/json' \\\n -d '{\"model\":\"claude_cli:opus\",\"messages\":[{\"role\":\"user\",\"content\":\"привет\"}]}'\n\n# Через chain `local` (opus → sonnet → haiku фоллбэк):\ncurl -s http://127.0.0.1:8765/v1/chat/completions \\\n -H 'Content-Type: application/json' \\\n -d '{\"model\":\"local\",\"messages\":[{\"role\":\"user\",\"content\":\"привет\"}]}'\n```\n\n**Ограничения v1 (намеренно):**\n- **Text-only**: streaming, tool calling, vision — не поддерживаются. Router пре-флайт перенаправит запросы с `stream:true` / `tools:[...]` / image-content на следующего провайдера в chain.\n- **`temperature` и `max_tokens` игнорируются** — `claude -p` их не принимает. Если тебе важна детерминированность через `temperature=0` — этот провайдер не подойдёт.\n- **Каждый запрос — отдельный subprocess**: ~0.4–1с cold-start (форк Node-процесса), плюс собственно генерация. Не для high-volume.\n- **Квота подписки не видна neurogate** — `rate_tracker` считает локальные RPM/RPD из YAML (по умолчанию 30/500 для Opus), реальный остаток квоты Claude.ai не виден до получения 429.\n- **Multi-turn flattening**: история сообщений сериализуется в `Human:/Assistant:` транскрипт и отправляется как единый prompt. На длинных диалогах качество может проседать сильнее чем при native messages API.\n\n**На сервере (VPS) ничего настраивать не нужно** — если `claude` не установлен, все три `claude_cli:*` записи и chain `local` пропустятся на старте с понятной записью в логе (`skipping claude_cli:opus : claude binary not found`).\n\n### OpenAI direct — единоразово $5 ради бесплатной модерации (text + image)\n\n**TL;DR — зачем подключать OpenAI вообще:** ради **бесплатной модерации**. Текстовая (`text-moderation-latest`) и multimodal text+image (`omni-moderation-latest`) у OpenAI **бесплатны навсегда** и качественнее всех альтернатив. Платные модели ($0.05–$10 per 1M токенов) — опционально, если иногда понадобится высокое качество в `paid` chain. **На бесплатные chat / embed / image-gen цепочки OpenAI подключать не нужно** — у Groq / Gemini / Z.ai лимиты щедрее и без депозита.\n\n**Регистрация:**\n\n- https://platform.openai.com (Google / Microsoft / email)\n- https://platform.openai.com/api-keys → *Create new secret key*\n- **ENV**: `OPENAI_API_KEY` (для бесплатной модерации) и опционально `OPENAI_API_KEY_PAID` (для paid-моделей; можно тот же ключ — разделение нужно лишь чтобы случайно не сжечь baseline-баланс)\n\n**Критично — почему без $5 ничего не работает:**\n\nНа Free tier (без привязанной карты) OpenAI режет **все** запросы через `429 Too Many Requests` с `type: invalid_request_error` — **включая бесплатную модерацию**. Это не rate-limit моды, это аккаунт-уровневая блокировка. В ответе нет ни одного `x-ratelimit-*` хедера — это диагностический признак, что блок именно account-level, а не лимит модели. Лечится только депозитом.\n\n**Депозит — единоразово $5:**\n\n1. https://platform.openai.com/settings/organization/billing/overview → *Add payment details*\n2. Введи **`5`** в *Initial credit purchase* (минимум).\n3. ⚠️ **Снять галочку *Automatically add credits when your balance runs low***. По умолчанию она включена. Если оставить — карта будет молча докидывать $5 каждый раз когда баланс упадёт. Это главная ловушка для тех, кто хотел «только бесплатно».\n4. Подтвердить (банк может попросить 3DS).\n5. За 1-5 минут Tier поднимается `Free` → `Tier 1`, лимиты на moderation вырастают с 3 RPM до ~500 RPM.\n\n**Где следить за лимитами и расходом:**\n\n- **Rate limits per model** (RPM/RPD/TPM): https://platform.openai.com/settings/organization/limits — таблица с текущим тиром и лимитами по каждой модели. Полезно проверить после оплаты, что Tier действительно поднялся до 1.\n- **Usage (расход токенов и запросов):** https://platform.openai.com/usage — графики по дням/моделям, что именно сжигало баланс. Здесь же видно, что moderation идёт нулевой строкой.\n- **Billing & balance:** https://platform.openai.com/settings/organization/billing/overview — текущий остаток депозита, история платежей, настройки auto-recharge.\n\n**Стратегия использования $5:**\n\n- **Основной use-case (бесплатно):** модерация — `omni-moderation-latest` (text+image, 13 категорий) и `text-moderation-latest` (legacy text-only, 7 категорий) **не списываются с баланса**. $5 просто лежат бессрочно.\n- **Опционально (платно):** редкие вызовы `paid` chain через `gpt-5-mini` для случаев когда бесплатные провайдеры упёрлись или не справляются с качеством. При умеренном трафике $5 хватает на месяцы.\n- **Не подключать:** chat / embed / image_gen цепочки — у бесплатных провайдеров (Groq / Gemini / Z.ai / Cohere / Voyage / Cloudflare / Pollinations) лимиты на порядки больше.\n\n**Бесплатно после депозита:**\n\n| Модель | Что делает | Цена |\n|---|---|---|\n| `omni-moderation-latest` | Text + image moderation, 13 категорий, native scores | $0 / $0 |\n| `text-moderation-latest` | Legacy text-only, 7 категорий | $0 / $0 |\n\nВ neurogate реализованы как `kind: openai_moderation` в [config.py:118](../src/neurogate/config.py#L118), провайдер [`OpenAIModerationProvider`](../src/neurogate/providers.py#L3205). Обе уже в дефолтных цепочках `moderation` и `moderation_image`.\n\n**Платные модели — опциональный subset для `paid` chain (используя `OPENAI_API_KEY_PAID`):**\n\n| Модель | Цена in/out (per 1M) | Когда нужна |\n|---|---|---|\n| `gpt-5-mini` | $0.25 / $2.00 | Основной paid-fallback. Уже добавлен во вторую позицию `paid` после Claude Opus. |\n| `gpt-5-nano` | $0.05 / $0.40 | Если нужен ультра-дешёвый paid-fallback. На простых запросах хватает. |\n| `gpt-4.1-mini` | $0.40 / $1.60 | **1M контекст** — для длинных документов / RAG. Подключать только если упираешься в context window других моделей. |\n| `whisper-1` | $0.006/мин | STT-fallback после Groq Whisper. Только если делаешь транскрипцию серьёзных объёмов. |\n\n**Не брать:** `o3` (есть `o4-mini` в 4× дешевле), `dall-e-3` (устарел против `gpt-image-1`), `gpt-4o` / `gpt-4o-mini` (`gpt-5-mini`/`nano` дешевле и не хуже), `text-embedding-3-small/large` (Voyage даёт 200M tok permanent free на каждую модель — OpenAI embeddings подключать смысла мало), `gpt-image-1` (Kandinsky / YandexART лучше на фотореализме, см. отдельную заметку).\n\n**В конфиге:** OpenAI-нативный endpoint `https://api.openai.com/v1` — `kind: openai` для chat (`gpt-5-mini` и др.), `kind: openai_moderation` для модерации. Конкретные провайдеры см. в [config.yaml](../config.yaml) (`openai:moderation`, `openai:text-moderation`, `openai:gpt-5-mini`).\n\n## После получения ключей\n\n1. Скопировать: `cp .env.example .env`\n2. Вписать ключи в `.env` (пустые строки neurogate просто пропустит — провайдеры без ключа исключаются из цепочки)\n3. Запустить: `uv run neurogate`\n4. Проверить, какие провайдеры реально доступны: `curl -s -H \"Authorization: Bearer $TOKEN\" http://127.0.0.1:8765/v1/models`\n\nЕсли провайдер упирается в 429 — neurogate автоматически перейдёт к следующему. Если все упали — вернётся HTTP 502 `upstream_exhausted` (на free-тирах в сумме с 1 ключа это ~20-25k сообщений/сутки, так что до потолка надо постараться).\n\n## Если что-то не работает — как сообщить о баге\n\nБез следующих данных мы не можем отделить баг шлюза от проблемы провайдера / твоего соединения / клиента, и фикс затягивается на дни. Скинь всё одним сообщением:\n\n### Чек-лист (минимум)\n\n- [ ] **Что произошло** — одна-две фразы. Что должно было быть, что получилось вместо.\n- [ ] **Скриншот или видео** — обязательно. На скрине должно быть видно: само сообщение об ошибке, время, и (если применимо) URL/endpoint.\n- [ ] **Текст ошибки целиком** — копи-паст, не пересказ. Если приложение режет текст — скрин консоли / network tab из DevTools.\n- [ ] **Когда произошло** — точное время с часовым поясом (например, `2026-05-09 14:32 МСК`). Это нужно чтобы найти запись в логах.\n- [ ] **Что делал до ошибки** — последовательность действий. Например: «открыл Cursor → задал вопрос про код → пошёл стрим, на 3-й секунде оборвался». Или: «отправил длинный документ через Continue → сразу 502». **Воспроизводится повторно или один раз?**\n- [ ] **Тип соединения**:\n - Wi-Fi (домашний роутер / офис / публичный)\n - мобильный интернет (4G/5G)\n - смешанно (когда переключался с одного на другое — отметь)\n- [ ] **Провайдер/оператор**:\n - для мобильного: МТС / Мегафон / Билайн / Tele2 / Yota / другой\n - для домашнего: Ростелеком / МТС / Билайн / ТТК / Дом.ру / другой\n - если за VPN — **обязательно укажи**, какой VPN и какая страна выхода\n- [ ] **Город** (грубо — Москва / СПб / регион / зарубежье). Не для слежки, а потому что некоторые провайдеры блокируют upstream-эндпоинты только в части регионов.\n- [ ] **Какой клиент** и его версия:\n - Cursor / Claude Code / Codex / OpenCode / Continue / Cline / curl / собственный скрипт / браузер\n - версия (например, `Cursor 1.4.2`)\n- [ ] **Какая модель / chain** была запрошена — посмотри в настройках клиента, поле `model:`. Например: `auto`, `chat`, `deepseek:reasoner`, `paid`.\n\n### Желательно (если можешь)\n\n- **Request ID** — если ошибка вернулась с шлюза (HTTP-ответ), там в headers должен быть `x-request-id`. Скинь его — найдём конкретный запрос в логах за миллисекунды.\n- **Скрин Network tab** браузера или вывод `curl -v` — видны заголовки и точный путь.\n- **Размер промпта** — короткий вопрос или длинный документ на 50K токенов? Длинный context часто выявляет баги, которых нет на коротком.\n- **Stream или non-stream** — обычно стрим по умолчанию, но некоторые клиенты выключают.\n\n### Шаблон сообщения\n\nСкопируй и заполни:\n\n```\nЧто произошло:\nСкриншот/видео: (приложить файл)\nТекст ошибки:\n <вставить текст>\nКогда: 2026-05-09 HH:MM МСК\nЧто делал до:\nВоспроизводится: да / нет / иногда\nСоединение: Wi-Fi / мобильный\nОператор:\nVPN: нет / да (страна: ...)\nГород:\nКлиент: ... версия ...\nМодель/chain:\nRequest ID:\n```\n\n### Почему мы спрашиваем про оператора\n\nneurogate за собой держит 15+ upstream-провайдеров (Groq, Cerebras, SambaNova, Gemini, OpenRouter, DeepSeek, …). Часть из них **блокируется или режется на уровне отдельных российских операторов** — эта блокировка не от шлюза, а от твоего ISP. Признаки: connection reset / timeout / SSL handshake fail на конкретный домен. На разных операторах живут разные подмножества upstream'ов:\n\n- МТС иногда режет HuggingFace и часть Cloudflare-эндпоинтов\n- Мегафон блокирует часть Google IP-блоков → Gemini нестабильна\n- Ростелеком блокирует часть международного трафика по DPI\n- Из мобильного интернета бывает странный SNI-фильтр\n\nБез информации про оператора мы будем час крутить логи в поисках бага в коде, которого нет.\n"}, "16c39de0fd6e21cd0398157108b1b21fa1c71f1a": {"t": 1785765656.3472512, "n": 34145, "h": "67c238bc4dd7053d", "c": "# Как получить API-ключи провайдеров\n\nПошаговая инструкция для всех провайдеров из [config.yaml.example](../config.yaml.example) — где зарегистрироваться, где взять ключ, какая переменная в [.env.example](../.env.example), важные нюансы.\n\n**Минимум для старта**: достаточно 1-2 ключей — neurogate пропустит позиции, у которых ключ пустой, и пойдёт дальше по цепочке. Стартап-репорт на консоли подскажет, какие именно env-vars не заполнены и какие провайдеры это включит. Начать проще всего с **Groq** (самый быстрый onboarding) + **Gemini** (самая жирная квота на 1 ключ).\n\n## Free quota at a glance\n\nСводная таблица. Две колонки маркеров:\n\n**Cap (квота):**\n- 🟢 **effectively unlimited** — нет суточного/месячного потолка по запросам, ограничение только на RPM (или concurrency). Можно жечь хоть 24/7.\n- 🟡 **RPD-capped** — есть суточный потолок (счётчик ресетится 00:00 UTC, обычно).\n- 🔵 **monthly / token quota** — потолок по токенам или вызовам в месяц / в год.\n- 🟣 **anonymous / no key** — без ключа.\n\n**Privacy (что провайдер делает с твоими промптами):**\n- 🔒 **private** — провайдер заявляет «не обучаем на твоих данных» (free tier).\n- ⚠️ **trains on free tier** — на free-тире промпты/ответы могут уходить в обучение. Не клади чувствительное.\n- 🟣 **public-by-design** — community-инфраструктура, твои промпты видны другим.\n\nЦифры на free-тирах часто меняются — `/v1/models` и dashboard покажут реальную картину. Privacy-метки взяты из публично заявленных политик; они не аудит, а ориентир.\n\n| Cap | Privacy | Провайдер | ENV-переменная | Лимит | Phone | Card | Особенность |\n|---|---|---|---|---|---|---|---|\n| 🟢 | 🔒 | **NVIDIA NIM** | `NVIDIA_API_KEY` | 40 RPM, без RPD | нет | нет | TTFB медленный — в `unlimited`/фоллбэк. |\n| 🟢 | 🔒 | **Z.ai** | `ZAI_API_KEY` | concurrency-only | нет | нет | GLM-4.5-Flash permanent free. China upstream — оф. заявляет «no training», но юрисдикция КНР. |\n| 🟢 | 🔒 | **Cerebras** | `CEREBRAS_API_KEY` | 5–30 RPM, без RPD | да | нет | Узкий выбор моделей, но потолка нет. Enterprise-friendly TOS. |\n| 🟢 | ⚠️ | **Mistral** | `MISTRAL_API_KEY` | ~4 RPM, без RPD | да | нет | Experiment plan. На free тренируется на твоих промптах. Paid plan — opt-out. |\n| 🟡 | 🔒 | **SambaNova** | `SAMBANOVA_API_KEY` | 20 RPD **на модель** | нет | нет | 4 модели = 80 RPD на ключ. Enterprise-friendly. |\n| 🟡 | ⚠️ | **Groq** | `GROQ_API_KEY` | 30 RPM, 1k–14.4k RPD | нет | нет | Самый быстрый onboarding. Privacy policy позволяет использовать промпты для improvements. |\n| 🟡 | ⚠️ | **Gemini (AI Studio)** | `GEMINI_API_KEY` | 10 RPM, 250-1500 RPD | нет | нет | Per-project: 2-3 GCP-проекта = ×N квота. **На free tier Google использует промпты для улучшения моделей.** Paid Vertex — opt-out. |\n| 🟡 | 🔒 | **Cloudflare Workers AI** | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` | 300 RPD (Llama 70B) | нет | нет | Edge inference, image gen бесплатно. CF не тренирует. |\n| 🟡 | 🔒 | **GitHub Models** | `GITHUB_MODELS_TOKEN` | 50–150 RPD | нет | нет | gpt-5-mini в free tier. Microsoft не тренирует на промптах GitHub Models. |\n| 🟡 | ⚠️ | **OpenRouter (free)** | `OPENROUTER_API_KEY` | 20 RPM, 50 RPD (1000 с $10) | нет | нет\\* | Каждая `:free`-модель имеет свою policy — у некоторых тренировка включена. Читай каточку модели. |\n| 🟡 | ⚠️ | **FreeTheAi** | `FREETHEAI_API_KEY` | 10 RPM, 1 concurrent | нет (Discord) | нет | **Требует daily Discord `/checkin`**. Privacy не задекларирована — считай что промпты видят. |\n| 🟡 | 🔒 | **OVHcloud** | — (anon) | 2 RPM на IP | нет | нет | EU-инфра, без ключа, не тренирует. |\n| 🔵 | ⚠️ | **GigaChat (Sber)** | `GIGACHAT_AUTH_KEY` | Freemium quota / год | да (РФ) | нет | Чат слабоват, но **есть бесплатная Kandinsky image gen**. Free tier — обучаются. См. §11. |\n| 🔵 | ⚠️ | **HuggingFace** | `HF_TOKEN` | ~$0.10/мес общий кредит | нет | нет | Кредит на paid sub-providers. Каждый sub-provider — своя privacy policy. |\n| 🔵 | ⚠️ | **DeepSeek** | `DEEPSEEK_API_KEY` | 5M tok signup credits, дальше PAYG | да | нет | Off-peak 50–75% скидка. **CN-юрисдикция, тренируются на промптах.** |\n| 🔵 | ⚠️ | **Alibaba DashScope Intl** | `DASHSCOPE_API_KEY` | 1M tok / model × 90 дней | да | да | Singapore region, 1M context на флагманах. CN-юрисдикция. |\n| 🔵 | 🔒 | **Cohere** | `COHERE_API_KEY` | 20 RPM, 1000 calls/мес | нет | нет | **Non-commercial only** на free tier (ToS). Не тренируются. |\n| 🟣 | 🟣 | **LibreTranslate** | — (anon) | varies | нет | нет | Public mirror. Логи могут вестись на стороне зеркала. |\n| 🟣 | 🟣 | **MyMemory** | `MYMEMORY_CONTACT_EMAIL` (опц) | 5k–50k chars/IP | нет | нет | Community translation memory — твои тексты могут пополнять корпус. |\n| 🟣 | 🔒 | **Edge TTS** | — (anon) | без лимита | нет | нет | MS Edge — голос синтезируется serverside, текст не сохраняется. |\n| 🟣 | 🟣 | **AIhorde** | — (anon) | community queue | нет | нет | Распределённый inference — твой prompt видит worker, который на нём генерирует картинку. |\n\n\\* OpenRouter не требует карту для базового free tier, но $10 однократный депозит поднимает лимиты в 20 раз.\n\n**TL;DR (квоты).** Если нужен **24/7-бэкбон** — собирай цепочку из 🟢 (NVIDIA + Z.ai + Cerebras + Mistral): они не упираются в суточный потолок. Если нужен **широкий пул моделей** — добавляй 🟡 (Groq, Gemini, OpenRouter, GitHub) — они дают разнообразие, но ресетятся каждые 24ч. 🔵 — на конкретные ниши (Cohere для не-коммерческого RU, DeepSeek для signup-кредитов, GigaChat для Kandinsky).\n\n**TL;DR (privacy).** Для **чувствительного трафика** (внутренние документы, персональные данные клиентов) бери только 🔒: NVIDIA, Cerebras, Cloudflare, GitHub Models, Cohere, SambaNova. Z.ai заявляет no-training, но юрисдикция КНР — для коммерческой тайны не годится. Всё что 🟣 — public-by-design, такие провайдеры можно использовать только для безличных текстов (переводы общего назначения, генерация фоновых картинок). Если в чейне смешаны провайдеры — фоллбэк может уйти на ⚠️-провайдера; для строгого режима оставь только 🔒-провайдеров либо подними отдельный `chains: private:` под чувствительный трафик.\n\n### Quick suggestion: какие 2-3 ключа добавить первыми\n\n- **Самый быстрый старт:** Groq (без верификаций) → мгновенный отклик и приличная квота.\n- **Долгий контекст / vision:** Gemini.\n- **Бэкбон без RPD-капа:** Cerebras (одно подтверждение телефона) или NVIDIA.\n- **Русский:** Yandex Alice (`yandex_foundation` kind) — на наш опыт лучше GigaChat для RU.\n- **Картинки бесплатно:** Cloudflare (FLUX/SDXL без RPD на image gen) или GigaChat (Kandinsky — фотореализм держит лучше FLUX).\n\n## Провайдеры\n\n### 1. Gemini (Google)\n\n- **Регистрация**: любой Google-аккаунт\n- **Получить ключ**: https://aistudio.google.com/apikey → *Create API key*\n- **ENV**: `GEMINI_API_KEY`\n- **Нюанс**: квота считается **per-project**, не per-key. Если завести 2-3 GCP-проекта на том же Google-аккаунте и сгенерить по ключу в каждом, получишь 2-3× квоту легально (TOS это разрешает — дубликаты запрещены только на уровне аккаунтов). Дополнительные ключи можно прописать как `GEMINI_API_KEY_2`, `GEMINI_API_KEY_3` и завести дубликаты провайдеров в `config.yaml` с разными `api_key_env`.\n\n### 2. Groq\n\n- **Регистрация**: https://console.groq.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Create API Key*\n- **ENV**: `GROQ_API_KEY`\n- **Нюанс**: самый быстрый провайдер в цепочке (300-1000+ токенов/сек). Free tier даёт 1000 RPD на `llama-3.3-70b-versatile` и 14400 RPD на `llama-3.1-8b-instant`. Дубликаты аккаунтов Groq ловит и банит оба — **не регистрируй второй аккаунт** с того же IP/телефона/карты.\n\n### 3. Cerebras\n\n- **Регистрация**: https://cloud.cerebras.ai (требует подтверждение телефона)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `CEREBRAS_API_KEY`\n- **Нюанс**: нет суточного лимита, но free tier сейчас узкий — реально работают только `qwen-3-235b-a22b-instruct-2507` (5 RPM) и `llama3.1-8b` (30 RPM). Более крупные модели (llama-3.3-70b, gpt-oss-120b) депрекейтнуты или paid-only.\n\n### 4. SambaNova\n\n- **Регистрация**: https://cloud.sambanova.ai (Google / email)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `SAMBANOVA_API_KEY`\n- **Нюанс**: 20 RPD **на каждую модель**, а не на аккаунт — 4 SambaNova-позиции в цепочке дают суммарно 80 RPD на один ключ. Лимит читается из заголовка `x-ratelimit-limit-requests-day` в ответе.\n\n### 5. NVIDIA NIM\n\n- **Регистрация**: https://build.nvidia.com (email, developer-программа)\n- **Получить ключ**: профиль справа вверху → *Get API Key* → выдают ключ вида `nvapi-...`\n- **ENV**: `NVIDIA_API_KEY`\n- **Нюанс**: формально **только для research/dev/test** — production TOS требует AI Enterprise license (~$4500/GPU/год). Для личного бота не критично. Нет суточного лимита, только RPM (40 на большинстве моделей).\n\n### 6. Z.ai (GLM)\n\n- **Регистрация**: https://z.ai (international) или https://open.bigmodel.cn (Китай — для аккаунтов из РФ/СНГ)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `ZAI_API_KEY`\n- **Нюанс**: `glm-4.5-flash` — **permanent free**, без RPD-лимита. В конфиге стоит `extra_body: { thinking: { type: disabled } }` — это принудительно отключает reasoning-режим (по умолчанию модель тратит токены на chain-of-thought, что режет скорость). Z.ai официально заявляет «no training on API data» — ок для чувствительного трафика.\n\n### 7. OpenRouter\n\n- **Регистрация**: https://openrouter.ai (Google / GitHub / MetaMask)\n- **Получить ключ**: https://openrouter.ai/keys → *Create Key*\n- **ENV**: `OPENROUTER_API_KEY`\n- **Нюанс**: `:free` модели делят глобальный пул 50 RPD на всех пользователей планеты — часто упирается в лимит к вечеру UTC. **Однократный депозит $10** поднимает RPD → 1000 на все `:free` модели (сами $10 не сгорают, лежат на балансе). Это единственное действие с 20× ROI на лимиты — см. «Платные расширения».\n\n### 8. Cloudflare Workers AI\n\n- **Регистрация**: https://dash.cloudflare.com (email)\n- **Получить ключ**: *My Profile* (правый верх) → *API Tokens* → *Create Token* → шаблон *Workers AI* (или custom: permission `Account → Workers AI → Read` + `Edit`)\n- **Получить Account ID**: на главной странице dashboard в правом сайдбаре — строка *Account ID*\n- **ENV**: `CLOUDFLARE_API_KEY` (токен) + `CLOUDFLARE_ACCOUNT_ID`\n- **Нюанс**: единственный провайдер, которому нужны **две** переменные. Account ID нельзя передать как env — Cloudflare вшивает его в URL запроса. 300 RPD на Llama 70B fp8-fast.\n\n### 9. GitHub Models\n\n- **Регистрация**: любой GitHub-аккаунт\n- **Получить токен**: https://github.com/settings/personal-access-tokens → *Generate new token (fine-grained)* → Account permissions → **Models: Read-only**\n- Классический PAT (`settings/tokens`) тоже работает, но fine-grained безопаснее — скоуп только на Models, не трогает репы.\n- **ENV**: `GITHUB_MODELS_TOKEN`\n- **Нюанс**: endpoint `https://models.github.ai/inference`, жёсткий потолок 8K токенов на запрос (input+output). Лимиты 50-150 RPD по моделям, считаются на токен.\n\n### 10. Mistral La Plateforme\n\n- **Регистрация**: https://console.mistral.ai (email + SMS-верификация)\n- **Получить ключ**: *API Keys*\n- **План**: выбрать **Experiment** (бесплатный) — даёт доступ к `mistral-large-latest` и остальным флагманам\n- **ENV**: `MISTRAL_API_KEY`\n- **Нюанс**: **обязательно зайти** в *Admin* → *Privacy* и **выключить опцию использования данных для обучения** — по умолчанию она включена. Без этого твои запросы уходят на training. Лимит ~4 RPM (заголовок `x-ratelimit-limit-req-minute`), не 60 как в старых доках.\n\n### 11. HuggingFace Inference Providers Router\n\n- **Регистрация**: любой HuggingFace-аккаунт https://huggingface.co\n- **Получить токен**: *Settings* → *Access Tokens* → *Create new token* → тип **Read**\n- **ENV**: `HF_TOKEN`\n- **Нюанс**: HF проксирует запросы к paid sub-providers (Novita, Cerebras, Together, …) через единый OpenAI-совместимый endpoint. Free tier даёт **~$0.10/мес общего кредита** на все sub-providers — этого хватает на эксперименты, не на постоянный трафик. **PRO-подписка ($9/мес)** даёт $2 кредита/мес. Модель указывается как `<repo>:<sub-provider>`, например `meta-llama/Llama-3.3-70B-Instruct:novita`.\n\n### 12. GigaChat (SberDevices)\n\n- **Регистрация**: https://developers.sber.ru/studio (требует подтверждённый аккаунт Сбера, телефон РФ)\n- **Получить ключ**: *Личное пространство* → *Мой GigaChat API* → *Получить новый ключ* → выдают `Authorization key` (это уже base64 от `client_id:client_secret`, готовый для `Basic`-авторизации)\n- **ENV**: `GIGACHAT_AUTH_KEY` (значение строки *Authorization key* как есть)\n- **Scope**: `GIGACHAT_API_PERS` — **Freemium** для физлиц с годовой квотой токенов (точные цифры Сбер периодически меняет — смотри актуальное на странице тарифа). По нашему опыту, на личное использование хватает с запасом.\n- **Чат vs картинки**: текстовые модели (GigaChat 2 / 2-Pro / 2-Max) на наш опыт **слабее даже отдельных Qwen / GLM** на русском, и заметно отстают от Yandex Alice. Но **бесплатная Kandinsky image gen** в этом же ключе — единственный способ получить русскоязычно-обученную text-to-image модель «из коробки», и она хорошо держит фотореализм когда в промпте есть «digital painting» / «oil painting» (где FLUX даёт «пластик»). Стоит держать в `image_gen` chain ради этого.\n- **Нюанс 1**: GigaChat отдаёт сертификат, подписанный *Russian Trusted Root CA* — стандартные системные truststore (на macOS/Linux вне РФ) его не знают. В конфиге для `kind: gigachat` стоит `verify_ssl: false`. Для прода — добавить Russian Trusted Sub CA в системный truststore.\n- **Нюанс 2**: авторизация двухступенчатая — провайдер обменивает `Authorization key` на короткоживущий OAuth access-token и кэширует его. Этот flow реализован внутри `kind: gigachat`, ничего вручную делать не нужно.\n- **Биллинг и расход**: https://developers.sber.ru/studio (раздел *Проекты* → *Лицевой счёт*).\n\n### 13. FreeTheAi\n\n- **Регистрация**: только через Discord. Зайти на сервер → https://discord.gg/secrets → команда `/signup` в канале #api-keys (https://discord.com/channels/1461555807731585158/1473159205048553705) → бот пришлёт ключ вида `sta_…` в DM. Если потерял — `/resetkey`.\n- **ENV**: `FREETHEAI_API_KEY`\n- **Лимиты**: 10 RPM + **1 concurrent** на ключ — последовательные вызовы, никакого parallel.\n- **Каталог**: ~16 252 алиасов. Префиксы: `cat/*` (gpt-5/claude/gemini frontier через прокси), `bbg/*` (DeepSeek/GLM/Kimi/MiniMax reasoning), `bbl/*` (Gemini/GPT non-reasoning), `or/*` (OpenRouter passthrough), `vhr/*` (image-gen scrap из Vheer), `img/gpt-image-2` (image gen+edit b64), `fth/*` (16k случайных HF моделей — почти всегда мусор). Не все алиасы реально работают — `glm/glm-5.1` (#1 в leaderboard) и `cat/gemini-3-1-pro` возвращают 400/timeout. Перед использованием — пробовать.\n- **⚠️ Главный нюанс — DAILY /checkin**: ключ блокируется **каждые 24 часа**. Чтобы разлочить — заходишь в Discord, в тот же канал #api-keys пишешь `/checkin`, бот возвращает «ключ активен на 24h». Без этого все запросы получают `HTTP 403 daily_checkin_required`.\n- **Автоматизировать /checkin НЕЛЬЗЯ**:\n 1. Discord ToS запрещает self-bot'ы (использование своего user-токена для скриптов) — ловят и банят аккаунт.\n 2. Обычные боты Discord не могут вызывать slash-команды других ботов (by design платформы).\n 3. Browser-automation поверх web-Discord — та же категория self-bot, ban guarantied.\n 4. FreeTheAi специально поставили /checkin как защиту от abuse — обходить = бан и от них тоже.\n- **Когда использовать**:\n - Ad-hoc-запросы для тестов (`model: \"freetheai:cat/gpt-5\"`) — 24h cooldown терпим, если не забыл сделать /checkin утром.\n - Не для продовых chains (без daily-checkin сервис ляжет).\n- **Bait-and-switch**: проверка identity показала, что `cat/claude-4-6-sonnet` отвечает «built by Tiny» — это НЕ Claude. `cat/gpt-5` идентифицируется как OpenAI, но без гарантий. `bbg/deepseek-v4-pro` выдаёт gibberish. Перед интеграцией каждой модели в логику — прогнать identity-test.\n- **Image-gen**: `vhr/*` модели возвращают URL'ы на `access.vheer.com` — это прокси на бесплатный Vheer.com сервис, файлы хранятся у них. `img/gpt-image-2` отдаёт b64 (~650KB на запрос) — единственная модель, поддерживающая edits.\n\n### 14. DeepSeek (direct API)\n\n**Пошагово (получить ключ):**\n\n1. Открой https://platform.deepseek.com → *Sign Up* (Google или email)\n2. Phone verify — российские номера принимает (МТС/Мегафон/Билайн/Tele2). Если по какой-то причине не принимает твой номер — попробуй через Google-аккаунт.\n3. После входа: левое меню → *API Keys* → *Create new API key* → дать любое имя → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается **один раз** — потом только regenerate.\n4. В `.env` локально и на проде:\n ```\n DEEPSEEK_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **5M токенов signup credits** + 7-14 дней без RPM-лимитов. Этого хватит на много экспериментов.\n- Модели: `deepseek-chat` (V3.2) и `deepseek-reasoner` (R1/R2).\n\n**Когда signup credits закончатся (опционально):**\n\n- $2 топ-ап ≈ 170 ₽ → месяцы PAYG-работы (`deepseek-chat` $0.28/$0.42 за 1M, `deepseek-reasoner` сопоставимо).\n- Off-peak 16:30–00:30 UTC — скидка 50% на V3, 75% на R1.\n- Prefix caching: cache hit в 4–10× дешевле miss. Структурируй промпты так, чтобы стабильный префикс (system + RAG) шёл первым, юзер-ввод — последним.\n- ⚠️ **Не включай auto-recharge** — карта будет молча докидывать каждый раз когда баланс падает.\n- ⚠️ Российские карты Visa/MC топ-ап **не примет**. Варианты: карта дружественной страны (Казахстан/Армения/Грузия), Wise/Revolut, виртуалка от иностранного fintech.\n\n**Подводные камни:**\n\n- **Privacy**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**. Если через шлюз идут чувствительные данные клиентов — либо удали DeepSeek из chain, либо ставь его последним позади cohere/openrouter/sambanova.\n- **Из России без VPN**: иногда нестабильные 5xx-ответы. Держи fallback в той же chain ниже — он сработает автоматически.\n\n**kind**: `deepseek`. Provider в config.yaml — простая запись с `model: deepseek-chat` или `model: deepseek-reasoner`. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 15. Alibaba DashScope International (Qwen)\n\n**⚠️ Самый муторный из четырёх. Делай утром, на это уйдёт 20-30 минут.**\n\n**Пошагово (получить ключ):**\n\n1. Открой https://accountclient.alibabacloud.com/intl → *Sign Up*\n2. **Регион — обязательно Singapore.** US/HK/EU/China версии free quota НЕ дают. Если на этапе onboarding спрашивает регион — выбирай Singapore. Если уже зарегистрировался в другом регионе — придётся завести отдельный аккаунт.\n3. Phone verify (российские номера принимает).\n4. **Карта обязательна** — для Real-name Verification. С карты ничего не списывается, но без привязки free quota не активируется.\n - ⚠️ Российские карты Visa/MC **не пройдут**.\n - Варианты:\n - Карта дружественной страны (Казахстан / Армения / Грузия)\n - Wise / Revolut если есть\n - Виртуальная карта от иностранного fintech (Pyypl, Genome, etc.)\n5. После Real-name Verification → открыть https://bailian.console.alibabacloud.com (Model Studio, регион Singapore)\n6. Левое меню → *API-KEY* → *Create* → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается полностью один раз.\n7. В `.env` локально и на проде:\n ```\n DASHSCOPE_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **1M токенов на каждую модель** × **90 дней** с момента активации. Десятки моделей в каталоге → десятки миллионов токенов суммарно.\n- Флагманы: `qwen3.6-plus` (топ-3 на OpenRouter trafficу, 1M context, всегда-вкл CoT), `qwen3.6-max-preview`, `qwen3-coder-480b-a35b-instruct`, `qwen3-next-80b-a3b-instruct/thinking`, `qwen3-vl-plus`.\n\n**После 90 дней**: paid-only. Поставь напоминание `/schedule` за неделю до истечения — посмотрим использование и решим продлять или уйти на DashScope-paid.\n\n**Подводные камни:**\n\n- **Регион Singapore ОБЯЗАТЕЛЬНО**. Endpoint в config.py уже забит: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. Если у тебя аккаунт в другом регионе — ключ будет работать, но free quota = 0.\n- **Privacy**: Alibaba явно заявляет «will never use your data for model training», данные в Сингапуре → **можно использовать с PII** в отличие от китайского endpoint DeepSeek.\n- **Real-name Verification может зависнуть на сутки** — в первый раз. Если статус «pending» больше 24ч — открыть тикет в support.\n\n**kind**: `dashscope`. Provider в config.yaml — простая запись с `model: qwen3.6-plus` или другой моделью. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 16. Cohere (Command-A / c4ai-aya — для русского)\n\n- **Регистрация**: https://dashboard.cohere.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Generate Trial Key*\n- **ENV**: `COHERE_API_KEY`\n- **Free tier**: 20 RPM на модель, 1000 calls/месяц (≈33 RPD safe-floor).\n- **Модели**: `c4ai-aya-expanse-32b/8b` — multilingual, **сильный русский**. `c4ai-aya-vision-32b/8b` — vision. `command-a-03-2025` — флагман общего назначения. `command-a-reasoning-08-2025` — reasoning. `command-a-translate-08-2025` — translation.\n- **ToS**: free tier — **non-commercial only**. Для open-source / личных проектов ок. Если кто-то форкнет коммерчески — нарушение. Помечай в README.\n- **Особенность реализации**: Cohere v2 /chat — собственный response shape (`{message: {content: [{type:'text', text:...}]}}`), не OpenAI-compat. Streaming эмулируется одним SSE chunk'ом из полного ответа (Cohere v2 SSE имеет свой формат, дешевле fake-stream чем переводить).\n- **kind**: `cohere_chat` (для chat) или `cohere` (для translate-only). Эмбеддинги отдельно — `cohere_embed`.\n\n### 17. OVHcloud AI Endpoints (anonymous, без ключа)\n\n- **Регистрация**: НЕ ТРЕБУЕТСЯ. Endpoint анонимный.\n- **ENV**: НЕТ. В config.yaml запись `kind: ovhcloud` без `api_key_env`.\n- **Endpoint**: `https://oai.endpoints.kepler.ai.cloud.ovh.net/v1` — OpenAI-совместимый.\n- **Лимит**: 2 RPM **на IP** на модель. Без ключа — прозрачный rate-limit, при превышении 429.\n- **Каталог**: 40+ open-моделей, EU-host (Франция/Германия). Llama 3.x, Mistral, Qwen, Mixtral, gpt-oss-120b, и т.д.\n- **Когда использовать**: исключительно как **deep fallback / last-resort** в конце chain — «лучше отдать что-то, чем 503». В основной chain ставить нет смысла из-за 2 RPM на IP.\n- **Реализация**: `OpenAICompatProvider` пропускает `Authorization` header при пустом `api_key` (см. providers.py — изменение из этого PR).\n- **kind**: `ovhcloud`.\n\n## Платные расширения (опционально)\n\nНиже — одноразовые или recurring платные действия с непропорционально большим профитом на лимиты.\n\n### OpenRouter — $10 депозит → 20× квоты\n\n**Что делает**: однократный пополнение на $10 поднимает 50 RPD → **1000 RPD** на все `:free` модели (DeepSeek R1/V3.2, Llama 4 Maverick/Scout, Qwen3 235B, GLM-5 `:free`, Kimi K2 `:free`, MiniMax M2 `:free`, Qwen3-Coder 480B `:free`).\n\n**Как**: *Settings* → *Credits* → пополнить любую сумму ≥ $10. Сами $10 остаются на балансе и тратятся только если ты явно вызовешь платную модель. Для `:free` — это просто unlock лимита.\n\n**После депозита**: в `config.yaml` обновить `rpd: 50` → `rpd: 1000` на всех позициях с `kind: openrouter`.\n\n### xAI Grok — $25 signup + $150/мес recurring\n\n- **Регистрация**: https://console.x.ai (phone verify)\n- **Signup**: $25 кредитов на 30 дней\n- **Data-sharing program**: opt-in на sharing → $150/мес recurring (обновляется пока включено, требует минимум $5 spend за период)\n- **Зачем**: Grok 4.1 Fast — уникальный **2M context window**, никто больше такого не даёт\n- **В конфиг**: нужен `kind: xai` провайдер (OpenAI-compat endpoint `https://api.x.ai/v1`). **Пока не реализован** в neurogate.\n\n### Alibaba Qwen Singapore — 1M токенов × десятки моделей на 90 дней\n\n- **Регистрация**: https://accountclient.alibabacloud.com/intl (требует телефон и карту, +966 работает)\n- **Регион критичен**: Singapore. Endpoint `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. US/HK/EU версии free quota не дают.\n- **Квота**: 1M токенов **на каждую модель** на 90 дней → десятки моделей × 1M = десятки миллионов токенов суммарно. Флагманы: `qwen3-max`, `qwen-plus`, `qwen-flash`, `qwen3-coder-plus`, `qwen3.5-plus`.\n- **Privacy**: официально «will never use your data for model training», данные в Сингапуре.\n- **После 90 дней**: paid-only.\n- **В конфиг**: `kind: dashscope` — нативно поддерживается, см. секцию #15 выше для деталей.\n\n### DeepSeek direct — 5M signup credits + off-peak 50-75%\n\n- **Регистрация**: https://platform.deepseek.com (phone verify)\n- **Signup**: 5M токенов + 7-14 дней без rate limits\n- **Off-peak**: 16:30-00:30 UTC — **50% скидка на V3, 75% на R1**. Годится для batch-задач, не для realtime-чата.\n- **Privacy-блокер**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**.\n- **В конфиг**: `kind: deepseek` — нативно поддерживается, см. секцию #14 выше для деталей.\n\n### Anthropic Claude direct — $5 signup\n\n- **Регистрация**: https://console.anthropic.com (phone verify)\n- **Signup**: $5 кредитов на 30 дней после phone verify\n- **Зачем**: единственный способ добавить frontier Claude Sonnet/Opus в цепочку без Bedrock/Databricks\n- **Нюанс**: Anthropic API не OpenAI-compat — нужен отдельный `kind: anthropic`. В neurogate **пока не реализован**.\n\n### OpenAI direct — единоразово $5 ради бесплатной модерации (text + image)\n\n**TL;DR — зачем подключать OpenAI вообще:** ради **бесплатной модерации**. Текстовая (`text-moderation-latest`) и multimodal text+image (`omni-moderation-latest`) у OpenAI **бесплатны навсегда** и качественнее всех альтернатив. Платные модели ($0.05–$10 per 1M токенов) — опционально, если иногда понадобится высокое качество в `paid` chain. **На бесплатные chat / embed / image-gen цепочки OpenAI подключать не нужно** — у Groq / Gemini / Z.ai лимиты щедрее и без депозита.\n\n**Регистрация:**\n\n- https://platform.openai.com (Google / Microsoft / email)\n- https://platform.openai.com/api-keys → *Create new secret key*\n- **ENV**: `OPENAI_API_KEY` (для бесплатной модерации) и опционально `OPENAI_API_KEY_PAID` (для paid-моделей; можно тот же ключ — разделение нужно лишь чтобы случайно не сжечь baseline-баланс)\n\n**Критично — почему без $5 ничего не работает:**\n\nНа Free tier (без привязанной карты) OpenAI режет **все** запросы через `429 Too Many Requests` с `type: invalid_request_error` — **включая бесплатную модерацию**. Это не rate-limit моды, это аккаунт-уровневая блокировка. В ответе нет ни одного `x-ratelimit-*` хедера — это диагностический признак, что блок именно account-level, а не лимит модели. Лечится только депозитом.\n\n**Депозит — единоразово $5:**\n\n1. https://platform.openai.com/settings/organization/billing/overview → *Add payment details*\n2. Введи **`5`** в *Initial credit purchase* (минимум).\n3. ⚠️ **Снять галочку *Automatically add credits when your balance runs low***. По умолчанию она включена. Если оставить — карта будет молча докидывать $5 каждый раз когда баланс упадёт. Это главная ловушка для тех, кто хотел «только бесплатно».\n4. Подтвердить (банк может попросить 3DS).\n5. За 1-5 минут Tier поднимается `Free` → `Tier 1`, лимиты на moderation вырастают с 3 RPM до ~500 RPM.\n\n**Где следить за лимитами и расходом:**\n\n- **Rate limits per model** (RPM/RPD/TPM): https://platform.openai.com/settings/organization/limits — таблица с текущим тиром и лимитами по каждой модели. Полезно проверить после оплаты, что Tier действительно поднялся до 1.\n- **Usage (расход токенов и запросов):** https://platform.openai.com/usage — графики по дням/моделям, что именно сжигало баланс. Здесь же видно, что moderation идёт нулевой строкой.\n- **Billing & balance:** https://platform.openai.com/settings/organization/billing/overview — текущий остаток депозита, история платежей, настройки auto-recharge.\n\n**Стратегия использования $5:**\n\n- **Основной use-case (бесплатно):** модерация — `omni-moderation-latest` (text+image, 13 категорий) и `text-moderation-latest` (legacy text-only, 7 категорий) **не списываются с баланса**. $5 просто лежат бессрочно.\n- **Опционально (платно):** редкие вызовы `paid` chain через `gpt-5-mini` для случаев когда бесплатные провайдеры упёрлись или не справляются с качеством. При умеренном трафике $5 хватает на месяцы.\n- **Не подключать:** chat / embed / image_gen цепочки — у бесплатных провайдеров (Groq / Gemini / Z.ai / Cohere / Voyage / Cloudflare / Pollinations) лимиты на порядки больше.\n\n**Бесплатно после депозита:**\n\n| Модель | Что делает | Цена |\n|---|---|---|\n| `omni-moderation-latest` | Text + image moderation, 13 категорий, native scores | $0 / $0 |\n| `text-moderation-latest` | Legacy text-only, 7 категорий | $0 / $0 |\n\nВ neurogate реализованы как `kind: openai_moderation` в [config.py:118](../src/neurogate/config.py#L118), провайдер [`OpenAIModerationProvider`](../src/neurogate/providers.py#L3205). Обе уже в дефолтных цепочках `moderation` и `moderation_image`.\n\n**Платные модели — опциональный subset для `paid` chain (используя `OPENAI_API_KEY_PAID`):**\n\n| Модель | Цена in/out (per 1M) | Когда нужна |\n|---|---|---|\n| `gpt-5-mini` | $0.25 / $2.00 | Основной paid-fallback. Уже добавлен во вторую позицию `paid` после Claude Opus. |\n| `gpt-5-nano` | $0.05 / $0.40 | Если нужен ультра-дешёвый paid-fallback. На простых запросах хватает. |\n| `gpt-4.1-mini` | $0.40 / $1.60 | **1M контекст** — для длинных документов / RAG. Подключать только если упираешься в context window других моделей. |\n| `whisper-1` | $0.006/мин | STT-fallback после Groq Whisper. Только если делаешь транскрипцию серьёзных объёмов. |\n\n**Не брать:** `o3` (есть `o4-mini` в 4× дешевле), `dall-e-3` (устарел против `gpt-image-1`), `gpt-4o` / `gpt-4o-mini` (`gpt-5-mini`/`nano` дешевле и не хуже), `text-embedding-3-small/large` (Voyage даёт 200M tok permanent free на каждую модель — OpenAI embeddings подключать смысла мало), `gpt-image-1` (Kandinsky / YandexART лучше на фотореализме, см. отдельную заметку).\n\n**В конфиге:** OpenAI-нативный endpoint `https://api.openai.com/v1` — `kind: openai` для chat (`gpt-5-mini` и др.), `kind: openai_moderation` для модерации. Конкретные провайдеры см. в [config.yaml](../config.yaml) (`openai:moderation`, `openai:text-moderation`, `openai:gpt-5-mini`).\n\n## После получения ключей\n\n1. Скопировать: `cp .env.example .env`\n2. Вписать ключи в `.env` (пустые строки neurogate просто пропустит — провайдеры без ключа исключаются из цепочки)\n3. Запустить: `uv run neurogate`\n4. Проверить, какие провайдеры реально доступны: `curl -s -H \"Authorization: Bearer $TOKEN\" http://127.0.0.1:8765/v1/models`\n\nЕсли провайдер упирается в 429 — neurogate автоматически перейдёт к следующему. Если все упали — вернётся HTTP 502 `upstream_exhausted` (на free-тирах в сумме с 1 ключа это ~20-25k сообщений/сутки, так что до потолка надо постараться).\n\n## Если что-то не работает — как сообщить о баге\n\nБез следующих данных мы не можем отделить баг шлюза от проблемы провайдера / твоего соединения / клиента, и фикс затягивается на дни. Скинь всё одним сообщением:\n\n### Чек-лист (минимум)\n\n- [ ] **Что произошло** — одна-две фразы. Что должно было быть, что получилось вместо.\n- [ ] **Скриншот или видео** — обязательно. На скрине должно быть видно: само сообщение об ошибке, время, и (если применимо) URL/endpoint.\n- [ ] **Текст ошибки целиком** — копи-паст, не пересказ. Если приложение режет текст — скрин консоли / network tab из DevTools.\n- [ ] **Когда произошло** — точное время с часовым поясом (например, `2026-05-09 14:32 МСК`). Это нужно чтобы найти запись в логах.\n- [ ] **Что делал до ошибки** — последовательность действий. Например: «открыл Cursor → задал вопрос про код → пошёл стрим, на 3-й секунде оборвался». Или: «отправил длинный документ через Continue → сразу 502». **Воспроизводится повторно или один раз?**\n- [ ] **Тип соединения**:\n - Wi-Fi (домашний роутер / офис / публичный)\n - мобильный интернет (4G/5G)\n - смешанно (когда переключался с одного на другое — отметь)\n- [ ] **Провайдер/оператор**:\n - для мобильного: МТС / Мегафон / Билайн / Tele2 / Yota / другой\n - для домашнего: Ростелеком / МТС / Билайн / ТТК / Дом.ру / другой\n - если за VPN — **обязательно укажи**, какой VPN и какая страна выхода\n- [ ] **Город** (грубо — Москва / СПб / регион / зарубежье). Не для слежки, а потому что некоторые провайдеры блокируют upstream-эндпоинты только в части регионов.\n- [ ] **Какой клиент** и его версия:\n - Cursor / Claude Code / Codex / OpenCode / Continue / Cline / curl / собственный скрипт / браузер\n - версия (например, `Cursor 1.4.2`)\n- [ ] **Какая модель / chain** была запрошена — посмотри в настройках клиента, поле `model:`. Например: `auto`, `chat`, `deepseek:reasoner`, `paid`.\n\n### Желательно (если можешь)\n\n- **Request ID** — если ошибка вернулась с шлюза (HTTP-ответ), там в headers должен быть `x-request-id`. Скинь его — найдём конкретный запрос в логах за миллисекунды.\n- **Скрин Network tab** браузера или вывод `curl -v` — видны заголовки и точный путь.\n- **Размер промпта** — короткий вопрос или длинный документ на 50K токенов? Длинный context часто выявляет баги, которых нет на коротком.\n- **Stream или non-stream** — обычно стрим по умолчанию, но некоторые клиенты выключают.\n\n### Шаблон сообщения\n\nСкопируй и заполни:\n\n```\nЧто произошло:\nСкриншот/видео: (приложить файл)\nТекст ошибки:\n <вставить текст>\nКогда: 2026-05-09 HH:MM МСК\nЧто делал до:\nВоспроизводится: да / нет / иногда\nСоединение: Wi-Fi / мобильный\nОператор:\nVPN: нет / да (страна: ...)\nГород:\nКлиент: ... версия ...\nМодель/chain:\nRequest ID:\n```\n\n### Почему мы спрашиваем про оператора\n\nneurogate за собой держит 15+ upstream-провайдеров (Groq, Cerebras, SambaNova, Gemini, OpenRouter, DeepSeek, …). Часть из них **блокируется или режется на уровне отдельных российских операторов** — эта блокировка не от шлюза, а от твоего ISP. Признаки: connection reset / timeout / SSL handshake fail на конкретный домен. На разных операторах живут разные подмножества upstream'ов:\n\n- МТС иногда режет HuggingFace и часть Cloudflare-эндпоинтов\n- Мегафон блокирует часть Google IP-блоков → Gemini нестабильна\n- Ростелеком блокирует часть международного трафика по DPI\n- Из мобильного интернета бывает странный SNI-фильтр\n\nБез информации про оператора мы будем час крутить логи в поисках бага в коде, которого нет.\n"}, "a7a824919e98515328249c600c94e9c6f08f40f7": {"t": 1785765658.045603, "n": 32353, "h": "a84c619b02eb4458", "c": "# Как получить API-ключи провайдеров\n\nПошаговая инструкция для всех провайдеров из [config.yaml.example](../config.yaml.example) — где зарегистрироваться, где взять ключ, какая переменная в [.env.example](../.env.example), важные нюансы.\n\n**Минимум для старта**: достаточно 1-2 ключей — neurogate пропустит позиции, у которых ключ пустой, и пойдёт дальше по цепочке. Стартап-репорт на консоли подскажет, какие именно env-vars не заполнены и какие провайдеры это включит. Начать проще всего с **Groq** (самый быстрый onboarding) + **Gemini** (самая жирная квота на 1 ключ).\n\n## Free quota at a glance\n\nСводная таблица. **Колонка «Cap»** — главное:\n\n- 🟢 **effectively unlimited** — нет суточного/месячного потолка по запросам, ограничение только на RPM (или concurrency). Можно жечь хоть 24/7.\n- 🟡 **RPD-capped** — есть суточный потолок (счётчик ресетится 00:00 UTC, обычно).\n- 🔵 **monthly / token quota** — потолок по токенам или вызовам в месяц / в год; после исчерпания — paid либо ждать обновления.\n- 🟣 **anonymous / no key** — без ключа.\n\n| Cap | Провайдер | ENV-переменная | Лимит | Phone | Card | Особенность |\n|---|---|---|---|---|---|---|\n| 🟢 | **NVIDIA NIM** | `NVIDIA_API_KEY` | 40 RPM, без RPD | нет | нет | TTFB медленный — в `unlimited`/фоллбэк. |\n| 🟢 | **Z.ai** | `ZAI_API_KEY` | concurrency-only | нет | нет | GLM-4.5-Flash permanent free. China upstream. |\n| 🟢 | **Cerebras** | `CEREBRAS_API_KEY` | 5–30 RPM, без RPD | да | нет | Узкий выбор моделей, но потолка нет. Очень быстрый. |\n| 🟢 | **Mistral** | `MISTRAL_API_KEY` | ~4 RPM, без RPD | да | нет | Experiment plan. Узкий RPM, но без RPD. |\n| 🟡 | **SambaNova** | `SAMBANOVA_API_KEY` | 20 RPD **на модель** | нет | нет | 4 модели = 80 RPD на ключ. |\n| 🟡 | **Groq** | `GROQ_API_KEY` | 30 RPM, 1k–14.4k RPD | нет | нет | Самый быстрый onboarding, 300-1000+ т/с. Дубликаты ловят. |\n| 🟡 | **Gemini** | `GEMINI_API_KEY` | 10 RPM, 250-1500 RPD | нет | нет | Per-project: 2-3 GCP-проекта = ×N квота. Vision + tools. |\n| 🟡 | **OpenRouter (free)** | `OPENROUTER_API_KEY` | 20 RPM, 50 RPD (1000 с $10) | нет | нет\\* | Без $10 депозита — 50 RPD на всех. С депозитом — ×20. |\n| 🟡 | **Cloudflare Workers AI** | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` | 300 RPD (Llama 70B) | нет | нет | Edge inference, низкая латентность. Image gen бесплатно. |\n| 🟡 | **GitHub Models** | `GITHUB_MODELS_TOKEN` | 50–150 RPD | нет | нет | gpt-5-mini в free tier. Auth через GitHub PAT. |\n| 🟡 | **FreeTheAi** | `FREETHEAI_API_KEY` | 10 RPM, 1 concurrent | нет (Discord) | нет | **Требует daily Discord `/checkin`** — иначе 403. |\n| 🟡 | **OVHcloud** | — (anon) | 2 RPM на IP | нет | нет | EU-инфра, без ключа. |\n| 🔵 | **GigaChat (Sber)** | `GIGACHAT_AUTH_KEY` | Freemium quota / год | да (РФ) | нет | На наш опыт, чат слабоват, но **есть бесплатная Kandinsky image gen**. См. §11. |\n| 🔵 | **HuggingFace** | `HF_TOKEN` | ~$0.10/мес общий кредит | нет | нет | Кредит на paid sub-providers. PRO ($9/мес) = $2 кредит. |\n| 🔵 | **DeepSeek** | `DEEPSEEK_API_KEY` | 5M tok signup credits, дальше PAYG | да | нет | Off-peak 50–75% скидка. После кредитов — paid. |\n| 🔵 | **Alibaba DashScope Intl** | `DASHSCOPE_API_KEY` | 1M tok / model × 90 дней | да | да | Singapore region, 1M context на флагманах. |\n| 🔵 | **Cohere** | `COHERE_API_KEY` | 20 RPM, 1000 calls/мес | нет | нет | **Non-commercial only** на free tier (ToS). |\n| 🟣 | **LibreTranslate** | — (anon) | varies | нет | нет | Public mirrors. Перевод. |\n| 🟣 | **MyMemory** | `MYMEMORY_CONTACT_EMAIL` (опц) | 5k–50k chars/IP | нет | нет | Email повышает квоту 10×. |\n| 🟣 | **Edge TTS** | — (anon) | без лимита | нет | нет | Microsoft TTS, безлимит. |\n| 🟣 | **AIhorde** | — (anon) | community queue | нет | нет | Image gen, community inference. |\n\n\\* OpenRouter не требует карту для базового free tier, но $10 однократный депозит поднимает лимиты в 20 раз.\n\n**TL;DR.** Если нужен **24/7-бэкбон** — собирай цепочку из 🟢 (NVIDIA + Z.ai + Cerebras + Mistral): они не упираются в суточный потолок. Если нужен **широкий пул моделей** — добавляй 🟡 (Groq, Gemini, OpenRouter, GitHub) — они дают разнообразие, но ресетятся каждые 24ч. 🔵 — на конкретные ниши (Cohere для не-коммерческого RU, DeepSeek для signup-кредитов, GigaChat для Kandinsky).\n\n### Quick suggestion: какие 2-3 ключа добавить первыми\n\n- **Самый быстрый старт:** Groq (без верификаций) → мгновенный отклик и приличная квота.\n- **Долгий контекст / vision:** Gemini.\n- **Бэкбон без RPD-капа:** Cerebras (одно подтверждение телефона) или NVIDIA.\n- **Русский:** Yandex Alice (`yandex_foundation` kind) — на наш опыт лучше GigaChat для RU.\n- **Картинки бесплатно:** Cloudflare (FLUX/SDXL без RPD на image gen) или GigaChat (Kandinsky — фотореализм держит лучше FLUX).\n\n## Провайдеры\n\n### 1. Gemini (Google)\n\n- **Регистрация**: любой Google-аккаунт\n- **Получить ключ**: https://aistudio.google.com/apikey → *Create API key*\n- **ENV**: `GEMINI_API_KEY`\n- **Нюанс**: квота считается **per-project**, не per-key. Если завести 2-3 GCP-проекта на том же Google-аккаунте и сгенерить по ключу в каждом, получишь 2-3× квоту легально (TOS это разрешает — дубликаты запрещены только на уровне аккаунтов). Дополнительные ключи можно прописать как `GEMINI_API_KEY_2`, `GEMINI_API_KEY_3` и завести дубликаты провайдеров в `config.yaml` с разными `api_key_env`.\n\n### 2. Groq\n\n- **Регистрация**: https://console.groq.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Create API Key*\n- **ENV**: `GROQ_API_KEY`\n- **Нюанс**: самый быстрый провайдер в цепочке (300-1000+ токенов/сек). Free tier даёт 1000 RPD на `llama-3.3-70b-versatile` и 14400 RPD на `llama-3.1-8b-instant`. Дубликаты аккаунтов Groq ловит и банит оба — **не регистрируй второй аккаунт** с того же IP/телефона/карты.\n\n### 3. Cerebras\n\n- **Регистрация**: https://cloud.cerebras.ai (требует подтверждение телефона)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `CEREBRAS_API_KEY`\n- **Нюанс**: нет суточного лимита, но free tier сейчас узкий — реально работают только `qwen-3-235b-a22b-instruct-2507` (5 RPM) и `llama3.1-8b` (30 RPM). Более крупные модели (llama-3.3-70b, gpt-oss-120b) депрекейтнуты или paid-only.\n\n### 4. SambaNova\n\n- **Регистрация**: https://cloud.sambanova.ai (Google / email)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `SAMBANOVA_API_KEY`\n- **Нюанс**: 20 RPD **на каждую модель**, а не на аккаунт — 4 SambaNova-позиции в цепочке дают суммарно 80 RPD на один ключ. Лимит читается из заголовка `x-ratelimit-limit-requests-day` в ответе.\n\n### 5. NVIDIA NIM\n\n- **Регистрация**: https://build.nvidia.com (email, developer-программа)\n- **Получить ключ**: профиль справа вверху → *Get API Key* → выдают ключ вида `nvapi-...`\n- **ENV**: `NVIDIA_API_KEY`\n- **Нюанс**: формально **только для research/dev/test** — production TOS требует AI Enterprise license (~$4500/GPU/год). Для личного бота не критично. Нет суточного лимита, только RPM (40 на большинстве моделей).\n\n### 6. Z.ai (GLM)\n\n- **Регистрация**: https://z.ai (international) или https://open.bigmodel.cn (Китай — для аккаунтов из РФ/СНГ)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `ZAI_API_KEY`\n- **Нюанс**: `glm-4.5-flash` — **permanent free**, без RPD-лимита. В конфиге стоит `extra_body: { thinking: { type: disabled } }` — это принудительно отключает reasoning-режим (по умолчанию модель тратит токены на chain-of-thought, что режет скорость). Z.ai официально заявляет «no training on API data» — ок для чувствительного трафика.\n\n### 7. OpenRouter\n\n- **Регистрация**: https://openrouter.ai (Google / GitHub / MetaMask)\n- **Получить ключ**: https://openrouter.ai/keys → *Create Key*\n- **ENV**: `OPENROUTER_API_KEY`\n- **Нюанс**: `:free` модели делят глобальный пул 50 RPD на всех пользователей планеты — часто упирается в лимит к вечеру UTC. **Однократный депозит $10** поднимает RPD → 1000 на все `:free` модели (сами $10 не сгорают, лежат на балансе). Это единственное действие с 20× ROI на лимиты — см. «Платные расширения».\n\n### 8. Cloudflare Workers AI\n\n- **Регистрация**: https://dash.cloudflare.com (email)\n- **Получить ключ**: *My Profile* (правый верх) → *API Tokens* → *Create Token* → шаблон *Workers AI* (или custom: permission `Account → Workers AI → Read` + `Edit`)\n- **Получить Account ID**: на главной странице dashboard в правом сайдбаре — строка *Account ID*\n- **ENV**: `CLOUDFLARE_API_KEY` (токен) + `CLOUDFLARE_ACCOUNT_ID`\n- **Нюанс**: единственный провайдер, которому нужны **две** переменные. Account ID нельзя передать как env — Cloudflare вшивает его в URL запроса. 300 RPD на Llama 70B fp8-fast.\n\n### 9. GitHub Models\n\n- **Регистрация**: любой GitHub-аккаунт\n- **Получить токен**: https://github.com/settings/personal-access-tokens → *Generate new token (fine-grained)* → Account permissions → **Models: Read-only**\n- Классический PAT (`settings/tokens`) тоже работает, но fine-grained безопаснее — скоуп только на Models, не трогает репы.\n- **ENV**: `GITHUB_MODELS_TOKEN`\n- **Нюанс**: endpoint `https://models.github.ai/inference`, жёсткий потолок 8K токенов на запрос (input+output). Лимиты 50-150 RPD по моделям, считаются на токен.\n\n### 10. Mistral La Plateforme\n\n- **Регистрация**: https://console.mistral.ai (email + SMS-верификация)\n- **Получить ключ**: *API Keys*\n- **План**: выбрать **Experiment** (бесплатный) — даёт доступ к `mistral-large-latest` и остальным флагманам\n- **ENV**: `MISTRAL_API_KEY`\n- **Нюанс**: **обязательно зайти** в *Admin* → *Privacy* и **выключить опцию использования данных для обучения** — по умолчанию она включена. Без этого твои запросы уходят на training. Лимит ~4 RPM (заголовок `x-ratelimit-limit-req-minute`), не 60 как в старых доках.\n\n### 11. HuggingFace Inference Providers Router\n\n- **Регистрация**: любой HuggingFace-аккаунт https://huggingface.co\n- **Получить токен**: *Settings* → *Access Tokens* → *Create new token* → тип **Read**\n- **ENV**: `HF_TOKEN`\n- **Нюанс**: HF проксирует запросы к paid sub-providers (Novita, Cerebras, Together, …) через единый OpenAI-совместимый endpoint. Free tier даёт **~$0.10/мес общего кредита** на все sub-providers — этого хватает на эксперименты, не на постоянный трафик. **PRO-подписка ($9/мес)** даёт $2 кредита/мес. Модель указывается как `<repo>:<sub-provider>`, например `meta-llama/Llama-3.3-70B-Instruct:novita`.\n\n### 12. GigaChat (SberDevices)\n\n- **Регистрация**: https://developers.sber.ru/studio (требует подтверждённый аккаунт Сбера, телефон РФ)\n- **Получить ключ**: *Личное пространство* → *Мой GigaChat API* → *Получить новый ключ* → выдают `Authorization key` (это уже base64 от `client_id:client_secret`, готовый для `Basic`-авторизации)\n- **ENV**: `GIGACHAT_AUTH_KEY` (значение строки *Authorization key* как есть)\n- **Scope**: `GIGACHAT_API_PERS` — **Freemium** для физлиц с годовой квотой токенов (точные цифры Сбер периодически меняет — смотри актуальное на странице тарифа). По нашему опыту, на личное использование хватает с запасом.\n- **Чат vs картинки**: текстовые модели (GigaChat 2 / 2-Pro / 2-Max) на наш опыт **слабее даже отдельных Qwen / GLM** на русском, и заметно отстают от Yandex Alice. Но **бесплатная Kandinsky image gen** в этом же ключе — единственный способ получить русскоязычно-обученную text-to-image модель «из коробки», и она хорошо держит фотореализм когда в промпте есть «digital painting» / «oil painting» (где FLUX даёт «пластик»). Стоит держать в `image_gen` chain ради этого.\n- **Нюанс 1**: GigaChat отдаёт сертификат, подписанный *Russian Trusted Root CA* — стандартные системные truststore (на macOS/Linux вне РФ) его не знают. В конфиге для `kind: gigachat` стоит `verify_ssl: false`. Для прода — добавить Russian Trusted Sub CA в системный truststore.\n- **Нюанс 2**: авторизация двухступенчатая — провайдер обменивает `Authorization key` на короткоживущий OAuth access-token и кэширует его. Этот flow реализован внутри `kind: gigachat`, ничего вручную делать не нужно.\n- **Биллинг и расход**: https://developers.sber.ru/studio (раздел *Проекты* → *Лицевой счёт*).\n\n### 13. FreeTheAi\n\n- **Регистрация**: только через Discord. Зайти на сервер → https://discord.gg/secrets → команда `/signup` в канале #api-keys (https://discord.com/channels/1461555807731585158/1473159205048553705) → бот пришлёт ключ вида `sta_…` в DM. Если потерял — `/resetkey`.\n- **ENV**: `FREETHEAI_API_KEY`\n- **Лимиты**: 10 RPM + **1 concurrent** на ключ — последовательные вызовы, никакого parallel.\n- **Каталог**: ~16 252 алиасов. Префиксы: `cat/*` (gpt-5/claude/gemini frontier через прокси), `bbg/*` (DeepSeek/GLM/Kimi/MiniMax reasoning), `bbl/*` (Gemini/GPT non-reasoning), `or/*` (OpenRouter passthrough), `vhr/*` (image-gen scrap из Vheer), `img/gpt-image-2` (image gen+edit b64), `fth/*` (16k случайных HF моделей — почти всегда мусор). Не все алиасы реально работают — `glm/glm-5.1` (#1 в leaderboard) и `cat/gemini-3-1-pro` возвращают 400/timeout. Перед использованием — пробовать.\n- **⚠️ Главный нюанс — DAILY /checkin**: ключ блокируется **каждые 24 часа**. Чтобы разлочить — заходишь в Discord, в тот же канал #api-keys пишешь `/checkin`, бот возвращает «ключ активен на 24h». Без этого все запросы получают `HTTP 403 daily_checkin_required`.\n- **Автоматизировать /checkin НЕЛЬЗЯ**:\n 1. Discord ToS запрещает self-bot'ы (использование своего user-токена для скриптов) — ловят и банят аккаунт.\n 2. Обычные боты Discord не могут вызывать slash-команды других ботов (by design платформы).\n 3. Browser-automation поверх web-Discord — та же категория self-bot, ban guarantied.\n 4. FreeTheAi специально поставили /checkin как защиту от abuse — обходить = бан и от них тоже.\n- **Когда использовать**:\n - Ad-hoc-запросы для тестов (`model: \"freetheai:cat/gpt-5\"`) — 24h cooldown терпим, если не забыл сделать /checkin утром.\n - Не для продовых chains (без daily-checkin сервис ляжет).\n- **Bait-and-switch**: проверка identity показала, что `cat/claude-4-6-sonnet` отвечает «built by Tiny» — это НЕ Claude. `cat/gpt-5` идентифицируется как OpenAI, но без гарантий. `bbg/deepseek-v4-pro` выдаёт gibberish. Перед интеграцией каждой модели в логику — прогнать identity-test.\n- **Image-gen**: `vhr/*` модели возвращают URL'ы на `access.vheer.com` — это прокси на бесплатный Vheer.com сервис, файлы хранятся у них. `img/gpt-image-2` отдаёт b64 (~650KB на запрос) — единственная модель, поддерживающая edits.\n\n### 14. DeepSeek (direct API)\n\n**Пошагово (получить ключ):**\n\n1. Открой https://platform.deepseek.com → *Sign Up* (Google или email)\n2. Phone verify — российские номера принимает (МТС/Мегафон/Билайн/Tele2). Если по какой-то причине не принимает твой номер — попробуй через Google-аккаунт.\n3. После входа: левое меню → *API Keys* → *Create new API key* → дать любое имя → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается **один раз** — потом только regenerate.\n4. В `.env` локально и на проде:\n ```\n DEEPSEEK_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **5M токенов signup credits** + 7-14 дней без RPM-лимитов. Этого хватит на много экспериментов.\n- Модели: `deepseek-chat` (V3.2) и `deepseek-reasoner` (R1/R2).\n\n**Когда signup credits закончатся (опционально):**\n\n- $2 топ-ап ≈ 170 ₽ → месяцы PAYG-работы (`deepseek-chat` $0.28/$0.42 за 1M, `deepseek-reasoner` сопоставимо).\n- Off-peak 16:30–00:30 UTC — скидка 50% на V3, 75% на R1.\n- Prefix caching: cache hit в 4–10× дешевле miss. Структурируй промпты так, чтобы стабильный префикс (system + RAG) шёл первым, юзер-ввод — последним.\n- ⚠️ **Не включай auto-recharge** — карта будет молча докидывать каждый раз когда баланс падает.\n- ⚠️ Российские карты Visa/MC топ-ап **не примет**. Варианты: карта дружественной страны (Казахстан/Армения/Грузия), Wise/Revolut, виртуалка от иностранного fintech.\n\n**Подводные камни:**\n\n- **Privacy**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**. Если через шлюз идут чувствительные данные клиентов — либо удали DeepSeek из chain, либо ставь его последним позади cohere/openrouter/sambanova.\n- **Из России без VPN**: иногда нестабильные 5xx-ответы. Держи fallback в той же chain ниже — он сработает автоматически.\n\n**kind**: `deepseek`. Provider в config.yaml — простая запись с `model: deepseek-chat` или `model: deepseek-reasoner`. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 15. Alibaba DashScope International (Qwen)\n\n**⚠️ Самый муторный из четырёх. Делай утром, на это уйдёт 20-30 минут.**\n\n**Пошагово (получить ключ):**\n\n1. Открой https://accountclient.alibabacloud.com/intl → *Sign Up*\n2. **Регион — обязательно Singapore.** US/HK/EU/China версии free quota НЕ дают. Если на этапе onboarding спрашивает регион — выбирай Singapore. Если уже зарегистрировался в другом регионе — придётся завести отдельный аккаунт.\n3. Phone verify (российские номера принимает).\n4. **Карта обязательна** — для Real-name Verification. С карты ничего не списывается, но без привязки free quota не активируется.\n - ⚠️ Российские карты Visa/MC **не пройдут**.\n - Варианты:\n - Карта дружественной страны (Казахстан / Армения / Грузия)\n - Wise / Revolut если есть\n - Виртуальная карта от иностранного fintech (Pyypl, Genome, etc.)\n5. После Real-name Verification → открыть https://bailian.console.alibabacloud.com (Model Studio, регион Singapore)\n6. Левое меню → *API-KEY* → *Create* → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается полностью один раз.\n7. В `.env` локально и на проде:\n ```\n DASHSCOPE_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **1M токенов на каждую модель** × **90 дней** с момента активации. Десятки моделей в каталоге → десятки миллионов токенов суммарно.\n- Флагманы: `qwen3.6-plus` (топ-3 на OpenRouter trafficу, 1M context, всегда-вкл CoT), `qwen3.6-max-preview`, `qwen3-coder-480b-a35b-instruct`, `qwen3-next-80b-a3b-instruct/thinking`, `qwen3-vl-plus`.\n\n**После 90 дней**: paid-only. Поставь напоминание `/schedule` за неделю до истечения — посмотрим использование и решим продлять или уйти на DashScope-paid.\n\n**Подводные камни:**\n\n- **Регион Singapore ОБЯЗАТЕЛЬНО**. Endpoint в config.py уже забит: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. Если у тебя аккаунт в другом регионе — ключ будет работать, но free quota = 0.\n- **Privacy**: Alibaba явно заявляет «will never use your data for model training», данные в Сингапуре → **можно использовать с PII** в отличие от китайского endpoint DeepSeek.\n- **Real-name Verification может зависнуть на сутки** — в первый раз. Если статус «pending» больше 24ч — открыть тикет в support.\n\n**kind**: `dashscope`. Provider в config.yaml — простая запись с `model: qwen3.6-plus` или другой моделью. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 16. Cohere (Command-A / c4ai-aya — для русского)\n\n- **Регистрация**: https://dashboard.cohere.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Generate Trial Key*\n- **ENV**: `COHERE_API_KEY`\n- **Free tier**: 20 RPM на модель, 1000 calls/месяц (≈33 RPD safe-floor).\n- **Модели**: `c4ai-aya-expanse-32b/8b` — multilingual, **сильный русский**. `c4ai-aya-vision-32b/8b` — vision. `command-a-03-2025` — флагман общего назначения. `command-a-reasoning-08-2025` — reasoning. `command-a-translate-08-2025` — translation.\n- **ToS**: free tier — **non-commercial only**. Для open-source / личных проектов ок. Если кто-то форкнет коммерчески — нарушение. Помечай в README.\n- **Особенность реализации**: Cohere v2 /chat — собственный response shape (`{message: {content: [{type:'text', text:...}]}}`), не OpenAI-compat. Streaming эмулируется одним SSE chunk'ом из полного ответа (Cohere v2 SSE имеет свой формат, дешевле fake-stream чем переводить).\n- **kind**: `cohere_chat` (для chat) или `cohere` (для translate-only). Эмбеддинги отдельно — `cohere_embed`.\n\n### 17. OVHcloud AI Endpoints (anonymous, без ключа)\n\n- **Регистрация**: НЕ ТРЕБУЕТСЯ. Endpoint анонимный.\n- **ENV**: НЕТ. В config.yaml запись `kind: ovhcloud` без `api_key_env`.\n- **Endpoint**: `https://oai.endpoints.kepler.ai.cloud.ovh.net/v1` — OpenAI-совместимый.\n- **Лимит**: 2 RPM **на IP** на модель. Без ключа — прозрачный rate-limit, при превышении 429.\n- **Каталог**: 40+ open-моделей, EU-host (Франция/Германия). Llama 3.x, Mistral, Qwen, Mixtral, gpt-oss-120b, и т.д.\n- **Когда использовать**: исключительно как **deep fallback / last-resort** в конце chain — «лучше отдать что-то, чем 503». В основной chain ставить нет смысла из-за 2 RPM на IP.\n- **Реализация**: `OpenAICompatProvider` пропускает `Authorization` header при пустом `api_key` (см. providers.py — изменение из этого PR).\n- **kind**: `ovhcloud`.\n\n## Платные расширения (опционально)\n\nНиже — одноразовые или recurring платные действия с непропорционально большим профитом на лимиты.\n\n### OpenRouter — $10 депозит → 20× квоты\n\n**Что делает**: однократный пополнение на $10 поднимает 50 RPD → **1000 RPD** на все `:free` модели (DeepSeek R1/V3.2, Llama 4 Maverick/Scout, Qwen3 235B, GLM-5 `:free`, Kimi K2 `:free`, MiniMax M2 `:free`, Qwen3-Coder 480B `:free`).\n\n**Как**: *Settings* → *Credits* → пополнить любую сумму ≥ $10. Сами $10 остаются на балансе и тратятся только если ты явно вызовешь платную модель. Для `:free` — это просто unlock лимита.\n\n**После депозита**: в `config.yaml` обновить `rpd: 50` → `rpd: 1000` на всех позициях с `kind: openrouter`.\n\n### xAI Grok — $25 signup + $150/мес recurring\n\n- **Регистрация**: https://console.x.ai (phone verify)\n- **Signup**: $25 кредитов на 30 дней\n- **Data-sharing program**: opt-in на sharing → $150/мес recurring (обновляется пока включено, требует минимум $5 spend за период)\n- **Зачем**: Grok 4.1 Fast — уникальный **2M context window**, никто больше такого не даёт\n- **В конфиг**: нужен `kind: xai` провайдер (OpenAI-compat endpoint `https://api.x.ai/v1`). **Пока не реализован** в neurogate.\n\n### Alibaba Qwen Singapore — 1M токенов × десятки моделей на 90 дней\n\n- **Регистрация**: https://accountclient.alibabacloud.com/intl (требует телефон и карту, +966 работает)\n- **Регион критичен**: Singapore. Endpoint `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. US/HK/EU версии free quota не дают.\n- **Квота**: 1M токенов **на каждую модель** на 90 дней → десятки моделей × 1M = десятки миллионов токенов суммарно. Флагманы: `qwen3-max`, `qwen-plus`, `qwen-flash`, `qwen3-coder-plus`, `qwen3.5-plus`.\n- **Privacy**: официально «will never use your data for model training», данные в Сингапуре.\n- **После 90 дней**: paid-only.\n- **В конфиг**: `kind: dashscope` — нативно поддерживается, см. секцию #15 выше для деталей.\n\n### DeepSeek direct — 5M signup credits + off-peak 50-75%\n\n- **Регистрация**: https://platform.deepseek.com (phone verify)\n- **Signup**: 5M токенов + 7-14 дней без rate limits\n- **Off-peak**: 16:30-00:30 UTC — **50% скидка на V3, 75% на R1**. Годится для batch-задач, не для realtime-чата.\n- **Privacy-блокер**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**.\n- **В конфиг**: `kind: deepseek` — нативно поддерживается, см. секцию #14 выше для деталей.\n\n### Anthropic Claude direct — $5 signup\n\n- **Регистрация**: https://console.anthropic.com (phone verify)\n- **Signup**: $5 кредитов на 30 дней после phone verify\n- **Зачем**: единственный способ добавить frontier Claude Sonnet/Opus в цепочку без Bedrock/Databricks\n- **Нюанс**: Anthropic API не OpenAI-compat — нужен отдельный `kind: anthropic`. В neurogate **пока не реализован**.\n\n### OpenAI direct — единоразово $5 ради бесплатной модерации (text + image)\n\n**TL;DR — зачем подключать OpenAI вообще:** ради **бесплатной модерации**. Текстовая (`text-moderation-latest`) и multimodal text+image (`omni-moderation-latest`) у OpenAI **бесплатны навсегда** и качественнее всех альтернатив. Платные модели ($0.05–$10 per 1M токенов) — опционально, если иногда понадобится высокое качество в `paid` chain. **На бесплатные chat / embed / image-gen цепочки OpenAI подключать не нужно** — у Groq / Gemini / Z.ai лимиты щедрее и без депозита.\n\n**Регистрация:**\n\n- https://platform.openai.com (Google / Microsoft / email)\n- https://platform.openai.com/api-keys → *Create new secret key*\n- **ENV**: `OPENAI_API_KEY` (для бесплатной модерации) и опционально `OPENAI_API_KEY_PAID` (для paid-моделей; можно тот же ключ — разделение нужно лишь чтобы случайно не сжечь baseline-баланс)\n\n**Критично — почему без $5 ничего не работает:**\n\nНа Free tier (без привязанной карты) OpenAI режет **все** запросы через `429 Too Many Requests` с `type: invalid_request_error` — **включая бесплатную модерацию**. Это не rate-limit моды, это аккаунт-уровневая блокировка. В ответе нет ни одного `x-ratelimit-*` хедера — это диагностический признак, что блок именно account-level, а не лимит модели. Лечится только депозитом.\n\n**Депозит — единоразово $5:**\n\n1. https://platform.openai.com/settings/organization/billing/overview → *Add payment details*\n2. Введи **`5`** в *Initial credit purchase* (минимум).\n3. ⚠️ **Снять галочку *Automatically add credits when your balance runs low***. По умолчанию она включена. Если оставить — карта будет молча докидывать $5 каждый раз когда баланс упадёт. Это главная ловушка для тех, кто хотел «только бесплатно».\n4. Подтвердить (банк может попросить 3DS).\n5. За 1-5 минут Tier поднимается `Free` → `Tier 1`, лимиты на moderation вырастают с 3 RPM до ~500 RPM.\n\n**Где следить за лимитами и расходом:**\n\n- **Rate limits per model** (RPM/RPD/TPM): https://platform.openai.com/settings/organization/limits — таблица с текущим тиром и лимитами по каждой модели. Полезно проверить после оплаты, что Tier действительно поднялся до 1.\n- **Usage (расход токенов и запросов):** https://platform.openai.com/usage — графики по дням/моделям, что именно сжигало баланс. Здесь же видно, что moderation идёт нулевой строкой.\n- **Billing & balance:** https://platform.openai.com/settings/organization/billing/overview — текущий остаток депозита, история платежей, настройки auto-recharge.\n\n**Стратегия использования $5:**\n\n- **Основной use-case (бесплатно):** модерация — `omni-moderation-latest` (text+image, 13 категорий) и `text-moderation-latest` (legacy text-only, 7 категорий) **не списываются с баланса**. $5 просто лежат бессрочно.\n- **Опционально (платно):** редкие вызовы `paid` chain через `gpt-5-mini` для случаев когда бесплатные провайдеры упёрлись или не справляются с качеством. При умеренном трафике $5 хватает на месяцы.\n- **Не подключать:** chat / embed / image_gen цепочки — у бесплатных провайдеров (Groq / Gemini / Z.ai / Cohere / Voyage / Cloudflare / Pollinations) лимиты на порядки больше.\n\n**Бесплатно после депозита:**\n\n| Модель | Что делает | Цена |\n|---|---|---|\n| `omni-moderation-latest` | Text + image moderation, 13 категорий, native scores | $0 / $0 |\n| `text-moderation-latest` | Legacy text-only, 7 категорий | $0 / $0 |\n\nВ neurogate реализованы как `kind: openai_moderation` в [config.py:118](../src/neurogate/config.py#L118), провайдер [`OpenAIModerationProvider`](../src/neurogate/providers.py#L3205). Обе уже в дефолтных цепочках `moderation` и `moderation_image`.\n\n**Платные модели — опциональный subset для `paid` chain (используя `OPENAI_API_KEY_PAID`):**\n\n| Модель | Цена in/out (per 1M) | Когда нужна |\n|---|---|---|\n| `gpt-5-mini` | $0.25 / $2.00 | Основной paid-fallback. Уже добавлен во вторую позицию `paid` после Claude Opus. |\n| `gpt-5-nano` | $0.05 / $0.40 | Если нужен ультра-дешёвый paid-fallback. На простых запросах хватает. |\n| `gpt-4.1-mini` | $0.40 / $1.60 | **1M контекст** — для длинных документов / RAG. Подключать только если упираешься в context window других моделей. |\n| `whisper-1` | $0.006/мин | STT-fallback после Groq Whisper. Только если делаешь транскрипцию серьёзных объёмов. |\n\n**Не брать:** `o3` (есть `o4-mini` в 4× дешевле), `dall-e-3` (устарел против `gpt-image-1`), `gpt-4o` / `gpt-4o-mini` (`gpt-5-mini`/`nano` дешевле и не хуже), `text-embedding-3-small/large` (Voyage даёт 200M tok permanent free на каждую модель — OpenAI embeddings подключать смысла мало), `gpt-image-1` (Kandinsky / YandexART лучше на фотореализме, см. отдельную заметку).\n\n**В конфиге:** OpenAI-нативный endpoint `https://api.openai.com/v1` — `kind: openai` для chat (`gpt-5-mini` и др.), `kind: openai_moderation` для модерации. Конкретные провайдеры см. в [config.yaml](../config.yaml) (`openai:moderation`, `openai:text-moderation`, `openai:gpt-5-mini`).\n\n## После получения ключей\n\n1. Скопировать: `cp .env.example .env`\n2. Вписать ключи в `.env` (пустые строки neurogate просто пропустит — провайдеры без ключа исключаются из цепочки)\n3. Запустить: `uv run neurogate`\n4. Проверить, какие провайдеры реально доступны: `curl -s -H \"Authorization: Bearer $TOKEN\" http://127.0.0.1:8765/v1/models`\n\nЕсли провайдер упирается в 429 — neurogate автоматически перейдёт к следующему. Если все упали — вернётся HTTP 502 `upstream_exhausted` (на free-тирах в сумме с 1 ключа это ~20-25k сообщений/сутки, так что до потолка надо постараться).\n\n## Если что-то не работает — как сообщить о баге\n\nБез следующих данных мы не можем отделить баг шлюза от проблемы провайдера / твоего соединения / клиента, и фикс затягивается на дни. Скинь всё одним сообщением:\n\n### Чек-лист (минимум)\n\n- [ ] **Что произошло** — одна-две фразы. Что должно было быть, что получилось вместо.\n- [ ] **Скриншот или видео** — обязательно. На скрине должно быть видно: само сообщение об ошибке, время, и (если применимо) URL/endpoint.\n- [ ] **Текст ошибки целиком** — копи-паст, не пересказ. Если приложение режет текст — скрин консоли / network tab из DevTools.\n- [ ] **Когда произошло** — точное время с часовым поясом (например, `2026-05-09 14:32 МСК`). Это нужно чтобы найти запись в логах.\n- [ ] **Что делал до ошибки** — последовательность действий. Например: «открыл Cursor → задал вопрос про код → пошёл стрим, на 3-й секунде оборвался». Или: «отправил длинный документ через Continue → сразу 502». **Воспроизводится повторно или один раз?**\n- [ ] **Тип соединения**:\n - Wi-Fi (домашний роутер / офис / публичный)\n - мобильный интернет (4G/5G)\n - смешанно (когда переключался с одного на другое — отметь)\n- [ ] **Провайдер/оператор**:\n - для мобильного: МТС / Мегафон / Билайн / Tele2 / Yota / другой\n - для домашнего: Ростелеком / МТС / Билайн / ТТК / Дом.ру / другой\n - если за VPN — **обязательно укажи**, какой VPN и какая страна выхода\n- [ ] **Город** (грубо — Москва / СПб / регион / зарубежье). Не для слежки, а потому что некоторые провайдеры блокируют upstream-эндпоинты только в части регионов.\n- [ ] **Какой клиент** и его версия:\n - Cursor / Claude Code / Continue / Cline / Aider / curl / собственный скрипт / браузер\n - версия (например, `Cursor 1.4.2`)\n- [ ] **Какая модель / chain** была запрошена — посмотри в настройках клиента, поле `model:`. Например: `auto`, `chat`, `deepseek:reasoner`, `paid`.\n\n### Желательно (если можешь)\n\n- **Request ID** — если ошибка вернулась с шлюза (HTTP-ответ), там в headers должен быть `x-request-id`. Скинь его — найдём конкретный запрос в логах за миллисекунды.\n- **Скрин Network tab** браузера или вывод `curl -v` — видны заголовки и точный путь.\n- **Размер промпта** — короткий вопрос или длинный документ на 50K токенов? Длинный context часто выявляет баги, которых нет на коротком.\n- **Stream или non-stream** — обычно стрим по умолчанию, но некоторые клиенты выключают.\n\n### Шаблон сообщения\n\nСкопируй и заполни:\n\n```\nЧто произошло:\nСкриншот/видео: (приложить файл)\nТекст ошибки:\n <вставить текст>\nКогда: 2026-05-09 HH:MM МСК\nЧто делал до:\nВоспроизводится: да / нет / иногда\nСоединение: Wi-Fi / мобильный\nОператор:\nVPN: нет / да (страна: ...)\nГород:\nКлиент: ... версия ...\nМодель/chain:\nRequest ID:\n```\n\n### Почему мы спрашиваем про оператора\n\nneurogate за собой держит 15+ upstream-провайдеров (Groq, Cerebras, SambaNova, Gemini, OpenRouter, DeepSeek, …). Часть из них **блокируется или режется на уровне отдельных российских операторов** — эта блокировка не от шлюза, а от твоего ISP. Признаки: connection reset / timeout / SSL handshake fail на конкретный домен. На разных операторах живут разные подмножества upstream'ов:\n\n- МТС иногда режет HuggingFace и часть Cloudflare-эндпоинтов\n- Мегафон блокирует часть Google IP-блоков → Gemini нестабильна\n- Ростелеком блокирует часть международного трафика по DPI\n- Из мобильного интернета бывает странный SNI-фильтр\n\nБез информации про оператора мы будем час крутить логи в поисках бага в коде, которого нет.\n"}, "fb993b0a48ca1bd23804f243b9fc99936a536497": {"t": 1785765659.8732994, "n": 32333, "h": "f8645dc3f55aab87", "c": "# Как получить API-ключи провайдеров\n\nПошаговая инструкция для всех провайдеров из [config.yaml.example](../config.yaml.example) — где зарегистрироваться, где взять ключ, какая переменная в [.env.example](../.env.example), важные нюансы.\n\n**Минимум для старта**: достаточно 1-2 ключей — llmgate пропустит позиции, у которых ключ пустой, и пойдёт дальше по цепочке. Стартап-репорт на консоли подскажет, какие именно env-vars не заполнены и какие провайдеры это включит. Начать проще всего с **Groq** (самый быстрый onboarding) + **Gemini** (самая жирная квота на 1 ключ).\n\n## Free quota at a glance\n\nСводная таблица. **Колонка «Cap»** — главное:\n\n- 🟢 **effectively unlimited** — нет суточного/месячного потолка по запросам, ограничение только на RPM (или concurrency). Можно жечь хоть 24/7.\n- 🟡 **RPD-capped** — есть суточный потолок (счётчик ресетится 00:00 UTC, обычно).\n- 🔵 **monthly / token quota** — потолок по токенам или вызовам в месяц / в год; после исчерпания — paid либо ждать обновления.\n- 🟣 **anonymous / no key** — без ключа.\n\n| Cap | Провайдер | ENV-переменная | Лимит | Phone | Card | Особенность |\n|---|---|---|---|---|---|---|\n| 🟢 | **NVIDIA NIM** | `NVIDIA_API_KEY` | 40 RPM, без RPD | нет | нет | TTFB медленный — в `unlimited`/фоллбэк. |\n| 🟢 | **Z.ai** | `ZAI_API_KEY` | concurrency-only | нет | нет | GLM-4.5-Flash permanent free. China upstream. |\n| 🟢 | **Cerebras** | `CEREBRAS_API_KEY` | 5–30 RPM, без RPD | да | нет | Узкий выбор моделей, но потолка нет. Очень быстрый. |\n| 🟢 | **Mistral** | `MISTRAL_API_KEY` | ~4 RPM, без RPD | да | нет | Experiment plan. Узкий RPM, но без RPD. |\n| 🟡 | **SambaNova** | `SAMBANOVA_API_KEY` | 20 RPD **на модель** | нет | нет | 4 модели = 80 RPD на ключ. |\n| 🟡 | **Groq** | `GROQ_API_KEY` | 30 RPM, 1k–14.4k RPD | нет | нет | Самый быстрый onboarding, 300-1000+ т/с. Дубликаты ловят. |\n| 🟡 | **Gemini** | `GEMINI_API_KEY` | 10 RPM, 250-1500 RPD | нет | нет | Per-project: 2-3 GCP-проекта = ×N квота. Vision + tools. |\n| 🟡 | **OpenRouter (free)** | `OPENROUTER_API_KEY` | 20 RPM, 50 RPD (1000 с $10) | нет | нет\\* | Без $10 депозита — 50 RPD на всех. С депозитом — ×20. |\n| 🟡 | **Cloudflare Workers AI** | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` | 300 RPD (Llama 70B) | нет | нет | Edge inference, низкая латентность. Image gen бесплатно. |\n| 🟡 | **GitHub Models** | `GITHUB_MODELS_TOKEN` | 50–150 RPD | нет | нет | gpt-5-mini в free tier. Auth через GitHub PAT. |\n| 🟡 | **FreeTheAi** | `FREETHEAI_API_KEY` | 10 RPM, 1 concurrent | нет (Discord) | нет | **Требует daily Discord `/checkin`** — иначе 403. |\n| 🟡 | **OVHcloud** | — (anon) | 2 RPM на IP | нет | нет | EU-инфра, без ключа. |\n| 🔵 | **GigaChat (Sber)** | `GIGACHAT_AUTH_KEY` | Freemium quota / год | да (РФ) | нет | На наш опыт, чат слабоват, но **есть бесплатная Kandinsky image gen**. См. §11. |\n| 🔵 | **HuggingFace** | `HF_TOKEN` | ~$0.10/мес общий кредит | нет | нет | Кредит на paid sub-providers. PRO ($9/мес) = $2 кредит. |\n| 🔵 | **DeepSeek** | `DEEPSEEK_API_KEY` | 5M tok signup credits, дальше PAYG | да | нет | Off-peak 50–75% скидка. После кредитов — paid. |\n| 🔵 | **Alibaba DashScope Intl** | `DASHSCOPE_API_KEY` | 1M tok / model × 90 дней | да | да | Singapore region, 1M context на флагманах. |\n| 🔵 | **Cohere** | `COHERE_API_KEY` | 20 RPM, 1000 calls/мес | нет | нет | **Non-commercial only** на free tier (ToS). |\n| 🟣 | **LibreTranslate** | — (anon) | varies | нет | нет | Public mirrors. Перевод. |\n| 🟣 | **MyMemory** | `MYMEMORY_CONTACT_EMAIL` (опц) | 5k–50k chars/IP | нет | нет | Email повышает квоту 10×. |\n| 🟣 | **Edge TTS** | — (anon) | без лимита | нет | нет | Microsoft TTS, безлимит. |\n| 🟣 | **AIhorde** | — (anon) | community queue | нет | нет | Image gen, community inference. |\n\n\\* OpenRouter не требует карту для базового free tier, но $10 однократный депозит поднимает лимиты в 20 раз.\n\n**TL;DR.** Если нужен **24/7-бэкбон** — собирай цепочку из 🟢 (NVIDIA + Z.ai + Cerebras + Mistral): они не упираются в суточный потолок. Если нужен **широкий пул моделей** — добавляй 🟡 (Groq, Gemini, OpenRouter, GitHub) — они дают разнообразие, но ресетятся каждые 24ч. 🔵 — на конкретные ниши (Cohere для не-коммерческого RU, DeepSeek для signup-кредитов, GigaChat для Kandinsky).\n\n### Quick suggestion: какие 2-3 ключа добавить первыми\n\n- **Самый быстрый старт:** Groq (без верификаций) → мгновенный отклик и приличная квота.\n- **Долгий контекст / vision:** Gemini.\n- **Бэкбон без RPD-капа:** Cerebras (одно подтверждение телефона) или NVIDIA.\n- **Русский:** Yandex Alice (`yandex_foundation` kind) — на наш опыт лучше GigaChat для RU.\n- **Картинки бесплатно:** Cloudflare (FLUX/SDXL без RPD на image gen) или GigaChat (Kandinsky — фотореализм держит лучше FLUX).\n\n## Провайдеры\n\n### 1. Gemini (Google)\n\n- **Регистрация**: любой Google-аккаунт\n- **Получить ключ**: https://aistudio.google.com/apikey → *Create API key*\n- **ENV**: `GEMINI_API_KEY`\n- **Нюанс**: квота считается **per-project**, не per-key. Если завести 2-3 GCP-проекта на том же Google-аккаунте и сгенерить по ключу в каждом, получишь 2-3× квоту легально (TOS это разрешает — дубликаты запрещены только на уровне аккаунтов). Дополнительные ключи можно прописать как `GEMINI_API_KEY_2`, `GEMINI_API_KEY_3` и завести дубликаты провайдеров в `config.yaml` с разными `api_key_env`.\n\n### 2. Groq\n\n- **Регистрация**: https://console.groq.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Create API Key*\n- **ENV**: `GROQ_API_KEY`\n- **Нюанс**: самый быстрый провайдер в цепочке (300-1000+ токенов/сек). Free tier даёт 1000 RPD на `llama-3.3-70b-versatile` и 14400 RPD на `llama-3.1-8b-instant`. Дубликаты аккаунтов Groq ловит и банит оба — **не регистрируй второй аккаунт** с того же IP/телефона/карты.\n\n### 3. Cerebras\n\n- **Регистрация**: https://cloud.cerebras.ai (требует подтверждение телефона)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `CEREBRAS_API_KEY`\n- **Нюанс**: нет суточного лимита, но free tier сейчас узкий — реально работают только `qwen-3-235b-a22b-instruct-2507` (5 RPM) и `llama3.1-8b` (30 RPM). Более крупные модели (llama-3.3-70b, gpt-oss-120b) депрекейтнуты или paid-only.\n\n### 4. SambaNova\n\n- **Регистрация**: https://cloud.sambanova.ai (Google / email)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `SAMBANOVA_API_KEY`\n- **Нюанс**: 20 RPD **на каждую модель**, а не на аккаунт — 4 SambaNova-позиции в цепочке дают суммарно 80 RPD на один ключ. Лимит читается из заголовка `x-ratelimit-limit-requests-day` в ответе.\n\n### 5. NVIDIA NIM\n\n- **Регистрация**: https://build.nvidia.com (email, developer-программа)\n- **Получить ключ**: профиль справа вверху → *Get API Key* → выдают ключ вида `nvapi-...`\n- **ENV**: `NVIDIA_API_KEY`\n- **Нюанс**: формально **только для research/dev/test** — production TOS требует AI Enterprise license (~$4500/GPU/год). Для личного бота не критично. Нет суточного лимита, только RPM (40 на большинстве моделей).\n\n### 6. Z.ai (GLM)\n\n- **Регистрация**: https://z.ai (international) или https://open.bigmodel.cn (Китай — для аккаунтов из РФ/СНГ)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `ZAI_API_KEY`\n- **Нюанс**: `glm-4.5-flash` — **permanent free**, без RPD-лимита. В конфиге стоит `extra_body: { thinking: { type: disabled } }` — это принудительно отключает reasoning-режим (по умолчанию модель тратит токены на chain-of-thought, что режет скорость). Z.ai официально заявляет «no training on API data» — ок для чувствительного трафика.\n\n### 7. OpenRouter\n\n- **Регистрация**: https://openrouter.ai (Google / GitHub / MetaMask)\n- **Получить ключ**: https://openrouter.ai/keys → *Create Key*\n- **ENV**: `OPENROUTER_API_KEY`\n- **Нюанс**: `:free` модели делят глобальный пул 50 RPD на всех пользователей планеты — часто упирается в лимит к вечеру UTC. **Однократный депозит $10** поднимает RPD → 1000 на все `:free` модели (сами $10 не сгорают, лежат на балансе). Это единственное действие с 20× ROI на лимиты — см. «Платные расширения».\n\n### 8. Cloudflare Workers AI\n\n- **Регистрация**: https://dash.cloudflare.com (email)\n- **Получить ключ**: *My Profile* (правый верх) → *API Tokens* → *Create Token* → шаблон *Workers AI* (или custom: permission `Account → Workers AI → Read` + `Edit`)\n- **Получить Account ID**: на главной странице dashboard в правом сайдбаре — строка *Account ID*\n- **ENV**: `CLOUDFLARE_API_KEY` (токен) + `CLOUDFLARE_ACCOUNT_ID`\n- **Нюанс**: единственный провайдер, которому нужны **две** переменные. Account ID нельзя передать как env — Cloudflare вшивает его в URL запроса. 300 RPD на Llama 70B fp8-fast.\n\n### 9. GitHub Models\n\n- **Регистрация**: любой GitHub-аккаунт\n- **Получить токен**: https://github.com/settings/personal-access-tokens → *Generate new token (fine-grained)* → Account permissions → **Models: Read-only**\n- Классический PAT (`settings/tokens`) тоже работает, но fine-grained безопаснее — скоуп только на Models, не трогает репы.\n- **ENV**: `GITHUB_MODELS_TOKEN`\n- **Нюанс**: endpoint `https://models.github.ai/inference`, жёсткий потолок 8K токенов на запрос (input+output). Лимиты 50-150 RPD по моделям, считаются на токен.\n\n### 10. Mistral La Plateforme\n\n- **Регистрация**: https://console.mistral.ai (email + SMS-верификация)\n- **Получить ключ**: *API Keys*\n- **План**: выбрать **Experiment** (бесплатный) — даёт доступ к `mistral-large-latest` и остальным флагманам\n- **ENV**: `MISTRAL_API_KEY`\n- **Нюанс**: **обязательно зайти** в *Admin* → *Privacy* и **выключить опцию использования данных для обучения** — по умолчанию она включена. Без этого твои запросы уходят на training. Лимит ~4 RPM (заголовок `x-ratelimit-limit-req-minute`), не 60 как в старых доках.\n\n### 11. HuggingFace Inference Providers Router\n\n- **Регистрация**: любой HuggingFace-аккаунт https://huggingface.co\n- **Получить токен**: *Settings* → *Access Tokens* → *Create new token* → тип **Read**\n- **ENV**: `HF_TOKEN`\n- **Нюанс**: HF проксирует запросы к paid sub-providers (Novita, Cerebras, Together, …) через единый OpenAI-совместимый endpoint. Free tier даёт **~$0.10/мес общего кредита** на все sub-providers — этого хватает на эксперименты, не на постоянный трафик. **PRO-подписка ($9/мес)** даёт $2 кредита/мес. Модель указывается как `<repo>:<sub-provider>`, например `meta-llama/Llama-3.3-70B-Instruct:novita`.\n\n### 12. GigaChat (SberDevices)\n\n- **Регистрация**: https://developers.sber.ru/studio (требует подтверждённый аккаунт Сбера, телефон РФ)\n- **Получить ключ**: *Личное пространство* → *Мой GigaChat API* → *Получить новый ключ* → выдают `Authorization key` (это уже base64 от `client_id:client_secret`, готовый для `Basic`-авторизации)\n- **ENV**: `GIGACHAT_AUTH_KEY` (значение строки *Authorization key* как есть)\n- **Scope**: `GIGACHAT_API_PERS` — **Freemium** для физлиц с годовой квотой токенов (точные цифры Сбер периодически меняет — смотри актуальное на странице тарифа). По нашему опыту, на личное использование хватает с запасом.\n- **Чат vs картинки**: текстовые модели (GigaChat 2 / 2-Pro / 2-Max) на наш опыт **слабее даже отдельных Qwen / GLM** на русском, и заметно отстают от Yandex Alice. Но **бесплатная Kandinsky image gen** в этом же ключе — единственный способ получить русскоязычно-обученную text-to-image модель «из коробки», и она хорошо держит фотореализм когда в промпте есть «digital painting» / «oil painting» (где FLUX даёт «пластик»). Стоит держать в `image_gen` chain ради этого.\n- **Нюанс 1**: GigaChat отдаёт сертификат, подписанный *Russian Trusted Root CA* — стандартные системные truststore (на macOS/Linux вне РФ) его не знают. В конфиге для `kind: gigachat` стоит `verify_ssl: false`. Для прода — добавить Russian Trusted Sub CA в системный truststore.\n- **Нюанс 2**: авторизация двухступенчатая — провайдер обменивает `Authorization key` на короткоживущий OAuth access-token и кэширует его. Этот flow реализован внутри `kind: gigachat`, ничего вручную делать не нужно.\n- **Биллинг и расход**: https://developers.sber.ru/studio (раздел *Проекты* → *Лицевой счёт*).\n\n### 13. FreeTheAi\n\n- **Регистрация**: только через Discord. Зайти на сервер → https://discord.gg/secrets → команда `/signup` в канале #api-keys (https://discord.com/channels/1461555807731585158/1473159205048553705) → бот пришлёт ключ вида `sta_…` в DM. Если потерял — `/resetkey`.\n- **ENV**: `FREETHEAI_API_KEY`\n- **Лимиты**: 10 RPM + **1 concurrent** на ключ — последовательные вызовы, никакого parallel.\n- **Каталог**: ~16 252 алиасов. Префиксы: `cat/*` (gpt-5/claude/gemini frontier через прокси), `bbg/*` (DeepSeek/GLM/Kimi/MiniMax reasoning), `bbl/*` (Gemini/GPT non-reasoning), `or/*` (OpenRouter passthrough), `vhr/*` (image-gen scrap из Vheer), `img/gpt-image-2` (image gen+edit b64), `fth/*` (16k случайных HF моделей — почти всегда мусор). Не все алиасы реально работают — `glm/glm-5.1` (#1 в leaderboard) и `cat/gemini-3-1-pro` возвращают 400/timeout. Перед использованием — пробовать.\n- **⚠️ Главный нюанс — DAILY /checkin**: ключ блокируется **каждые 24 часа**. Чтобы разлочить — заходишь в Discord, в тот же канал #api-keys пишешь `/checkin`, бот возвращает «ключ активен на 24h». Без этого все запросы получают `HTTP 403 daily_checkin_required`.\n- **Автоматизировать /checkin НЕЛЬЗЯ**:\n 1. Discord ToS запрещает self-bot'ы (использование своего user-токена для скриптов) — ловят и банят аккаунт.\n 2. Обычные боты Discord не могут вызывать slash-команды других ботов (by design платформы).\n 3. Browser-automation поверх web-Discord — та же категория self-bot, ban guarantied.\n 4. FreeTheAi специально поставили /checkin как защиту от abuse — обходить = бан и от них тоже.\n- **Когда использовать**:\n - Ad-hoc-запросы для тестов (`model: \"freetheai:cat/gpt-5\"`) — 24h cooldown терпим, если не забыл сделать /checkin утром.\n - Не для продовых chains (без daily-checkin сервис ляжет).\n- **Bait-and-switch**: проверка identity показала, что `cat/claude-4-6-sonnet` отвечает «built by Tiny» — это НЕ Claude. `cat/gpt-5` идентифицируется как OpenAI, но без гарантий. `bbg/deepseek-v4-pro` выдаёт gibberish. Перед интеграцией каждой модели в логику — прогнать identity-test.\n- **Image-gen**: `vhr/*` модели возвращают URL'ы на `access.vheer.com` — это прокси на бесплатный Vheer.com сервис, файлы хранятся у них. `img/gpt-image-2` отдаёт b64 (~650KB на запрос) — единственная модель, поддерживающая edits.\n\n### 14. DeepSeek (direct API)\n\n**Пошагово (получить ключ):**\n\n1. Открой https://platform.deepseek.com → *Sign Up* (Google или email)\n2. Phone verify — российские номера принимает (МТС/Мегафон/Билайн/Tele2). Если по какой-то причине не принимает твой номер — попробуй через Google-аккаунт.\n3. После входа: левое меню → *API Keys* → *Create new API key* → дать любое имя → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается **один раз** — потом только regenerate.\n4. В `.env` локально и на проде:\n ```\n DEEPSEEK_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **5M токенов signup credits** + 7-14 дней без RPM-лимитов. Этого хватит на много экспериментов.\n- Модели: `deepseek-chat` (V3.2) и `deepseek-reasoner` (R1/R2).\n\n**Когда signup credits закончатся (опционально):**\n\n- $2 топ-ап ≈ 170 ₽ → месяцы PAYG-работы (`deepseek-chat` $0.28/$0.42 за 1M, `deepseek-reasoner` сопоставимо).\n- Off-peak 16:30–00:30 UTC — скидка 50% на V3, 75% на R1.\n- Prefix caching: cache hit в 4–10× дешевле miss. Структурируй промпты так, чтобы стабильный префикс (system + RAG) шёл первым, юзер-ввод — последним.\n- ⚠️ **Не включай auto-recharge** — карта будет молча докидывать каждый раз когда баланс падает.\n- ⚠️ Российские карты Visa/MC топ-ап **не примет**. Варианты: карта дружественной страны (Казахстан/Армения/Грузия), Wise/Revolut, виртуалка от иностранного fintech.\n\n**Подводные камни:**\n\n- **Privacy**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**. Если через шлюз идут чувствительные данные клиентов — либо удали DeepSeek из chain, либо ставь его последним позади cohere/openrouter/sambanova.\n- **Из России без VPN**: иногда нестабильные 5xx-ответы. Держи fallback в той же chain ниже — он сработает автоматически.\n\n**kind**: `deepseek`. Provider в config.yaml — простая запись с `model: deepseek-chat` или `model: deepseek-reasoner`. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 15. Alibaba DashScope International (Qwen)\n\n**⚠️ Самый муторный из четырёх. Делай утром, на это уйдёт 20-30 минут.**\n\n**Пошагово (получить ключ):**\n\n1. Открой https://accountclient.alibabacloud.com/intl → *Sign Up*\n2. **Регион — обязательно Singapore.** US/HK/EU/China версии free quota НЕ дают. Если на этапе onboarding спрашивает регион — выбирай Singapore. Если уже зарегистрировался в другом регионе — придётся завести отдельный аккаунт.\n3. Phone verify (российские номера принимает).\n4. **Карта обязательна** — для Real-name Verification. С карты ничего не списывается, но без привязки free quota не активируется.\n - ⚠️ Российские карты Visa/MC **не пройдут**.\n - Варианты:\n - Карта дружественной страны (Казахстан / Армения / Грузия)\n - Wise / Revolut если есть\n - Виртуальная карта от иностранного fintech (Pyypl, Genome, etc.)\n5. После Real-name Verification → открыть https://bailian.console.alibabacloud.com (Model Studio, регион Singapore)\n6. Левое меню → *API-KEY* → *Create* → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается полностью один раз.\n7. В `.env` локально и на проде:\n ```\n DASHSCOPE_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **1M токенов на каждую модель** × **90 дней** с момента активации. Десятки моделей в каталоге → десятки миллионов токенов суммарно.\n- Флагманы: `qwen3.6-plus` (топ-3 на OpenRouter trafficу, 1M context, всегда-вкл CoT), `qwen3.6-max-preview`, `qwen3-coder-480b-a35b-instruct`, `qwen3-next-80b-a3b-instruct/thinking`, `qwen3-vl-plus`.\n\n**После 90 дней**: paid-only. Поставь напоминание `/schedule` за неделю до истечения — посмотрим использование и решим продлять или уйти на DashScope-paid.\n\n**Подводные камни:**\n\n- **Регион Singapore ОБЯЗАТЕЛЬНО**. Endpoint в config.py уже забит: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. Если у тебя аккаунт в другом регионе — ключ будет работать, но free quota = 0.\n- **Privacy**: Alibaba явно заявляет «will never use your data for model training», данные в Сингапуре → **можно использовать с PII** в отличие от китайского endpoint DeepSeek.\n- **Real-name Verification может зависнуть на сутки** — в первый раз. Если статус «pending» больше 24ч — открыть тикет в support.\n\n**kind**: `dashscope`. Provider в config.yaml — простая запись с `model: qwen3.6-plus` или другой моделью. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 16. Cohere (Command-A / c4ai-aya — для русского)\n\n- **Регистрация**: https://dashboard.cohere.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Generate Trial Key*\n- **ENV**: `COHERE_API_KEY`\n- **Free tier**: 20 RPM на модель, 1000 calls/месяц (≈33 RPD safe-floor).\n- **Модели**: `c4ai-aya-expanse-32b/8b` — multilingual, **сильный русский**. `c4ai-aya-vision-32b/8b` — vision. `command-a-03-2025` — флагман общего назначения. `command-a-reasoning-08-2025` — reasoning. `command-a-translate-08-2025` — translation.\n- **ToS**: free tier — **non-commercial only**. Для open-source / личных проектов ок. Если кто-то форкнет коммерчески — нарушение. Помечай в README.\n- **Особенность реализации**: Cohere v2 /chat — собственный response shape (`{message: {content: [{type:'text', text:...}]}}`), не OpenAI-compat. Streaming эмулируется одним SSE chunk'ом из полного ответа (Cohere v2 SSE имеет свой формат, дешевле fake-stream чем переводить).\n- **kind**: `cohere_chat` (для chat) или `cohere` (для translate-only). Эмбеддинги отдельно — `cohere_embed`.\n\n### 17. OVHcloud AI Endpoints (anonymous, без ключа)\n\n- **Регистрация**: НЕ ТРЕБУЕТСЯ. Endpoint анонимный.\n- **ENV**: НЕТ. В config.yaml запись `kind: ovhcloud` без `api_key_env`.\n- **Endpoint**: `https://oai.endpoints.kepler.ai.cloud.ovh.net/v1` — OpenAI-совместимый.\n- **Лимит**: 2 RPM **на IP** на модель. Без ключа — прозрачный rate-limit, при превышении 429.\n- **Каталог**: 40+ open-моделей, EU-host (Франция/Германия). Llama 3.x, Mistral, Qwen, Mixtral, gpt-oss-120b, и т.д.\n- **Когда использовать**: исключительно как **deep fallback / last-resort** в конце chain — «лучше отдать что-то, чем 503». В основной chain ставить нет смысла из-за 2 RPM на IP.\n- **Реализация**: `OpenAICompatProvider` пропускает `Authorization` header при пустом `api_key` (см. providers.py — изменение из этого PR).\n- **kind**: `ovhcloud`.\n\n## Платные расширения (опционально)\n\nНиже — одноразовые или recurring платные действия с непропорционально большим профитом на лимиты.\n\n### OpenRouter — $10 депозит → 20× квоты\n\n**Что делает**: однократный пополнение на $10 поднимает 50 RPD → **1000 RPD** на все `:free` модели (DeepSeek R1/V3.2, Llama 4 Maverick/Scout, Qwen3 235B, GLM-5 `:free`, Kimi K2 `:free`, MiniMax M2 `:free`, Qwen3-Coder 480B `:free`).\n\n**Как**: *Settings* → *Credits* → пополнить любую сумму ≥ $10. Сами $10 остаются на балансе и тратятся только если ты явно вызовешь платную модель. Для `:free` — это просто unlock лимита.\n\n**После депозита**: в `config.yaml` обновить `rpd: 50` → `rpd: 1000` на всех позициях с `kind: openrouter`.\n\n### xAI Grok — $25 signup + $150/мес recurring\n\n- **Регистрация**: https://console.x.ai (phone verify)\n- **Signup**: $25 кредитов на 30 дней\n- **Data-sharing program**: opt-in на sharing → $150/мес recurring (обновляется пока включено, требует минимум $5 spend за период)\n- **Зачем**: Grok 4.1 Fast — уникальный **2M context window**, никто больше такого не даёт\n- **В конфиг**: нужен `kind: xai` провайдер (OpenAI-compat endpoint `https://api.x.ai/v1`). **Пока не реализован** в llmgate.\n\n### Alibaba Qwen Singapore — 1M токенов × десятки моделей на 90 дней\n\n- **Регистрация**: https://accountclient.alibabacloud.com/intl (требует телефон и карту, +966 работает)\n- **Регион критичен**: Singapore. Endpoint `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. US/HK/EU версии free quota не дают.\n- **Квота**: 1M токенов **на каждую модель** на 90 дней → десятки моделей × 1M = десятки миллионов токенов суммарно. Флагманы: `qwen3-max`, `qwen-plus`, `qwen-flash`, `qwen3-coder-plus`, `qwen3.5-plus`.\n- **Privacy**: официально «will never use your data for model training», данные в Сингапуре.\n- **После 90 дней**: paid-only.\n- **В конфиг**: `kind: dashscope` — нативно поддерживается, см. секцию #15 выше для деталей.\n\n### DeepSeek direct — 5M signup credits + off-peak 50-75%\n\n- **Регистрация**: https://platform.deepseek.com (phone verify)\n- **Signup**: 5M токенов + 7-14 дней без rate limits\n- **Off-peak**: 16:30-00:30 UTC — **50% скидка на V3, 75% на R1**. Годится для batch-задач, не для realtime-чата.\n- **Privacy-блокер**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**.\n- **В конфиг**: `kind: deepseek` — нативно поддерживается, см. секцию #14 выше для деталей.\n\n### Anthropic Claude direct — $5 signup\n\n- **Регистрация**: https://console.anthropic.com (phone verify)\n- **Signup**: $5 кредитов на 30 дней после phone verify\n- **Зачем**: единственный способ добавить frontier Claude Sonnet/Opus в цепочку без Bedrock/Databricks\n- **Нюанс**: Anthropic API не OpenAI-compat — нужен отдельный `kind: anthropic`. В llmgate **пока не реализован**.\n\n### OpenAI direct — единоразово $5 ради бесплатной модерации (text + image)\n\n**TL;DR — зачем подключать OpenAI вообще:** ради **бесплатной модерации**. Текстовая (`text-moderation-latest`) и multimodal text+image (`omni-moderation-latest`) у OpenAI **бесплатны навсегда** и качественнее всех альтернатив. Платные модели ($0.05–$10 per 1M токенов) — опционально, если иногда понадобится высокое качество в `paid` chain. **На бесплатные chat / embed / image-gen цепочки OpenAI подключать не нужно** — у Groq / Gemini / Z.ai лимиты щедрее и без депозита.\n\n**Регистрация:**\n\n- https://platform.openai.com (Google / Microsoft / email)\n- https://platform.openai.com/api-keys → *Create new secret key*\n- **ENV**: `OPENAI_API_KEY` (для бесплатной модерации) и опционально `OPENAI_API_KEY_PAID` (для paid-моделей; можно тот же ключ — разделение нужно лишь чтобы случайно не сжечь baseline-баланс)\n\n**Критично — почему без $5 ничего не работает:**\n\nНа Free tier (без привязанной карты) OpenAI режет **все** запросы через `429 Too Many Requests` с `type: invalid_request_error` — **включая бесплатную модерацию**. Это не rate-limit моды, это аккаунт-уровневая блокировка. В ответе нет ни одного `x-ratelimit-*` хедера — это диагностический признак, что блок именно account-level, а не лимит модели. Лечится только депозитом.\n\n**Депозит — единоразово $5:**\n\n1. https://platform.openai.com/settings/organization/billing/overview → *Add payment details*\n2. Введи **`5`** в *Initial credit purchase* (минимум).\n3. ⚠️ **Снять галочку *Automatically add credits when your balance runs low***. По умолчанию она включена. Если оставить — карта будет молча докидывать $5 каждый раз когда баланс упадёт. Это главная ловушка для тех, кто хотел «только бесплатно».\n4. Подтвердить (банк может попросить 3DS).\n5. За 1-5 минут Tier поднимается `Free` → `Tier 1`, лимиты на moderation вырастают с 3 RPM до ~500 RPM.\n\n**Где следить за лимитами и расходом:**\n\n- **Rate limits per model** (RPM/RPD/TPM): https://platform.openai.com/settings/organization/limits — таблица с текущим тиром и лимитами по каждой модели. Полезно проверить после оплаты, что Tier действительно поднялся до 1.\n- **Usage (расход токенов и запросов):** https://platform.openai.com/usage — графики по дням/моделям, что именно сжигало баланс. Здесь же видно, что moderation идёт нулевой строкой.\n- **Billing & balance:** https://platform.openai.com/settings/organization/billing/overview — текущий остаток депозита, история платежей, настройки auto-recharge.\n\n**Стратегия использования $5:**\n\n- **Основной use-case (бесплатно):** модерация — `omni-moderation-latest` (text+image, 13 категорий) и `text-moderation-latest` (legacy text-only, 7 категорий) **не списываются с баланса**. $5 просто лежат бессрочно.\n- **Опционально (платно):** редкие вызовы `paid` chain через `gpt-5-mini` для случаев когда бесплатные провайдеры упёрлись или не справляются с качеством. При умеренном трафике $5 хватает на месяцы.\n- **Не подключать:** chat / embed / image_gen цепочки — у бесплатных провайдеров (Groq / Gemini / Z.ai / Cohere / Voyage / Cloudflare / Pollinations) лимиты на порядки больше.\n\n**Бесплатно после депозита:**\n\n| Модель | Что делает | Цена |\n|---|---|---|\n| `omni-moderation-latest` | Text + image moderation, 13 категорий, native scores | $0 / $0 |\n| `text-moderation-latest` | Legacy text-only, 7 категорий | $0 / $0 |\n\nВ llmgate реализованы как `kind: openai_moderation` в [config.py:118](../src/llmgate/config.py#L118), провайдер [`OpenAIModerationProvider`](../src/llmgate/providers.py#L3205). Обе уже в дефолтных цепочках `moderation` и `moderation_image`.\n\n**Платные модели — опциональный subset для `paid` chain (используя `OPENAI_API_KEY_PAID`):**\n\n| Модель | Цена in/out (per 1M) | Когда нужна |\n|---|---|---|\n| `gpt-5-mini` | $0.25 / $2.00 | Основной paid-fallback. Уже добавлен во вторую позицию `paid` после Claude Opus. |\n| `gpt-5-nano` | $0.05 / $0.40 | Если нужен ультра-дешёвый paid-fallback. На простых запросах хватает. |\n| `gpt-4.1-mini` | $0.40 / $1.60 | **1M контекст** — для длинных документов / RAG. Подключать только если упираешься в context window других моделей. |\n| `whisper-1` | $0.006/мин | STT-fallback после Groq Whisper. Только если делаешь транскрипцию серьёзных объёмов. |\n\n**Не брать:** `o3` (есть `o4-mini` в 4× дешевле), `dall-e-3` (устарел против `gpt-image-1`), `gpt-4o` / `gpt-4o-mini` (`gpt-5-mini`/`nano` дешевле и не хуже), `text-embedding-3-small/large` (Voyage даёт 200M tok permanent free на каждую модель — OpenAI embeddings подключать смысла мало), `gpt-image-1` (Kandinsky / YandexART лучше на фотореализме, см. отдельную заметку).\n\n**В конфиге:** OpenAI-нативный endpoint `https://api.openai.com/v1` — `kind: openai` для chat (`gpt-5-mini` и др.), `kind: openai_moderation` для модерации. Конкретные провайдеры см. в [config.yaml](../config.yaml) (`openai:moderation`, `openai:text-moderation`, `openai:gpt-5-mini`).\n\n## После получения ключей\n\n1. Скопировать: `cp .env.example .env`\n2. Вписать ключи в `.env` (пустые строки llmgate просто пропустит — провайдеры без ключа исключаются из цепочки)\n3. Запустить: `uv run llmgate`\n4. Проверить, какие провайдеры реально доступны: `curl -s -H \"Authorization: Bearer $TOKEN\" http://127.0.0.1:8765/v1/models`\n\nЕсли провайдер упирается в 429 — llmgate автоматически перейдёт к следующему. Если все упали — вернётся HTTP 502 `upstream_exhausted` (на free-тирах в сумме с 1 ключа это ~20-25k сообщений/сутки, так что до потолка надо постараться).\n\n## Если что-то не работает — как сообщить о баге\n\nБез следующих данных мы не можем отделить баг шлюза от проблемы провайдера / твоего соединения / клиента, и фикс затягивается на дни. Скинь всё одним сообщением:\n\n### Чек-лист (минимум)\n\n- [ ] **Что произошло** — одна-две фразы. Что должно было быть, что получилось вместо.\n- [ ] **Скриншот или видео** — обязательно. На скрине должно быть видно: само сообщение об ошибке, время, и (если применимо) URL/endpoint.\n- [ ] **Текст ошибки целиком** — копи-паст, не пересказ. Если приложение режет текст — скрин консоли / network tab из DevTools.\n- [ ] **Когда произошло** — точное время с часовым поясом (например, `2026-05-09 14:32 МСК`). Это нужно чтобы найти запись в логах.\n- [ ] **Что делал до ошибки** — последовательность действий. Например: «открыл Cursor → задал вопрос про код → пошёл стрим, на 3-й секунде оборвался». Или: «отправил длинный документ через Continue → сразу 502». **Воспроизводится повторно или один раз?**\n- [ ] **Тип соединения**:\n - Wi-Fi (домашний роутер / офис / публичный)\n - мобильный интернет (4G/5G)\n - смешанно (когда переключался с одного на другое — отметь)\n- [ ] **Провайдер/оператор**:\n - для мобильного: МТС / Мегафон / Билайн / Tele2 / Yota / другой\n - для домашнего: Ростелеком / МТС / Билайн / ТТК / Дом.ру / другой\n - если за VPN — **обязательно укажи**, какой VPN и какая страна выхода\n- [ ] **Город** (грубо — Москва / СПб / регион / зарубежье). Не для слежки, а потому что некоторые провайдеры блокируют upstream-эндпоинты только в части регионов.\n- [ ] **Какой клиент** и его версия:\n - Cursor / Claude Code / Continue / Cline / Aider / curl / собственный скрипт / браузер\n - версия (например, `Cursor 1.4.2`)\n- [ ] **Какая модель / chain** была запрошена — посмотри в настройках клиента, поле `model:`. Например: `auto`, `chat`, `deepseek:reasoner`, `paid`.\n\n### Желательно (если можешь)\n\n- **Request ID** — если ошибка вернулась с шлюза (HTTP-ответ), там в headers должен быть `x-request-id`. Скинь его — найдём конкретный запрос в логах за миллисекунды.\n- **Скрин Network tab** браузера или вывод `curl -v` — видны заголовки и точный путь.\n- **Размер промпта** — короткий вопрос или длинный документ на 50K токенов? Длинный context часто выявляет баги, которых нет на коротком.\n- **Stream или non-stream** — обычно стрим по умолчанию, но некоторые клиенты выключают.\n\n### Шаблон сообщения\n\nСкопируй и заполни:\n\n```\nЧто произошло:\nСкриншот/видео: (приложить файл)\nТекст ошибки:\n <вставить текст>\nКогда: 2026-05-09 HH:MM МСК\nЧто делал до:\nВоспроизводится: да / нет / иногда\nСоединение: Wi-Fi / мобильный\nОператор:\nVPN: нет / да (страна: ...)\nГород:\nКлиент: ... версия ...\nМодель/chain:\nRequest ID:\n```\n\n### Почему мы спрашиваем про оператора\n\nllmgate за собой держит 15+ upstream-провайдеров (Groq, Cerebras, SambaNova, Gemini, OpenRouter, DeepSeek, …). Часть из них **блокируется или режется на уровне отдельных российских операторов** — эта блокировка не от шлюза, а от твоего ISP. Признаки: connection reset / timeout / SSL handshake fail на конкретный домен. На разных операторах живут разные подмножества upstream'ов:\n\n- МТС иногда режет HuggingFace и часть Cloudflare-эндпоинтов\n- Мегафон блокирует часть Google IP-блоков → Gemini нестабильна\n- Ростелеком блокирует часть международного трафика по DPI\n- Из мобильного интернета бывает странный SNI-фильтр\n\nБез информации про оператора мы будем час крутить логи в поисках бага в коде, которого нет.\n"}, "f647a32af67f89dc2588a530d473b2eef6d119e8": {"t": 1785765661.6544318, "n": 31152, "h": "72ce478802863849", "c": "# Как получить API-ключи провайдеров\n\nПошаговая инструкция для всех провайдеров из [config.yaml.example](../config.yaml.example) — где зарегистрироваться, где взять ключ, какая переменная в [.env.example](../.env.example), важные нюансы.\n\n**Минимум для старта**: достаточно 1-2 ключей — llmgate пропустит позиции, у которых ключ пустой, и пойдёт дальше по цепочке. Стартап-репорт на консоли подскажет, какие именно env-vars не заполнены и какие провайдеры это включит. Начать проще всего с **Groq** (самый быстрый onboarding) + **Gemini** (самая жирная квота на 1 ключ).\n\n## Free quota at a glance\n\nСводная таблица — сколько просят, что дают на бесплатном тире. Цифры отражают потолки на момент cmu confg-среза, провайдеры периодически режут/щедрят — `/v1/models` и dashboard покажут реальную картину.\n\n| Провайдер | ENV-переменная | RPM | RPD / day | Monthly | Phone | Card | Особенность / quirk |\n|---|---|---|---|---|---|---|---|\n| **Groq** | `GROQ_API_KEY` | 30 | 1k–14.4k | — | нет | нет | Самый быстрый onboarding, скорость 300-1000+ т/с. Дубликаты ловят. |\n| **Gemini** | `GEMINI_API_KEY` | 10 | 250-1500 | — | нет | нет | Per-project квота: можно завести несколько GCP-проектов = ×N. Vision + tools. |\n| **Cerebras** | `CEREBRAS_API_KEY` | 5–30 | без RPD | — | да | нет | Узкий выбор моделей, но без суточного потолка. |\n| **SambaNova** | `SAMBANOVA_API_KEY` | без RPM-cap | 20/model | — | нет | нет | RPD на модель, 4 модели = 80 RPD на ключ. |\n| **NVIDIA NIM** | `NVIDIA_API_KEY` | 40 | без RPD | — | нет | нет | TTFB заметный (медленный). Использовать в `unlimited`/фоллбэк. |\n| **Z.ai** | `ZAI_API_KEY` | без cap | concurrency-only | — | нет | нет | Permanent free на GLM-4.5-Flash. China upstream — учти при чувствительном трафике. |\n| **OpenRouter (free)** | `OPENROUTER_API_KEY` | 20 | 50 (1000 с $10) | — | нет | нет* | $10 депозит → 1000 RPD на `:free`. Без депозита — 50 RPD общих. |\n| **Cloudflare Workers AI** | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` | varies | 300 (Llama 70B) | — | нет | нет | Edge inference, низкая латентность. |\n| **GitHub Models** | `GITHUB_MODELS_TOKEN` | varies | 50–150 | — | нет | нет | gpt-5-mini в free tier. Auth через GitHub PAT. |\n| **Mistral** | `MISTRAL_API_KEY` | ~4 | — | — | да | нет | Experiment plan. Без RPD-cap, но узкий RPM. |\n| **HuggingFace** | `HF_TOKEN` | varies | varies | ~$0.10 | нет | нет | Общий кредит на paid sub-providers. PRO ($9/mo) = $2 кредит. |\n| **GigaChat (Sber)** | `GIGACHAT_AUTH_KEY` | varies | varies | 1M tok / 30 дней | да (РФ) | нет | Freemium 1M токенов на 30 дней. |\n| **FreeTheAi** | `FREETHEAI_API_KEY` | 10 | varies | — | нет (Discord) | нет | **Требует daily Discord `/checkin`** — иначе 403. |\n| **DeepSeek** | `DEEPSEEK_API_KEY` | без cap | — | 5M tok signup | да | нет | После signup-кредитов — PAYG. Off-peak 50–75% скидка. |\n| **Alibaba DashScope Intl** | `DASHSCOPE_API_KEY` | varies | — | 1M tok / model × 90д | да | да | Singapore region, 1M context на флагманах. |\n| **Cohere** | `COHERE_API_KEY` | 20 | — | 1000 calls | нет | нет | **Non-commercial only** на free tier (ToS). |\n| **OVHcloud** | — (anonymous) | 2 | — | — | нет | нет | Без ключа. EU-инфра. |\n| **LibreTranslate** | — (anonymous) | varies | — | — | нет | нет | Public mirrors. Перевод. |\n| **MyMemory** | `MYMEMORY_CONTACT_EMAIL` (опц) | — | 5k chars/IP | (50k chars с email) | нет | нет | Перевод. Email увеличивает квоту. |\n| **Edge TTS** | — (anonymous) | — | — | — | нет | нет | Microsoft TTS, безлимит. |\n| **AIhorde** | — (anonymous) | — | — | — | нет | нет | Image gen, community-distributed inference. |\n\n`*` OpenRouter не требует карту для базового free tier, но $10 однократный депозит поднимает лимиты в 20 раз.\n\n### Quick suggestion: какие 2-3 ключа добавить первыми\n\n- **Самый быстрый старт:** Groq (без верификаций) → даёт мгновенный отклик и приличную квоту.\n- **Долгий контекст / vision:** Gemini.\n- **Бэкап без RPD-капа:** Cerebras (одно подтверждение телефона) или SambaNova.\n- **Русский:** Yandex Alice (`yandex_foundation` kind) — лучше для RU чем GigaChat по нашим наблюдениям.\n\n## Провайдеры\n\n### 1. Gemini (Google)\n\n- **Регистрация**: любой Google-аккаунт\n- **Получить ключ**: https://aistudio.google.com/apikey → *Create API key*\n- **ENV**: `GEMINI_API_KEY`\n- **Нюанс**: квота считается **per-project**, не per-key. Если завести 2-3 GCP-проекта на том же Google-аккаунте и сгенерить по ключу в каждом, получишь 2-3× квоту легально (TOS это разрешает — дубликаты запрещены только на уровне аккаунтов). Дополнительные ключи можно прописать как `GEMINI_API_KEY_2`, `GEMINI_API_KEY_3` и завести дубликаты провайдеров в `config.yaml` с разными `api_key_env`.\n\n### 2. Groq\n\n- **Регистрация**: https://console.groq.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Create API Key*\n- **ENV**: `GROQ_API_KEY`\n- **Нюанс**: самый быстрый провайдер в цепочке (300-1000+ токенов/сек). Free tier даёт 1000 RPD на `llama-3.3-70b-versatile` и 14400 RPD на `llama-3.1-8b-instant`. Дубликаты аккаунтов Groq ловит и банит оба — **не регистрируй второй аккаунт** с того же IP/телефона/карты.\n\n### 3. Cerebras\n\n- **Регистрация**: https://cloud.cerebras.ai (требует подтверждение телефона)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `CEREBRAS_API_KEY`\n- **Нюанс**: нет суточного лимита, но free tier сейчас узкий — реально работают только `qwen-3-235b-a22b-instruct-2507` (5 RPM) и `llama3.1-8b` (30 RPM). Более крупные модели (llama-3.3-70b, gpt-oss-120b) депрекейтнуты или paid-only.\n\n### 4. SambaNova\n\n- **Регистрация**: https://cloud.sambanova.ai (Google / email)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `SAMBANOVA_API_KEY`\n- **Нюанс**: 20 RPD **на каждую модель**, а не на аккаунт — 4 SambaNova-позиции в цепочке дают суммарно 80 RPD на один ключ. Лимит читается из заголовка `x-ratelimit-limit-requests-day` в ответе.\n\n### 5. NVIDIA NIM\n\n- **Регистрация**: https://build.nvidia.com (email, developer-программа)\n- **Получить ключ**: профиль справа вверху → *Get API Key* → выдают ключ вида `nvapi-...`\n- **ENV**: `NVIDIA_API_KEY`\n- **Нюанс**: формально **только для research/dev/test** — production TOS требует AI Enterprise license (~$4500/GPU/год). Для личного бота не критично. Нет суточного лимита, только RPM (40 на большинстве моделей).\n\n### 6. Z.ai (GLM)\n\n- **Регистрация**: https://z.ai (international) или https://open.bigmodel.cn (Китай — для аккаунтов из РФ/СНГ)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `ZAI_API_KEY`\n- **Нюанс**: `glm-4.5-flash` — **permanent free**, без RPD-лимита. В конфиге стоит `extra_body: { thinking: { type: disabled } }` — это принудительно отключает reasoning-режим (по умолчанию модель тратит токены на chain-of-thought, что режет скорость). Z.ai официально заявляет «no training on API data» — ок для чувствительного трафика.\n\n### 7. OpenRouter\n\n- **Регистрация**: https://openrouter.ai (Google / GitHub / MetaMask)\n- **Получить ключ**: https://openrouter.ai/keys → *Create Key*\n- **ENV**: `OPENROUTER_API_KEY`\n- **Нюанс**: `:free` модели делят глобальный пул 50 RPD на всех пользователей планеты — часто упирается в лимит к вечеру UTC. **Однократный депозит $10** поднимает RPD → 1000 на все `:free` модели (сами $10 не сгорают, лежат на балансе). Это единственное действие с 20× ROI на лимиты — см. «Платные расширения».\n\n### 8. Cloudflare Workers AI\n\n- **Регистрация**: https://dash.cloudflare.com (email)\n- **Получить ключ**: *My Profile* (правый верх) → *API Tokens* → *Create Token* → шаблон *Workers AI* (или custom: permission `Account → Workers AI → Read` + `Edit`)\n- **Получить Account ID**: на главной странице dashboard в правом сайдбаре — строка *Account ID*\n- **ENV**: `CLOUDFLARE_API_KEY` (токен) + `CLOUDFLARE_ACCOUNT_ID`\n- **Нюанс**: единственный провайдер, которому нужны **две** переменные. Account ID нельзя передать как env — Cloudflare вшивает его в URL запроса. 300 RPD на Llama 70B fp8-fast.\n\n### 9. GitHub Models\n\n- **Регистрация**: любой GitHub-аккаунт\n- **Получить токен**: https://github.com/settings/personal-access-tokens → *Generate new token (fine-grained)* → Account permissions → **Models: Read-only**\n- Классический PAT (`settings/tokens`) тоже работает, но fine-grained безопаснее — скоуп только на Models, не трогает репы.\n- **ENV**: `GITHUB_MODELS_TOKEN`\n- **Нюанс**: endpoint `https://models.github.ai/inference`, жёсткий потолок 8K токенов на запрос (input+output). Лимиты 50-150 RPD по моделям, считаются на токен.\n\n### 10. Mistral La Plateforme\n\n- **Регистрация**: https://console.mistral.ai (email + SMS-верификация)\n- **Получить ключ**: *API Keys*\n- **План**: выбрать **Experiment** (бесплатный) — даёт доступ к `mistral-large-latest` и остальным флагманам\n- **ENV**: `MISTRAL_API_KEY`\n- **Нюанс**: **обязательно зайти** в *Admin* → *Privacy* и **выключить опцию использования данных для обучения** — по умолчанию она включена. Без этого твои запросы уходят на training. Лимит ~4 RPM (заголовок `x-ratelimit-limit-req-minute`), не 60 как в старых доках.\n\n### 11. HuggingFace Inference Providers Router\n\n- **Регистрация**: любой HuggingFace-аккаунт https://huggingface.co\n- **Получить токен**: *Settings* → *Access Tokens* → *Create new token* → тип **Read**\n- **ENV**: `HF_TOKEN`\n- **Нюанс**: HF проксирует запросы к paid sub-providers (Novita, Cerebras, Together, …) через единый OpenAI-совместимый endpoint. Free tier даёт **~$0.10/мес общего кредита** на все sub-providers — этого хватает на эксперименты, не на постоянный трафик. **PRO-подписка ($9/мес)** даёт $2 кредита/мес. Модель указывается как `<repo>:<sub-provider>`, например `meta-llama/Llama-3.3-70B-Instruct:novita`.\n\n### 12. GigaChat (SberDevices)\n\n- **Регистрация**: https://developers.sber.ru/studio (требует подтверждённый аккаунт Сбера, телефон РФ)\n- **Получить ключ**: *Личное пространство* → *Мой GigaChat API* → *Получить новый ключ* → выдают `Authorization key` (это уже base64 от `client_id:client_secret`, готовый для `Basic`-авторизации)\n- **ENV**: `GIGACHAT_AUTH_KEY` (значение строки *Authorization key* как есть)\n- **Scope**: `GIGACHAT_API_PERS` — **Freemium** для физлиц, 1 млн токенов на 30 дней (включая Pro/Max-модели). После исчерпания квоты — billed.\n- **Нюанс 1**: GigaChat отдаёт сертификат, подписанный *Russian Trusted Root CA* — стандартные системные truststore (на macOS/Linux вне РФ) его не знают. В конфиге для `kind: gigachat` стоит `verify_ssl: false`. Для прода — добавить Russian Trusted Sub CA в системный truststore.\n- **Нюанс 2**: авторизация двухступенчатая — провайдер обменивает `Authorization key` на короткоживущий OAuth access-token и кэширует его. Этот flow реализован внутри `kind: gigachat`, ничего вручную делать не нужно.\n- **Биллинг и расход**: https://developers.sber.ru/studio (раздел *Проекты* → *Лицевой счёт*).\n\n### 13. FreeTheAi\n\n- **Регистрация**: только через Discord. Зайти на сервер → https://discord.gg/secrets → команда `/signup` в канале #api-keys (https://discord.com/channels/1461555807731585158/1473159205048553705) → бот пришлёт ключ вида `sta_…` в DM. Если потерял — `/resetkey`.\n- **ENV**: `FREETHEAI_API_KEY`\n- **Лимиты**: 10 RPM + **1 concurrent** на ключ — последовательные вызовы, никакого parallel.\n- **Каталог**: ~16 252 алиасов. Префиксы: `cat/*` (gpt-5/claude/gemini frontier через прокси), `bbg/*` (DeepSeek/GLM/Kimi/MiniMax reasoning), `bbl/*` (Gemini/GPT non-reasoning), `or/*` (OpenRouter passthrough), `vhr/*` (image-gen scrap из Vheer), `img/gpt-image-2` (image gen+edit b64), `fth/*` (16k случайных HF моделей — почти всегда мусор). Не все алиасы реально работают — `glm/glm-5.1` (#1 в leaderboard) и `cat/gemini-3-1-pro` возвращают 400/timeout. Перед использованием — пробовать.\n- **⚠️ Главный нюанс — DAILY /checkin**: ключ блокируется **каждые 24 часа**. Чтобы разлочить — заходишь в Discord, в тот же канал #api-keys пишешь `/checkin`, бот возвращает «ключ активен на 24h». Без этого все запросы получают `HTTP 403 daily_checkin_required`.\n- **Автоматизировать /checkin НЕЛЬЗЯ**:\n 1. Discord ToS запрещает self-bot'ы (использование своего user-токена для скриптов) — ловят и банят аккаунт.\n 2. Обычные боты Discord не могут вызывать slash-команды других ботов (by design платформы).\n 3. Browser-automation поверх web-Discord — та же категория self-bot, ban guarantied.\n 4. FreeTheAi специально поставили /checkin как защиту от abuse — обходить = бан и от них тоже.\n- **Когда использовать**:\n - Ad-hoc-запросы для тестов (`model: \"freetheai:cat/gpt-5\"`) — 24h cooldown терпим, если не забыл сделать /checkin утром.\n - Не для продовых chains (без daily-checkin сервис ляжет).\n- **Bait-and-switch**: проверка identity показала, что `cat/claude-4-6-sonnet` отвечает «built by Tiny» — это НЕ Claude. `cat/gpt-5` идентифицируется как OpenAI, но без гарантий. `bbg/deepseek-v4-pro` выдаёт gibberish. Перед интеграцией каждой модели в логику — прогнать identity-test.\n- **Image-gen**: `vhr/*` модели возвращают URL'ы на `access.vheer.com` — это прокси на бесплатный Vheer.com сервис, файлы хранятся у них. `img/gpt-image-2` отдаёт b64 (~650KB на запрос) — единственная модель, поддерживающая edits.\n\n### 14. DeepSeek (direct API)\n\n**Пошагово (получить ключ):**\n\n1. Открой https://platform.deepseek.com → *Sign Up* (Google или email)\n2. Phone verify — российские номера принимает (МТС/Мегафон/Билайн/Tele2). Если по какой-то причине не принимает твой номер — попробуй через Google-аккаунт.\n3. После входа: левое меню → *API Keys* → *Create new API key* → дать любое имя → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается **один раз** — потом только regenerate.\n4. В `.env` локально и на проде:\n ```\n DEEPSEEK_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **5M токенов signup credits** + 7-14 дней без RPM-лимитов. Этого хватит на много экспериментов.\n- Модели: `deepseek-chat` (V3.2) и `deepseek-reasoner` (R1/R2).\n\n**Когда signup credits закончатся (опционально):**\n\n- $2 топ-ап ≈ 170 ₽ → месяцы PAYG-работы (`deepseek-chat` $0.28/$0.42 за 1M, `deepseek-reasoner` сопоставимо).\n- Off-peak 16:30–00:30 UTC — скидка 50% на V3, 75% на R1.\n- Prefix caching: cache hit в 4–10× дешевле miss. Структурируй промпты так, чтобы стабильный префикс (system + RAG) шёл первым, юзер-ввод — последним.\n- ⚠️ **Не включай auto-recharge** — карта будет молча докидывать каждый раз когда баланс падает.\n- ⚠️ Российские карты Visa/MC топ-ап **не примет**. Варианты: карта дружественной страны (Казахстан/Армения/Грузия), Wise/Revolut, виртуалка от иностранного fintech.\n\n**Подводные камни:**\n\n- **Privacy**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**. Если через шлюз идут чувствительные данные клиентов — либо удали DeepSeek из chain, либо ставь его последним позади cohere/openrouter/sambanova.\n- **Из России без VPN**: иногда нестабильные 5xx-ответы. Держи fallback в той же chain ниже — он сработает автоматически.\n\n**kind**: `deepseek`. Provider в config.yaml — простая запись с `model: deepseek-chat` или `model: deepseek-reasoner`. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 15. Alibaba DashScope International (Qwen)\n\n**⚠️ Самый муторный из четырёх. Делай утром, на это уйдёт 20-30 минут.**\n\n**Пошагово (получить ключ):**\n\n1. Открой https://accountclient.alibabacloud.com/intl → *Sign Up*\n2. **Регион — обязательно Singapore.** US/HK/EU/China версии free quota НЕ дают. Если на этапе onboarding спрашивает регион — выбирай Singapore. Если уже зарегистрировался в другом регионе — придётся завести отдельный аккаунт.\n3. Phone verify (российские номера принимает).\n4. **Карта обязательна** — для Real-name Verification. С карты ничего не списывается, но без привязки free quota не активируется.\n - ⚠️ Российские карты Visa/MC **не пройдут**.\n - Варианты:\n - Карта дружественной страны (Казахстан / Армения / Грузия)\n - Wise / Revolut если есть\n - Виртуальная карта от иностранного fintech (Pyypl, Genome, etc.)\n5. После Real-name Verification → открыть https://bailian.console.alibabacloud.com (Model Studio, регион Singapore)\n6. Левое меню → *API-KEY* → *Create* → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается полностью один раз.\n7. В `.env` локально и на проде:\n ```\n DASHSCOPE_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **1M токенов на каждую модель** × **90 дней** с момента активации. Десятки моделей в каталоге → десятки миллионов токенов суммарно.\n- Флагманы: `qwen3.6-plus` (топ-3 на OpenRouter trafficу, 1M context, всегда-вкл CoT), `qwen3.6-max-preview`, `qwen3-coder-480b-a35b-instruct`, `qwen3-next-80b-a3b-instruct/thinking`, `qwen3-vl-plus`.\n\n**После 90 дней**: paid-only. Поставь напоминание `/schedule` за неделю до истечения — посмотрим использование и решим продлять или уйти на DashScope-paid.\n\n**Подводные камни:**\n\n- **Регион Singapore ОБЯЗАТЕЛЬНО**. Endpoint в config.py уже забит: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. Если у тебя аккаунт в другом регионе — ключ будет работать, но free quota = 0.\n- **Privacy**: Alibaba явно заявляет «will never use your data for model training», данные в Сингапуре → **можно использовать с PII** в отличие от китайского endpoint DeepSeek.\n- **Real-name Verification может зависнуть на сутки** — в первый раз. Если статус «pending» больше 24ч — открыть тикет в support.\n\n**kind**: `dashscope`. Provider в config.yaml — простая запись с `model: qwen3.6-plus` или другой моделью. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 16. Cohere (Command-A / c4ai-aya — для русского)\n\n- **Регистрация**: https://dashboard.cohere.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Generate Trial Key*\n- **ENV**: `COHERE_API_KEY`\n- **Free tier**: 20 RPM на модель, 1000 calls/месяц (≈33 RPD safe-floor).\n- **Модели**: `c4ai-aya-expanse-32b/8b` — multilingual, **сильный русский**. `c4ai-aya-vision-32b/8b` — vision. `command-a-03-2025` — флагман общего назначения. `command-a-reasoning-08-2025` — reasoning. `command-a-translate-08-2025` — translation.\n- **ToS**: free tier — **non-commercial only**. Для open-source / личных проектов ок. Если кто-то форкнет коммерчески — нарушение. Помечай в README.\n- **Особенность реализации**: Cohere v2 /chat — собственный response shape (`{message: {content: [{type:'text', text:...}]}}`), не OpenAI-compat. Streaming эмулируется одним SSE chunk'ом из полного ответа (Cohere v2 SSE имеет свой формат, дешевле fake-stream чем переводить).\n- **kind**: `cohere_chat` (для chat) или `cohere` (для translate-only). Эмбеддинги отдельно — `cohere_embed`.\n\n### 17. OVHcloud AI Endpoints (anonymous, без ключа)\n\n- **Регистрация**: НЕ ТРЕБУЕТСЯ. Endpoint анонимный.\n- **ENV**: НЕТ. В config.yaml запись `kind: ovhcloud` без `api_key_env`.\n- **Endpoint**: `https://oai.endpoints.kepler.ai.cloud.ovh.net/v1` — OpenAI-совместимый.\n- **Лимит**: 2 RPM **на IP** на модель. Без ключа — прозрачный rate-limit, при превышении 429.\n- **Каталог**: 40+ open-моделей, EU-host (Франция/Германия). Llama 3.x, Mistral, Qwen, Mixtral, gpt-oss-120b, и т.д.\n- **Когда использовать**: исключительно как **deep fallback / last-resort** в конце chain — «лучше отдать что-то, чем 503». В основной chain ставить нет смысла из-за 2 RPM на IP.\n- **Реализация**: `OpenAICompatProvider` пропускает `Authorization` header при пустом `api_key` (см. providers.py — изменение из этого PR).\n- **kind**: `ovhcloud`.\n\n## Платные расширения (опционально)\n\nНиже — одноразовые или recurring платные действия с непропорционально большим профитом на лимиты.\n\n### OpenRouter — $10 депозит → 20× квоты\n\n**Что делает**: однократный пополнение на $10 поднимает 50 RPD → **1000 RPD** на все `:free` модели (DeepSeek R1/V3.2, Llama 4 Maverick/Scout, Qwen3 235B, GLM-5 `:free`, Kimi K2 `:free`, MiniMax M2 `:free`, Qwen3-Coder 480B `:free`).\n\n**Как**: *Settings* → *Credits* → пополнить любую сумму ≥ $10. Сами $10 остаются на балансе и тратятся только если ты явно вызовешь платную модель. Для `:free` — это просто unlock лимита.\n\n**После депозита**: в `config.yaml` обновить `rpd: 50` → `rpd: 1000` на всех позициях с `kind: openrouter`.\n\n### xAI Grok — $25 signup + $150/мес recurring\n\n- **Регистрация**: https://console.x.ai (phone verify)\n- **Signup**: $25 кредитов на 30 дней\n- **Data-sharing program**: opt-in на sharing → $150/мес recurring (обновляется пока включено, требует минимум $5 spend за период)\n- **Зачем**: Grok 4.1 Fast — уникальный **2M context window**, никто больше такого не даёт\n- **В конфиг**: нужен `kind: xai` провайдер (OpenAI-compat endpoint `https://api.x.ai/v1`). **Пока не реализован** в llmgate.\n\n### Alibaba Qwen Singapore — 1M токенов × десятки моделей на 90 дней\n\n- **Регистрация**: https://accountclient.alibabacloud.com/intl (требует телефон и карту, +966 работает)\n- **Регион критичен**: Singapore. Endpoint `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. US/HK/EU версии free quota не дают.\n- **Квота**: 1M токенов **на каждую модель** на 90 дней → десятки моделей × 1M = десятки миллионов токенов суммарно. Флагманы: `qwen3-max`, `qwen-plus`, `qwen-flash`, `qwen3-coder-plus`, `qwen3.5-plus`.\n- **Privacy**: официально «will never use your data for model training», данные в Сингапуре.\n- **После 90 дней**: paid-only.\n- **В конфиг**: `kind: dashscope` — нативно поддерживается, см. секцию #15 выше для деталей.\n\n### DeepSeek direct — 5M signup credits + off-peak 50-75%\n\n- **Регистрация**: https://platform.deepseek.com (phone verify)\n- **Signup**: 5M токенов + 7-14 дней без rate limits\n- **Off-peak**: 16:30-00:30 UTC — **50% скидка на V3, 75% на R1**. Годится для batch-задач, не для realtime-чата.\n- **Privacy-блокер**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**.\n- **В конфиг**: `kind: deepseek` — нативно поддерживается, см. секцию #14 выше для деталей.\n\n### Anthropic Claude direct — $5 signup\n\n- **Регистрация**: https://console.anthropic.com (phone verify)\n- **Signup**: $5 кредитов на 30 дней после phone verify\n- **Зачем**: единственный способ добавить frontier Claude Sonnet/Opus в цепочку без Bedrock/Databricks\n- **Нюанс**: Anthropic API не OpenAI-compat — нужен отдельный `kind: anthropic`. В llmgate **пока не реализован**.\n\n### OpenAI direct — единоразово $5 ради бесплатной модерации (text + image)\n\n**TL;DR — зачем подключать OpenAI вообще:** ради **бесплатной модерации**. Текстовая (`text-moderation-latest`) и multimodal text+image (`omni-moderation-latest`) у OpenAI **бесплатны навсегда** и качественнее всех альтернатив. Платные модели ($0.05–$10 per 1M токенов) — опционально, если иногда понадобится высокое качество в `paid` chain. **На бесплатные chat / embed / image-gen цепочки OpenAI подключать не нужно** — у Groq / Gemini / Z.ai лимиты щедрее и без депозита.\n\n**Регистрация:**\n\n- https://platform.openai.com (Google / Microsoft / email)\n- https://platform.openai.com/api-keys → *Create new secret key*\n- **ENV**: `OPENAI_API_KEY` (для бесплатной модерации) и опционально `OPENAI_API_KEY_PAID` (для paid-моделей; можно тот же ключ — разделение нужно лишь чтобы случайно не сжечь baseline-баланс)\n\n**Критично — почему без $5 ничего не работает:**\n\nНа Free tier (без привязанной карты) OpenAI режет **все** запросы через `429 Too Many Requests` с `type: invalid_request_error` — **включая бесплатную модерацию**. Это не rate-limit моды, это аккаунт-уровневая блокировка. В ответе нет ни одного `x-ratelimit-*` хедера — это диагностический признак, что блок именно account-level, а не лимит модели. Лечится только депозитом.\n\n**Депозит — единоразово $5:**\n\n1. https://platform.openai.com/settings/organization/billing/overview → *Add payment details*\n2. Введи **`5`** в *Initial credit purchase* (минимум).\n3. ⚠️ **Снять галочку *Automatically add credits when your balance runs low***. По умолчанию она включена. Если оставить — карта будет молча докидывать $5 каждый раз когда баланс упадёт. Это главная ловушка для тех, кто хотел «только бесплатно».\n4. Подтвердить (банк может попросить 3DS).\n5. За 1-5 минут Tier поднимается `Free` → `Tier 1`, лимиты на moderation вырастают с 3 RPM до ~500 RPM.\n\n**Где следить за лимитами и расходом:**\n\n- **Rate limits per model** (RPM/RPD/TPM): https://platform.openai.com/settings/organization/limits — таблица с текущим тиром и лимитами по каждой модели. Полезно проверить после оплаты, что Tier действительно поднялся до 1.\n- **Usage (расход токенов и запросов):** https://platform.openai.com/usage — графики по дням/моделям, что именно сжигало баланс. Здесь же видно, что moderation идёт нулевой строкой.\n- **Billing & balance:** https://platform.openai.com/settings/organization/billing/overview — текущий остаток депозита, история платежей, настройки auto-recharge.\n\n**Стратегия использования $5:**\n\n- **Основной use-case (бесплатно):** модерация — `omni-moderation-latest` (text+image, 13 категорий) и `text-moderation-latest` (legacy text-only, 7 категорий) **не списываются с баланса**. $5 просто лежат бессрочно.\n- **Опционально (платно):** редкие вызовы `paid` chain через `gpt-5-mini` для случаев когда бесплатные провайдеры упёрлись или не справляются с качеством. При умеренном трафике $5 хватает на месяцы.\n- **Не подключать:** chat / embed / image_gen цепочки — у бесплатных провайдеров (Groq / Gemini / Z.ai / Cohere / Voyage / Cloudflare / Pollinations) лимиты на порядки больше.\n\n**Бесплатно после депозита:**\n\n| Модель | Что делает | Цена |\n|---|---|---|\n| `omni-moderation-latest` | Text + image moderation, 13 категорий, native scores | $0 / $0 |\n| `text-moderation-latest` | Legacy text-only, 7 категорий | $0 / $0 |\n\nВ llmgate реализованы как `kind: openai_moderation` в [config.py:118](../src/llmgate/config.py#L118), провайдер [`OpenAIModerationProvider`](../src/llmgate/providers.py#L3205). Обе уже в дефолтных цепочках `moderation` и `moderation_image`.\n\n**Платные модели — опциональный subset для `paid` chain (используя `OPENAI_API_KEY_PAID`):**\n\n| Модель | Цена in/out (per 1M) | Когда нужна |\n|---|---|---|\n| `gpt-5-mini` | $0.25 / $2.00 | Основной paid-fallback. Уже добавлен во вторую позицию `paid` после Claude Opus. |\n| `gpt-5-nano` | $0.05 / $0.40 | Если нужен ультра-дешёвый paid-fallback. На простых запросах хватает. |\n| `gpt-4.1-mini` | $0.40 / $1.60 | **1M контекст** — для длинных документов / RAG. Подключать только если упираешься в context window других моделей. |\n| `whisper-1` | $0.006/мин | STT-fallback после Groq Whisper. Только если делаешь транскрипцию серьёзных объёмов. |\n\n**Не брать:** `o3` (есть `o4-mini` в 4× дешевле), `dall-e-3` (устарел против `gpt-image-1`), `gpt-4o` / `gpt-4o-mini` (`gpt-5-mini`/`nano` дешевле и не хуже), `text-embedding-3-small/large` (Voyage даёт 200M tok permanent free на каждую модель — OpenAI embeddings подключать смысла мало), `gpt-image-1` (Kandinsky / YandexART лучше на фотореализме, см. отдельную заметку).\n\n**В конфиге:** OpenAI-нативный endpoint `https://api.openai.com/v1` — `kind: openai` для chat (`gpt-5-mini` и др.), `kind: openai_moderation` для модерации. Конкретные провайдеры см. в [config.yaml](../config.yaml) (`openai:moderation`, `openai:text-moderation`, `openai:gpt-5-mini`).\n\n## После получения ключей\n\n1. Скопировать: `cp .env.example .env`\n2. Вписать ключи в `.env` (пустые строки llmgate просто пропустит — провайдеры без ключа исключаются из цепочки)\n3. Запустить: `uv run llmgate`\n4. Проверить, какие провайдеры реально доступны: `curl -s -H \"Authorization: Bearer $TOKEN\" http://127.0.0.1:8765/v1/models`\n\nЕсли провайдер упирается в 429 — llmgate автоматически перейдёт к следующему. Если все упали — вернётся HTTP 502 `upstream_exhausted` (на free-тирах в сумме с 1 ключа это ~20-25k сообщений/сутки, так что до потолка надо постараться).\n\n## Если что-то не работает — как сообщить о баге\n\nБез следующих данных мы не можем отделить баг шлюза от проблемы провайдера / твоего соединения / клиента, и фикс затягивается на дни. Скинь всё одним сообщением:\n\n### Чек-лист (минимум)\n\n- [ ] **Что произошло** — одна-две фразы. Что должно было быть, что получилось вместо.\n- [ ] **Скриншот или видео** — обязательно. На скрине должно быть видно: само сообщение об ошибке, время, и (если применимо) URL/endpoint.\n- [ ] **Текст ошибки целиком** — копи-паст, не пересказ. Если приложение режет текст — скрин консоли / network tab из DevTools.\n- [ ] **Когда произошло** — точное время с часовым поясом (например, `2026-05-09 14:32 МСК`). Это нужно чтобы найти запись в логах.\n- [ ] **Что делал до ошибки** — последовательность действий. Например: «открыл Cursor → задал вопрос про код → пошёл стрим, на 3-й секунде оборвался». Или: «отправил длинный документ через Continue → сразу 502». **Воспроизводится повторно или один раз?**\n- [ ] **Тип соединения**:\n - Wi-Fi (домашний роутер / офис / публичный)\n - мобильный интернет (4G/5G)\n - смешанно (когда переключался с одного на другое — отметь)\n- [ ] **Провайдер/оператор**:\n - для мобильного: МТС / Мегафон / Билайн / Tele2 / Yota / другой\n - для домашнего: Ростелеком / МТС / Билайн / ТТК / Дом.ру / другой\n - если за VPN — **обязательно укажи**, какой VPN и какая страна выхода\n- [ ] **Город** (грубо — Москва / СПб / регион / зарубежье). Не для слежки, а потому что некоторые провайдеры блокируют upstream-эндпоинты только в части регионов.\n- [ ] **Какой клиент** и его версия:\n - Cursor / Claude Code / Continue / Cline / Aider / curl / собственный скрипт / браузер\n - версия (например, `Cursor 1.4.2`)\n- [ ] **Какая модель / chain** была запрошена — посмотри в настройках клиента, поле `model:`. Например: `auto`, `chat`, `deepseek:reasoner`, `paid`.\n\n### Желательно (если можешь)\n\n- **Request ID** — если ошибка вернулась с шлюза (HTTP-ответ), там в headers должен быть `x-request-id`. Скинь его — найдём конкретный запрос в логах за миллисекунды.\n- **Скрин Network tab** браузера или вывод `curl -v` — видны заголовки и точный путь.\n- **Размер промпта** — короткий вопрос или длинный документ на 50K токенов? Длинный context часто выявляет баги, которых нет на коротком.\n- **Stream или non-stream** — обычно стрим по умолчанию, но некоторые клиенты выключают.\n\n### Шаблон сообщения\n\nСкопируй и заполни:\n\n```\nЧто произошло:\nСкриншот/видео: (приложить файл)\nТекст ошибки:\n <вставить текст>\nКогда: 2026-05-09 HH:MM МСК\nЧто делал до:\nВоспроизводится: да / нет / иногда\nСоединение: Wi-Fi / мобильный\nОператор:\nVPN: нет / да (страна: ...)\nГород:\nКлиент: ... версия ...\nМодель/chain:\nRequest ID:\n```\n\n### Почему мы спрашиваем про оператора\n\nllmgate за собой держит 15+ upstream-провайдеров (Groq, Cerebras, SambaNova, Gemini, OpenRouter, DeepSeek, …). Часть из них **блокируется или режется на уровне отдельных российских операторов** — эта блокировка не от шлюза, а от твоего ISP. Признаки: connection reset / timeout / SSL handshake fail на конкретный домен. На разных операторах живут разные подмножества upstream'ов:\n\n- МТС иногда режет HuggingFace и часть Cloudflare-эндпоинтов\n- Мегафон блокирует часть Google IP-блоков → Gemini нестабильна\n- Ростелеком блокирует часть международного трафика по DPI\n- Из мобильного интернета бывает странный SNI-фильтр\n\nБез информации про оператора мы будем час крутить логи в поисках бага в коде, которого нет.\n"}, "a14154f82e6fe22e1956c1c4538bd18a2c70fd96": {"t": 1785765663.0912673, "n": 31168, "h": "1b1f48c580da5bf6", "c": "# Как получить API-ключи провайдеров\n\nПошаговая инструкция для всех провайдеров из [config.yaml.example](../config.yaml.example) — где зарегистрироваться, где взять ключ, какая переменная в [.env.example](../.env.example), важные нюансы.\n\n**Минимум для старта**: достаточно 1-2 ключей — llmgate пропустит позиции, у которых ключ пустой, и пойдёт дальше по цепочке. Стартап-репорт на консоли подскажет, какие именно env-vars не заполнены и какие провайдеры это включит. Начать проще всего с **Groq** (самый быстрый onboarding) + **Gemini** (самая жирная квота на 1 ключ).\n\n## Free quota at a glance\n\nСводная таблица — сколько просят, что дают на бесплатном тире. Цифры отражают потолки на момент cmu confg-среза, провайдеры периодически режут/щедрят — `/v1/models` и dashboard покажут реальную картину.\n\n| Провайдер | ENV-переменная | RPM | RPD / day | Monthly | Phone | Card | Особенность / quirk |\n|---|---|---|---|---|---|---|---|\n| **Groq** | `GROQ_API_KEY` | 30 | 1k–14.4k | — | нет | нет | Самый быстрый onboarding, скорость 300-1000+ т/с. Дубликаты ловят. |\n| **Gemini** | `GEMINI_API_KEY` | 10 | 250-1500 | — | нет | нет | Per-project квота: можно завести несколько GCP-проектов = ×N. Vision + tools. |\n| **Cerebras** | `CEREBRAS_API_KEY` | 5–30 | без RPD | — | да | нет | Узкий выбор моделей, но без суточного потолка. |\n| **SambaNova** | `SAMBANOVA_API_KEY` | без RPM-cap | 20/model | — | нет | нет | RPD на модель, 4 модели = 80 RPD на ключ. |\n| **NVIDIA NIM** | `NVIDIA_API_KEY` | 40 | без RPD | — | нет | нет | TTFB заметный (медленный). Использовать в `unlimited`/фоллбэк. |\n| **Z.ai** | `ZAI_API_KEY` | без cap | concurrency-only | — | нет | нет | Permanent free на GLM-4.5-Flash. China upstream — учти при чувствительном трафике. |\n| **OpenRouter (free)** | `OPENROUTER_API_KEY` | 20 | 50 (1000 с $10) | — | нет | нет* | $10 депозит → 1000 RPD на `:free`. Без депозита — 50 RPD общих. |\n| **Cloudflare Workers AI** | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` | varies | 300 (Llama 70B) | — | нет | нет | Edge inference, низкая латентность. |\n| **GitHub Models** | `GITHUB_MODELS_TOKEN` | varies | 50–150 | — | нет | нет | gpt-5-mini в free tier. Auth через GitHub PAT. |\n| **Mistral** | `MISTRAL_API_KEY` | ~4 | — | — | да | нет | Experiment plan. Без RPD-cap, но узкий RPM. |\n| **HuggingFace** | `HF_TOKEN` | varies | varies | ~$0.10 | нет | нет | Общий кредит на paid sub-providers. PRO ($9/mo) = $2 кредит. |\n| **GigaChat (Sber)** | `GIGACHAT_AUTH_KEY` | varies | varies | 1M tok / 30 дней | да (РФ) | нет | Freemium 1M токенов на 30 дней. |\n| **FreeTheAi** | `FREETHEAI_API_KEY` | 10 | varies | — | нет (Discord) | нет | **Требует daily Discord `/checkin`** — иначе 403. |\n| **DeepSeek** | `DEEPSEEK_API_KEY` | без cap | — | 5M tok signup | да | нет | После signup-кредитов — PAYG. Off-peak 50–75% скидка. |\n| **Alibaba DashScope Intl** | `DASHSCOPE_API_KEY` | varies | — | 1M tok / model × 90д | да | да | Singapore region, 1M context на флагманах. |\n| **Cohere** | `COHERE_API_KEY` | 20 | — | 1000 calls | нет | нет | **Non-commercial only** на free tier (ToS). |\n| **OVHcloud** | — (anonymous) | 2 | — | — | нет | нет | Без ключа. EU-инфра. |\n| **LibreTranslate** | — (anonymous) | varies | — | — | нет | нет | Public mirrors. Перевод. |\n| **MyMemory** | `MYMEMORY_CONTACT_EMAIL` (опц) | — | 5k chars/IP | (50k chars с email) | нет | нет | Перевод. Email увеличивает квоту. |\n| **Edge TTS** | — (anonymous) | — | — | — | нет | нет | Microsoft TTS, безлимит. |\n| **AIhorde** | — (anonymous) | — | — | — | нет | нет | Image gen, community-distributed inference. |\n\n`*` OpenRouter не требует карту для базового free tier, но $10 однократный депозит поднимает лимиты в 20 раз.\n\n### Quick suggestion: какие 2-3 ключа добавить первыми\n\n- **Самый быстрый старт:** Groq (без верификаций) → даёт мгновенный отклик и приличную квоту.\n- **Долгий контекст / vision:** Gemini.\n- **Бэкап без RPD-капа:** Cerebras (одно подтверждение телефона) или SambaNova.\n- **Русский:** Yandex Alice (`yandex_foundation` kind) — лучше для RU чем GigaChat по нашим наблюдениям.\n\n## Провайдеры\n\n### 1. Gemini (Google)\n\n- **Регистрация**: любой Google-аккаунт\n- **Получить ключ**: https://aistudio.google.com/apikey → *Create API key*\n- **ENV**: `GEMINI_API_KEY`\n- **Нюанс**: квота считается **per-project**, не per-key. Если завести 2-3 GCP-проекта на том же Google-аккаунте и сгенерить по ключу в каждом, получишь 2-3× квоту легально (TOS это разрешает — дубликаты запрещены только на уровне аккаунтов). Дополнительные ключи можно прописать как `GEMINI_API_KEY_2`, `GEMINI_API_KEY_3` и завести дубликаты провайдеров в `config.yaml` с разными `api_key_env`.\n\n### 2. Groq\n\n- **Регистрация**: https://console.groq.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Create API Key*\n- **ENV**: `GROQ_API_KEY`\n- **Нюанс**: самый быстрый провайдер в цепочке (300-1000+ токенов/сек). Free tier даёт 1000 RPD на `llama-3.3-70b-versatile` и 14400 RPD на `llama-3.1-8b-instant`. Дубликаты аккаунтов Groq ловит и банит оба — **не регистрируй второй аккаунт** с того же IP/телефона/карты.\n\n### 3. Cerebras\n\n- **Регистрация**: https://cloud.cerebras.ai (требует подтверждение телефона)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `CEREBRAS_API_KEY`\n- **Нюанс**: нет суточного лимита, но free tier сейчас узкий — реально работают только `qwen-3-235b-a22b-instruct-2507` (5 RPM) и `llama3.1-8b` (30 RPM). Более крупные модели (llama-3.3-70b, gpt-oss-120b) депрекейтнуты или paid-only.\n\n### 4. SambaNova\n\n- **Регистрация**: https://cloud.sambanova.ai (Google / email)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `SAMBANOVA_API_KEY`\n- **Нюанс**: 20 RPD **на каждую модель**, а не на аккаунт — 4 SambaNova-позиции в цепочке дают суммарно 80 RPD на один ключ. Лимит читается из заголовка `x-ratelimit-limit-requests-day` в ответе.\n\n### 5. NVIDIA NIM\n\n- **Регистрация**: https://build.nvidia.com (email, developer-программа)\n- **Получить ключ**: профиль справа вверху → *Get API Key* → выдают ключ вида `nvapi-...`\n- **ENV**: `NVIDIA_API_KEY`\n- **Нюанс**: формально **только для research/dev/test** — production TOS требует AI Enterprise license (~$4500/GPU/год). Для личного бота не критично. Нет суточного лимита, только RPM (40 на большинстве моделей).\n\n### 6. Z.ai (GLM)\n\n- **Регистрация**: https://z.ai (international) или https://open.bigmodel.cn (Китай — для аккаунтов из РФ/СНГ)\n- **Получить ключ**: *API Keys* в dashboard\n- **ENV**: `ZAI_API_KEY`\n- **Нюанс**: `glm-4.5-flash` — **permanent free**, без RPD-лимита. В конфиге стоит `extra_body: { thinking: { type: disabled } }` — это принудительно отключает reasoning-режим (по умолчанию модель тратит токены на chain-of-thought, что режет скорость). Z.ai официально заявляет «no training on API data» — ок для чувствительного трафика.\n\n### 7. OpenRouter\n\n- **Регистрация**: https://openrouter.ai (Google / GitHub / MetaMask)\n- **Получить ключ**: https://openrouter.ai/keys → *Create Key*\n- **ENV**: `OPENROUTER_API_KEY`\n- **Нюанс**: `:free` модели делят глобальный пул 50 RPD на всех пользователей планеты — часто упирается в лимит к вечеру UTC. **Однократный депозит $10** поднимает RPD → 1000 на все `:free` модели (сами $10 не сгорают, лежат на балансе). Это единственное действие с 20× ROI на лимиты — см. «Платные расширения».\n\n### 8. Cloudflare Workers AI\n\n- **Регистрация**: https://dash.cloudflare.com (email)\n- **Получить ключ**: *My Profile* (правый верх) → *API Tokens* → *Create Token* → шаблон *Workers AI* (или custom: permission `Account → Workers AI → Read` + `Edit`)\n- **Получить Account ID**: на главной странице dashboard в правом сайдбаре — строка *Account ID*\n- **ENV**: `CLOUDFLARE_API_KEY` (токен) + `CLOUDFLARE_ACCOUNT_ID`\n- **Нюанс**: единственный провайдер, которому нужны **две** переменные. Account ID нельзя передать как env — Cloudflare вшивает его в URL запроса. 300 RPD на Llama 70B fp8-fast.\n\n### 9. GitHub Models\n\n- **Регистрация**: любой GitHub-аккаунт\n- **Получить токен**: https://github.com/settings/personal-access-tokens → *Generate new token (fine-grained)* → Account permissions → **Models: Read-only**\n- Классический PAT (`settings/tokens`) тоже работает, но fine-grained безопаснее — скоуп только на Models, не трогает репы.\n- **ENV**: `GITHUB_MODELS_TOKEN`\n- **Нюанс**: endpoint `https://models.github.ai/inference`, жёсткий потолок 8K токенов на запрос (input+output). Лимиты 50-150 RPD по моделям, считаются на токен.\n\n### 10. Mistral La Plateforme\n\n- **Регистрация**: https://console.mistral.ai (email + SMS-верификация)\n- **Получить ключ**: *API Keys*\n- **План**: выбрать **Experiment** (бесплатный) — даёт доступ к `mistral-large-latest` и остальным флагманам\n- **ENV**: `MISTRAL_API_KEY`\n- **Нюанс**: **обязательно зайти** в *Admin* → *Privacy* и **выключить опцию использования данных для обучения** — по умолчанию она включена. Без этого твои запросы уходят на training. Лимит ~4 RPM (заголовок `x-ratelimit-limit-req-minute`), не 60 как в старых доках.\n\n### 11. HuggingFace Inference Providers Router\n\n- **Регистрация**: любой HuggingFace-аккаунт https://huggingface.co\n- **Получить токен**: *Settings* → *Access Tokens* → *Create new token* → тип **Read**\n- **ENV**: `HF_TOKEN`\n- **Нюанс**: HF проксирует запросы к paid sub-providers (Novita, Cerebras, Together, …) через единый OpenAI-совместимый endpoint. Free tier даёт **~$0.10/мес общего кредита** на все sub-providers — этого хватает на эксперименты, не на постоянный трафик. **PRO-подписка ($9/мес)** даёт $2 кредита/мес. Модель указывается как `<repo>:<sub-provider>`, например `meta-llama/Llama-3.3-70B-Instruct:novita`.\n\n### 12. GigaChat (SberDevices)\n\n- **Регистрация**: https://developers.sber.ru/studio (требует подтверждённый аккаунт Сбера, телефон РФ)\n- **Получить ключ**: *Личное пространство* → *Мой GigaChat API* → *Получить новый ключ* → выдают `Authorization key` (это уже base64 от `client_id:client_secret`, готовый для `Basic`-авторизации)\n- **ENV**: `GIGACHAT_AUTH_KEY` (значение строки *Authorization key* как есть)\n- **Scope**: `GIGACHAT_API_PERS` — **Freemium** для физлиц, 1 млн токенов на 30 дней (включая Pro/Max-модели). После исчерпания квоты — billed.\n- **Нюанс 1**: GigaChat отдаёт сертификат, подписанный *Russian Trusted Root CA* — стандартные системные truststore (на macOS/Linux вне РФ) его не знают. В конфиге для `kind: gigachat` стоит `verify_ssl: false`. Для прода — добавить Russian Trusted Sub CA в системный truststore.\n- **Нюанс 2**: авторизация двухступенчатая — провайдер обменивает `Authorization key` на короткоживущий OAuth access-token и кэширует его. Этот flow реализован внутри `kind: gigachat`, ничего вручную делать не нужно.\n- **Биллинг и расход**: https://developers.sber.ru/studio (раздел *Проекты* → *Лицевой счёт*).\n\n### 13. FreeTheAi\n\n- **Регистрация**: только через Discord. Зайти на сервер → https://discord.gg/secrets → команда `/signup` в канале #api-keys (https://discord.com/channels/1461555807731585158/1473159205048553705) → бот пришлёт ключ вида `sta_…` в DM. Если потерял — `/resetkey`.\n- **ENV**: `FREETHEAI_API_KEY`\n- **Лимиты**: 10 RPM + **1 concurrent** на ключ — последовательные вызовы, никакого parallel.\n- **Каталог**: ~16 252 алиасов. Префиксы: `cat/*` (gpt-5/claude/gemini frontier через прокси), `bbg/*` (DeepSeek/GLM/Kimi/MiniMax reasoning), `bbl/*` (Gemini/GPT non-reasoning), `or/*` (OpenRouter passthrough), `vhr/*` (image-gen scrap из Vheer), `img/gpt-image-2` (image gen+edit b64), `fth/*` (16k случайных HF моделей — почти всегда мусор). Не все алиасы реально работают — `glm/glm-5.1` (#1 в leaderboard) и `cat/gemini-3-1-pro` возвращают 400/timeout. Перед использованием — пробовать.\n- **⚠️ Главный нюанс — DAILY /checkin**: ключ блокируется **каждые 24 часа**. Чтобы разлочить — заходишь в Discord, в тот же канал #api-keys пишешь `/checkin`, бот возвращает «ключ активен на 24h». Без этого все запросы получают `HTTP 403 daily_checkin_required`.\n- **Автоматизировать /checkin НЕЛЬЗЯ**:\n 1. Discord ToS запрещает self-bot'ы (использование своего user-токена для скриптов) — ловят и банят аккаунт.\n 2. Обычные боты Discord не могут вызывать slash-команды других ботов (by design платформы).\n 3. Browser-automation поверх web-Discord — та же категория self-bot, ban guarantied.\n 4. FreeTheAi специально поставили /checkin как защиту от abuse — обходить = бан и от них тоже.\n- **Когда использовать**:\n - Ad-hoc-запросы для тестов (`model: \"freetheai:cat/gpt-5\"`) — 24h cooldown терпим, если не забыл сделать /checkin утром.\n - Не для продовых chains (без daily-checkin сервис ляжет).\n- **Bait-and-switch**: проверка identity показала, что `cat/claude-4-6-sonnet` отвечает «built by Tiny» — это НЕ Claude. `cat/gpt-5` идентифицируется как OpenAI, но без гарантий. `bbg/deepseek-v4-pro` выдаёт gibberish. Перед интеграцией каждой модели в логику — прогнать identity-test.\n- **Image-gen**: `vhr/*` модели возвращают URL'ы на `access.vheer.com` — это прокси на бесплатный Vheer.com сервис, файлы хранятся у них. `img/gpt-image-2` отдаёт b64 (~650KB на запрос) — единственная модель, поддерживающая edits.\n\n### 14. DeepSeek (direct API)\n\n**Пошагово (получить ключ):**\n\n1. Открой https://platform.deepseek.com → *Sign Up* (Google или email)\n2. Phone verify — российские номера принимает (МТС/Мегафон/Билайн/Tele2). Если по какой-то причине не принимает твой номер — попробуй через Google-аккаунт.\n3. После входа: левое меню → *API Keys* → *Create new API key* → дать любое имя → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается **один раз** — потом только regenerate.\n4. В `.env` локально и на проде:\n ```\n DEEPSEEK_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **5M токенов signup credits** + 7-14 дней без RPM-лимитов. Этого хватит на много экспериментов.\n- Модели: `deepseek-chat` (V3.2) и `deepseek-reasoner` (R1/R2).\n\n**Когда signup credits закончатся (опционально):**\n\n- $2 топ-ап ≈ 170 ₽ → месяцы PAYG-работы (`deepseek-chat` $0.28/$0.42 за 1M, `deepseek-reasoner` сопоставимо).\n- Off-peak 16:30–00:30 UTC — скидка 50% на V3, 75% на R1.\n- Prefix caching: cache hit в 4–10× дешевле miss. Структурируй промпты так, чтобы стабильный префикс (system + RAG) шёл первым, юзер-ввод — последним.\n- ⚠️ **Не включай auto-recharge** — карта будет молча докидывать каждый раз когда баланс падает.\n- ⚠️ Российские карты Visa/MC топ-ап **не примет**. Варианты: карта дружественной страны (Казахстан/Армения/Грузия), Wise/Revolut, виртуалка от иностранного fintech.\n\n**Подводные камни:**\n\n- **Privacy**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**. Если через шлюз идут чувствительные данные клиентов — либо удали DeepSeek из chain, либо ставь его последним позади cohere/openrouter/sambanova.\n- **Из России без VPN**: иногда нестабильные 5xx-ответы. Держи fallback в той же chain ниже — он сработает автоматически.\n\n**kind**: `deepseek`. Provider в config.yaml — простая запись с `model: deepseek-chat` или `model: deepseek-reasoner`. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 15. Alibaba DashScope International (Qwen)\n\n**⚠️ Самый муторный из четырёх. Делай утром, на это уйдёт 20-30 минут.**\n\n**Пошагово (получить ключ):**\n\n1. Открой https://accountclient.alibabacloud.com/intl → *Sign Up*\n2. **Регион — обязательно Singapore.** US/HK/EU/China версии free quota НЕ дают. Если на этапе onboarding спрашивает регион — выбирай Singapore. Если уже зарегистрировался в другом регионе — придётся завести отдельный аккаунт.\n3. Phone verify (российские номера принимает).\n4. **Карта обязательна** — для Real-name Verification. С карты ничего не списывается, но без привязки free quota не активируется.\n - ⚠️ Российские карты Visa/MC **не пройдут**.\n - Варианты:\n - Карта дружественной страны (Казахстан / Армения / Грузия)\n - Wise / Revolut если есть\n - Виртуальная карта от иностранного fintech (Pyypl, Genome, etc.)\n5. После Real-name Verification → открыть https://bailian.console.alibabacloud.com (Model Studio, регион Singapore)\n6. Левое меню → *API-KEY* → *Create* → скопировать ключ (вид `sk-xxxxx...`). Ключ показывается полностью один раз.\n7. В `.env` локально и на проде:\n ```\n DASHSCOPE_API_KEY=sk-xxxxx...\n ```\n\n**Что получаешь сразу (бесплатно):**\n\n- **1M токенов на каждую модель** × **90 дней** с момента активации. Десятки моделей в каталоге → десятки миллионов токенов суммарно.\n- Флагманы: `qwen3.6-plus` (топ-3 на OpenRouter trafficу, 1M context, всегда-вкл CoT), `qwen3.6-max-preview`, `qwen3-coder-480b-a35b-instruct`, `qwen3-next-80b-a3b-instruct/thinking`, `qwen3-vl-plus`.\n\n**После 90 дней**: paid-only. Поставь напоминание `/schedule` за неделю до истечения — посмотрим использование и решим продлять или уйти на DashScope-paid.\n\n**Подводные камни:**\n\n- **Регион Singapore ОБЯЗАТЕЛЬНО**. Endpoint в config.py уже забит: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. Если у тебя аккаунт в другом регионе — ключ будет работать, но free quota = 0.\n- **Privacy**: Alibaba явно заявляет «will never use your data for model training», данные в Сингапуре → **можно использовать с PII** в отличие от китайского endpoint DeepSeek.\n- **Real-name Verification может зависнуть на сутки** — в первый раз. Если статус «pending» больше 24ч — открыть тикет в support.\n\n**kind**: `dashscope`. Provider в config.yaml — простая запись с `model: qwen3.6-plus` или другой моделью. Уже добавлено в `chat`/`code`/`quality`/`latency` chains в `config.yaml.example`.\n\n### 16. Cohere (Command-A / c4ai-aya — для русского)\n\n- **Регистрация**: https://dashboard.cohere.com (Google / GitHub / email)\n- **Получить ключ**: *API Keys* → *Generate Trial Key*\n- **ENV**: `COHERE_API_KEY`\n- **Free tier**: 20 RPM на модель, 1000 calls/месяц (≈33 RPD safe-floor).\n- **Модели**: `c4ai-aya-expanse-32b/8b` — multilingual, **сильный русский**. `c4ai-aya-vision-32b/8b` — vision. `command-a-03-2025` — флагман общего назначения. `command-a-reasoning-08-2025` — reasoning. `command-a-translate-08-2025` — translation.\n- **ToS**: free tier — **non-commercial only**. Для open-source / личных проектов ок. Если кто-то форкнет коммерчески — нарушение. Помечай в README.\n- **Особенность реализации**: Cohere v2 /chat — собственный response shape (`{message: {content: [{type:'text', text:...}]}}`), не OpenAI-compat. Streaming эмулируется одним SSE chunk'ом из полного ответа (Cohere v2 SSE имеет свой формат, дешевле fake-stream чем переводить).\n- **kind**: `cohere_chat` (для chat) или `cohere` (для translate-only). Эмбеддинги отдельно — `cohere_embed`.\n\n### 17. OVHcloud AI Endpoints (anonymous, без ключа)\n\n- **Регистрация**: НЕ ТРЕБУЕТСЯ. Endpoint анонимный.\n- **ENV**: НЕТ. В config.yaml запись `kind: ovhcloud` без `api_key_env`.\n- **Endpoint**: `https://oai.endpoints.kepler.ai.cloud.ovh.net/v1` — OpenAI-совместимый.\n- **Лимит**: 2 RPM **на IP** на модель. Без ключа — прозрачный rate-limit, при превышении 429.\n- **Каталог**: 40+ open-моделей, EU-host (Франция/Германия). Llama 3.x, Mistral, Qwen, Mixtral, gpt-oss-120b, и т.д.\n- **Когда использовать**: исключительно как **deep fallback / last-resort** в конце chain — «лучше отдать что-то, чем 503». В основной chain ставить нет смысла из-за 2 RPM на IP.\n- **Реализация**: `OpenAICompatProvider` пропускает `Authorization` header при пустом `api_key` (см. providers.py — изменение из этого PR).\n- **kind**: `ovhcloud`.\n\n## Платные расширения (опционально)\n\nНиже — одноразовые или recurring платные действия с непропорционально большим профитом на лимиты.\n\n### OpenRouter — $10 депозит → 20× квоты\n\n**Что делает**: однократный пополнение на $10 поднимает 50 RPD → **1000 RPD** на все `:free` модели (DeepSeek R1/V3.2, Llama 4 Maverick/Scout, Qwen3 235B, GLM-5 `:free`, Kimi K2 `:free`, MiniMax M2 `:free`, Qwen3-Coder 480B `:free`).\n\n**Как**: *Settings* → *Credits* → пополнить любую сумму ≥ $10. Сами $10 остаются на балансе и тратятся только если ты явно вызовешь платную модель. Для `:free` — это просто unlock лимита.\n\n**После депозита**: в `config.yaml` обновить `rpd: 50` → `rpd: 1000` на всех позициях с `kind: openrouter`.\n\n### xAI Grok — $25 signup + $150/мес recurring\n\n- **Регистрация**: https://console.x.ai (phone verify)\n- **Signup**: $25 кредитов на 30 дней\n- **Data-sharing program**: opt-in на sharing → $150/мес recurring (обновляется пока включено, требует минимум $5 spend за период)\n- **Зачем**: Grok 4.1 Fast — уникальный **2M context window**, никто больше такого не даёт\n- **В конфиг**: нужен `kind: xai` провайдер (OpenAI-compat endpoint `https://api.x.ai/v1`). **Пока не реализован** в neurogate.\n\n### Alibaba Qwen Singapore — 1M токенов × десятки моделей на 90 дней\n\n- **Регистрация**: https://accountclient.alibabacloud.com/intl (требует телефон и карту, +966 работает)\n- **Регион критичен**: Singapore. Endpoint `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. US/HK/EU версии free quota не дают.\n- **Квота**: 1M токенов **на каждую модель** на 90 дней → десятки моделей × 1M = десятки миллионов токенов суммарно. Флагманы: `qwen3-max`, `qwen-plus`, `qwen-flash`, `qwen3-coder-plus`, `qwen3.5-plus`.\n- **Privacy**: официально «will never use your data for model training», данные в Сингапуре.\n- **После 90 дней**: paid-only.\n- **В конфиг**: `kind: dashscope` — нативно поддерживается, см. секцию #15 выше для деталей.\n\n### DeepSeek direct — 5M signup credits + off-peak 50-75%\n\n- **Регистрация**: https://platform.deepseek.com (phone verify)\n- **Signup**: 5M токенов + 7-14 дней без rate limits\n- **Off-peak**: 16:30-00:30 UTC — **50% скидка на V3, 75% на R1**. Годится для batch-задач, не для realtime-чата.\n- **Privacy-блокер**: данные хранятся в Китае, политика допускает использование для обучения → **не использовать с PII**.\n- **В конфиг**: `kind: deepseek` — нативно поддерживается, см. секцию #14 выше для деталей.\n\n### Anthropic Claude direct — $5 signup\n\n- **Регистрация**: https://console.anthropic.com (phone verify)\n- **Signup**: $5 кредитов на 30 дней после phone verify\n- **Зачем**: единственный способ добавить frontier Claude Sonnet/Opus в цепочку без Bedrock/Databricks\n- **Нюанс**: Anthropic API не OpenAI-compat — нужен отдельный `kind: anthropic`. В neurogate **пока не реализован**.\n\n### OpenAI direct — единоразово $5 ради бесплатной модерации (text + image)\n\n**TL;DR — зачем подключать OpenAI вообще:** ради **бесплатной модерации**. Текстовая (`text-moderation-latest`) и multimodal text+image (`omni-moderation-latest`) у OpenAI **бесплатны навсегда** и качественнее всех альтернатив. Платные модели ($0.05–$10 per 1M токенов) — опционально, если иногда понадобится высокое качество в `paid` chain. **На бесплатные chat / embed / image-gen цепочки OpenAI подключать не нужно** — у Groq / Gemini / Z.ai лимиты щедрее и без депозита.\n\n**Регистрация:**\n\n- https://platform.openai.com (Google / Microsoft / email)\n- https://platform.openai.com/api-keys → *Create new secret key*\n- **ENV**: `OPENAI_API_KEY` (для бесплатной модерации) и опционально `OPENAI_API_KEY_PAID` (для paid-моделей; можно тот же ключ — разделение нужно лишь чтобы случайно не сжечь baseline-баланс)\n\n**Критично — почему без $5 ничего не работает:**\n\nНа Free tier (без привязанной карты) OpenAI режет **все** запросы через `429 Too Many Requests` с `type: invalid_request_error` — **включая бесплатную модерацию**. Это не rate-limit моды, это аккаунт-уровневая блокировка. В ответе нет ни одного `x-ratelimit-*` хедера — это диагностический признак, что блок именно account-level, а не лимит модели. Лечится только депозитом.\n\n**Депозит — единоразово $5:**\n\n1. https://platform.openai.com/settings/organization/billing/overview → *Add payment details*\n2. Введи **`5`** в *Initial credit purchase* (минимум).\n3. ⚠️ **Снять галочку *Automatically add credits when your balance runs low***. По умолчанию она включена. Если оставить — карта будет молча докидывать $5 каждый раз когда баланс упадёт. Это главная ловушка для тех, кто хотел «только бесплатно».\n4. Подтвердить (банк может попросить 3DS).\n5. За 1-5 минут Tier поднимается `Free` → `Tier 1`, лимиты на moderation вырастают с 3 RPM до ~500 RPM.\n\n**Где следить за лимитами и расходом:**\n\n- **Rate limits per model** (RPM/RPD/TPM): https://platform.openai.com/settings/organization/limits — таблица с текущим тиром и лимитами по каждой модели. Полезно проверить после оплаты, что Tier действительно поднялся до 1.\n- **Usage (расход токенов и запросов):** https://platform.openai.com/usage — графики по дням/моделям, что именно сжигало баланс. Здесь же видно, что moderation идёт нулевой строкой.\n- **Billing & balance:** https://platform.openai.com/settings/organization/billing/overview — текущий остаток депозита, история платежей, настройки auto-recharge.\n\n**Стратегия использования $5:**\n\n- **Основной use-case (бесплатно):** модерация — `omni-moderation-latest` (text+image, 13 категорий) и `text-moderation-latest` (legacy text-only, 7 категорий) **не списываются с баланса**. $5 просто лежат бессрочно.\n- **Опционально (платно):** редкие вызовы `paid` chain через `gpt-5-mini` для случаев когда бесплатные провайдеры упёрлись или не справляются с качеством. При умеренном трафике $5 хватает на месяцы.\n- **Не подключать:** chat / embed / image_gen цепочки — у бесплатных провайдеров (Groq / Gemini / Z.ai / Cohere / Voyage / Cloudflare / Pollinations) лимиты на порядки больше.\n\n**Бесплатно после депозита:**\n\n| Модель | Что делает | Цена |\n|---|---|---|\n| `omni-moderation-latest` | Text + image moderation, 13 категорий, native scores | $0 / $0 |\n| `text-moderation-latest` | Legacy text-only, 7 категорий | $0 / $0 |\n\nВ neurogate реализованы как `kind: openai_moderation` в [config.py:118](../src/neurogate/config.py#L118), провайдер [`OpenAIModerationProvider`](../src/neurogate/providers.py#L3205). Обе уже в дефолтных цепочках `moderation` и `moderation_image`.\n\n**Платные модели — опциональный subset для `paid` chain (используя `OPENAI_API_KEY_PAID`):**\n\n| Модель | Цена in/out (per 1M) | Когда нужна |\n|---|---|---|\n| `gpt-5-mini` | $0.25 / $2.00 | Основной paid-fallback. Уже добавлен во вторую позицию `paid` после Claude Opus. |\n| `gpt-5-nano` | $0.05 / $0.40 | Если нужен ультра-дешёвый paid-fallback. На простых запросах хватает. |\n| `gpt-4.1-mini` | $0.40 / $1.60 | **1M контекст** — для длинных документов / RAG. Подключать только если упираешься в context window других моделей. |\n| `whisper-1` | $0.006/мин | STT-fallback после Groq Whisper. Только если делаешь транскрипцию серьёзных объёмов. |\n\n**Не брать:** `o3` (есть `o4-mini` в 4× дешевле), `dall-e-3` (устарел против `gpt-image-1`), `gpt-4o` / `gpt-4o-mini` (`gpt-5-mini`/`nano` дешевле и не хуже), `text-embedding-3-small/large` (Voyage даёт 200M tok permanent free на каждую модель — OpenAI embeddings подключать смысла мало), `gpt-image-1` (Kandinsky / YandexART лучше на фотореализме, см. отдельную заметку).\n\n**В конфиге:** OpenAI-нативный endpoint `https://api.openai.com/v1` — `kind: openai` для chat (`gpt-5-mini` и др.), `kind: openai_moderation` для модерации. Конкретные провайдеры см. в [config.yaml](../config.yaml) (`openai:moderation`, `openai:text-moderation`, `openai:gpt-5-mini`).\n\n## После получения ключей\n\n1. Скопировать: `cp .env.example .env`\n2. Вписать ключи в `.env` (пустые строки neurogate просто пропустит — провайдеры без ключа исключаются из цепочки)\n3. Запустить: `uv run neurogate`\n4. Проверить, какие провайдеры реально доступны: `curl -s -H \"Authorization: Bearer $TOKEN\" http://127.0.0.1:8765/v1/models`\n\nЕсли провайдер упирается в 429 — neurogate автоматически перейдёт к следующему. Если все упали — вернётся HTTP 502 `upstream_exhausted` (на free-тирах в сумме с 1 ключа это ~20-25k сообщений/сутки, так что до потолка надо постараться).\n\n## Если что-то не работает — как сообщить о баге\n\nБез следующих данных мы не можем отделить баг шлюза от проблемы провайдера / твоего соединения / клиента, и фикс затягивается на дни. Скинь всё одним сообщением:\n\n### Чек-лист (минимум)\n\n- [ ] **Что произошло** — одна-две фразы. Что должно было быть, что получилось вместо.\n- [ ] **Скриншот или видео** — обязательно. На скрине должно быть видно: само сообщение об ошибке, время, и (если применимо) URL/endpoint.\n- [ ] **Текст ошибки целиком** — копи-паст, не пересказ. Если приложение режет текст — скрин консоли / network tab из DevTools.\n- [ ] **Когда произошло** — точное время с часовым поясом (например, `2026-05-09 14:32 МСК`). Это нужно чтобы найти запись в логах.\n- [ ] **Что делал до ошибки** — последовательность действий. Например: «открыл Cursor → задал вопрос про код → пошёл стрим, на 3-й секунде оборвался». Или: «отправил длинный документ через Continue → сразу 502». **Воспроизводится повторно или один раз?**\n- [ ] **Тип соединения**:\n - Wi-Fi (домашний роутер / офис / публичный)\n - мобильный интернет (4G/5G)\n - смешанно (когда переключался с одного на другое — отметь)\n- [ ] **Провайдер/оператор**:\n - для мобильного: МТС / Мегафон / Билайн / Tele2 / Yota / другой\n - для домашнего: Ростелеком / МТС / Билайн / ТТК / Дом.ру / другой\n - если за VPN — **обязательно укажи**, какой VPN и какая страна выхода\n- [ ] **Город** (грубо — Москва / СПб / регион / зарубежье). Не для слежки, а потому что некоторые провайдеры блокируют upstream-эндпоинты только в части регионов.\n- [ ] **Какой клиент** и его версия:\n - Cursor / Claude Code / Continue / Cline / Aider / curl / собственный скрипт / браузер\n - версия (например, `Cursor 1.4.2`)\n- [ ] **Какая модель / chain** была запрошена — посмотри в настройках клиента, поле `model:`. Например: `auto`, `chat`, `deepseek:reasoner`, `paid`.\n\n### Желательно (если можешь)\n\n- **Request ID** — если ошибка вернулась с шлюза (HTTP-ответ), там в headers должен быть `x-request-id`. Скинь его — найдём конкретный запрос в логах за миллисекунды.\n- **Скрин Network tab** браузера или вывод `curl -v` — видны заголовки и точный путь.\n- **Размер промпта** — короткий вопрос или длинный документ на 50K токенов? Длинный context часто выявляет баги, которых нет на коротком.\n- **Stream или non-stream** — обычно стрим по умолчанию, но некоторые клиенты выключают.\n\n### Шаблон сообщения\n\nСкопируй и заполни:\n\n```\nЧто произошло:\nСкриншот/видео: (приложить файл)\nТекст ошибки:\n <вставить текст>\nКогда: 2026-05-09 HH:MM МСК\nЧто делал до:\nВоспроизводится: да / нет / иногда\nСоединение: Wi-Fi / мобильный\nОператор:\nVPN: нет / да (страна: ...)\nГород:\nКлиент: ... версия ...\nМодель/chain:\nRequest ID:\n```\n\n### Почему мы спрашиваем про оператора\n\nllmgate за собой держит 15+ upstream-провайдеров (Groq, Cerebras, SambaNova, Gemini, OpenRouter, DeepSeek, …). Часть из них **блокируется или режется на уровне отдельных российских операторов** — эта блокировка не от шлюза, а от твоего ISP. Признаки: connection reset / timeout / SSL handshake fail на конкретный домен. На разных операторах живут разные подмножества upstream'ов:\n\n- МТС иногда режет HuggingFace и часть Cloudflare-эндпоинтов\n- Мегафон блокирует часть Google IP-блоков → Gemini нестабильна\n- Ростелеком блокирует часть международного трафика по DPI\n- Из мобильного интернета бывает странный SNI-фильтр\n\nБез информации про оператора мы будем час крутить логи в поисках бага в коде, которого нет.\n"}}}} |