API-провайдеры

Снимок: 2026-10-11. Секция хаба AI & Agents, тайл «API» / «API», подпись «Провайдеры API, ключи и каталоги моделей». Доступен всегда.

Экраны и навигация

• Screen.ApiProviders → ProvidersScreen (470 строк) — список.
• Screen.AddEditProvider(providerId?, presetSlug?, startAtModels?) → ProviderFormScreen — форма добавления/правки; startAtModels открывает её сразу на моделях (тап по полоске моделей в карточке).

Возможности (подробно)

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

• Карточка ProviderCard (314 строк): статус (providerStatus + providerStatusReason), хост (providerHost), ключ маскирован (providerKeyLabel), число моделей, время последнего теста (lastTestEpochMillis/lastTestLabel).
• Метрики расхода: ProviderUsageRow, UsageMiniBar, ProviderQuotaRow — окна квот, quotaWindowLabel, quotaResetEpochMillis, formatQuotaRemaining, quotaHistoryPercents (спарклайн), UsageSparkline.
• Баланс DeepSeek: ProviderBalanceRow на карточке и ProviderBalanceSheet (// balance) — providerIsDeepSeek, providerHasBalance, balanceStatusLabel, balanceTotalLabel; ApiQuotaBalanceDto хранит currency/total/granted/toppedUp строками.
• Фильтр/поиск (providerMatchesQuery), группировка секций (providerSections).
• Управление: toggle (вкл/выкл), delete, quickTest (быстрый тест из списка), testModel (тест конкретной модели), loadQuotas/refreshQuota.
• Пустое состояние EmptyProviders.

Форма провайдера (ProviderFormScreen, шаги)

1. Connection (ConnectionStep) — пресет (applyPreset), имя, slug, base URL, protocol, API-ключ; валидация validateSetup.
2. Models (ModelsStep) — обнаружение моделей (discover → /providers/{id}/discover), выбор, компактные строки с раскрываемым редактором контекста и флагов.
3. Test (TestStep) — runTest (/providers/{id}/test), выбор тестовой модели.

• buildRequest собирает ProviderSaveReq.
• Save закреплён в нижней панели и доступен с любого шага; тест не обязателен.

Vision-модели

• Ручной флаг зрения живёт на экране Vision: пикер «+ модель» сохраняет vision=true через тот же save, а экран провайдера показывает флаг только бейджем.

Инсайты по моделям (ProviderInsights.kt)

modelFamily, modelVersion, compareModelVersions (сравнение версий), providerModelIdsSorted, providerModelsSorted, providerModelsPreview, formatContext (размер контекста).

Диалоги и листы

• TestModelDialog, DiscoverModelsDialog (ProviderDialogs).
• ProviderActionsSheet — действия над провайдером.
• ProviderUsageSheet (199) — подробные окна расхода, UsageWindowCard.

Где в коде

Данные и API

Репозиторий: data/repo/ApiProvidersRepository.kt.

Плюс data/api/ApiProviderDtos.kt — DTO. Провайдер с промпт-триггером PROVIDERS_PROMPT = "y83@providers" (агент может открыть экран).

Агент

MCP-тулы

• ai_status — провайдеры и аккаунты веб-ИИ, квоты, статистика (косвенно видит и API-провайдеров через роутер).
• ai_ask(model, provider) — спросить модель этого провайдера.
• image_generate(model) / image_edit(source_id|source_path|source_url) — генерация и правка картинок (не провайдер API, а отдельный сервис y83.media). Правка умеет PNG-маску (mask_path/mask_url), прямоугольники (mask_region), outpaint (anypaint_padding) и перенос стиля референсом (style_refs); рядом стоят image_status / image_jobs / image_cancel / image_quota. Тот же путь доступен человеку в окне правки просмотрщика — полный контракт в ../../tech/image-generation.md.

Как агент пользуется

1. Экран настраивает провайдера (ключ, base URL, модели).
2. Роутер (internal/providers/router.go) выбирает провайдера для запроса.
3. Агент зовёт ai_ask с provider:/model: — роутер идёт в нужный API.

Подводные камни

• Ключ хранится на backend. Приложение получает маскированный (providerKeyLabel); полный ключ не покидает backend.
• discover требует рабочего ключа — без него список моделей пуст. Ошибка апстрима приходит с HTTP 200 и ok:false (как у test), поэтому экран показывает её, а не падает на ApiException.
• Vision-флаг ручной. Если модель умеет видеть, но не помечена — агент её не выберет (Vision опирается на этот флаг + автоопределение).
• Квоты приходят от провайдера. Не все API дают квоту — бывает providerStatusReason с объяснением.
• Выключенный провайдер не участвует в роутере, но остаётся в списке.
• probe и test — разные вещи: probe запрашивает GET /models, test — шлёт один реальный запрос к модели. Оба принимают providerId, чтобы черновик формы не терял сохранённый ключ, и отдают результат с HTTP 200 (ok:false при ошибке провайдера).

Как обновлять

• Каталог: data/InstrumentCatalog.kt (id api).
• Маршрут: ui/navigation/Screen.kt (Screen.ApiProviders, Screen.AddEditProvider).
• Код: ui/providers/*.
• Репозиторий: data/repo/ApiProvidersRepository.kt.
• API: data/api/BackendApiProviders.kt, ApiProviderDtos.kt, роуты — backend/internal/api/v1/routes.go.
• Роутер моделей: backend/internal/providers/router.go.