Если ваша команда уже использует CC Switch или контрольную плоскость в стиле NewAPI, самый быстрый способ включить Gemini — не добавлять еще одни учетные данные провайдера везде. Вместо этого нужно определить один upstream-маршрут, одно правило именования моделей, одну проверку использования и один production-этап ревью перед выкатыванием.
Google теперь документирует доступ к Gemini через библиотеки OpenAI, изменяя API key, base URL и имя модели. Для прямого доступа к Gemini OpenAI-совместимый base URL — https://generativelanguage.googleapis.com/v1beta/openai/. Для команд, которым нужен один операционный слой для Gemini и других провайдеров, Flatkey предоставляет один OpenAI-совместимый маршрут по адресу https://router.flatkey.ai/v1, а текущий текст на главной странице делает акцент на одном ключе, одном base URL и использовании вашего существующего SDK.
Это руководство предназначено для production-приложений, а не для любительских демо. Цель — помочь вам подключить Gemini так, чтобы решение можно было проверить со стороны engineering, operations и security до переключения трафика.
Краткий ответ: что должно измениться в production?
Для production-внедрения Gemini API зафиксируйте пять вещей до сохранения upstream:
| Пункт | Прямое подключение Gemini | Подключение через один gateway для клиентов CC Switch или NewAPI-стиля |
|---|---|---|
| Источник аутентификации | API key Gemini из Google AI Studio или импортированного проекта Google Cloud | Один ключ gateway, управляемый в одном месте |
| Base URL | https://generativelanguage.googleapis.com/v1beta/openai/ | https://router.flatkey.ai/v1 |
| Режим протокола | OpenAI-compatible | OpenAI-compatible |
| Политика моделей | Одобренный список моделей Gemini | Одобренный список моделей Gemini плюс политика fallback между провайдерами |
| Проверка | Проверка использования и биллинга на стороне Google | Лог запросов gateway, quota, сопоставление моделей и downstream-review |
Если ваше приложение уже поддерживает upstream, совместимые с OpenAI, Gemini обычно требует настройки маршрутизации и политики, а не полной переписывания SDK.
Почему этот чек-лист важен в пятницу, 17 июля 2026 года
Три текущих факта делают production-чек-лист важнее, чем quickstart:
- В документации Gemini от Google теперь явно поддерживается доступ через библиотеки OpenAI, что упрощает для команд смену endpoint'ов без ужесточения дисциплины ревью.
- Google также указывает, что новые ключи AI Studio по умолчанию создаются как auth keys и что стандартные ключи будут отклоняться в сентябре 2026 года, поэтому тип ключа и владение проектом являются частью решения о запуске.
- Текущая публичная формулировка настройки Flatkey делает акцент на одном ключе, одном base URL и использовании существующего SDK, что полезно только если команда также стандартизирует сопоставление полей, логирование и откат.
Перед началом
Не открывайте сначала CC Switch или NewAPI. Начните с контракта, которому должен соответствовать upstream.
Используйте этот минимальный preflight-список:
| Проверка | Что подтвердить | Почему это важно |
|---|---|---|
| Ответственный | Команда знает, кто отвечает за создание ключей Gemini, их ротацию и квоты | Предотвращает рассогласование при использовании общей учётной записи |
| Тип маршрута | Вы используете upstream, совместимый с OpenAI, а не смешанный кастомный адаптер | Сохраняет простое сопоставление полей |
| Список моделей | У вас есть утверждённый список ID моделей Gemini для этого приложения | Предотвращает незаметный дрейф алиасов |
| Логирование | Вы знаете, где будут просматриваться логи запросов, использование и биллинг | Нужно для подтверждения cutover |
| Откат | Вы можете быстро вернуть upstream или политику модели обратно | Требуется для поэтапного развёртывания |
Если у вас нет ответов на эти вопросы, вы не готовы считать настройку production-ready.
Сопоставление полей для CC Switch или upstream'ов в стиле NewAPI
Разные клиенты по-разному называют поля, но production-сопоставление должно оставаться единообразным.
| Поле upstream | Значение для этого развёртывания | Примечание для проверки |
|---|---|---|
| Тип провайдера | OpenAI-compatible | Используйте универсальный режим OpenAI-compatible, если только у клиента нет валидированного Gemini-native режима, который вы планируете использовать |
| API-ключ | Flatkey key или утверждённый ключ upstream | Храните его в одном источнике секретов, а не в локальных копиях у каждого пользователя |
| Base URL | https://router.flatkey.ai/v1 | Используйте один маршрут для централизованного контроля |
| Источник модели | Ручной allowlist или получение после сохранения маршрута | Проверьте возвращённые ID моделей, прежде чем открывать их приложению |
| Модель по умолчанию | Утверждённая production-модель Gemini | Не направляйте production случайно на preview-модель |
| Fallback-модель | Опционально и осознанно | Включайте только после того, как пройдут проверки именования модели и логов |
| Заголовки | Стандартная bearer-аутентификация, если только в документации клиента не указаны дополнительные поля | Избегайте разовых хаков с заголовками, которые ломают переносимость |
| Проверка использования | Лог запросов плюс панель квот или биллинга | Должно быть частью утверждения |
Это ключевое операционное различие между прямой настройкой Gemini и настройкой через gateway: путь через gateway снижает разрастание учётных данных, но повышает необходимость в чистом этапе проверки, потому что больше приложений может унаследовать один и тот же upstream.
Шаг 1: решите, нужен ли этому приложению прямой Gemini или один gateway
Используйте прямой Gemini, если приложение изолировано, ответственный понятен и вам сейчас не нужна маршрутизация между провайдерами.
Используйте один gateway, если верно хотя бы одно из следующего:
- Этот же клиент уже работает с несколькими провайдерами.
- Интеграцией будут управлять более одного инженера или команды.
- Вы хотите иметь одно место для проверки использования, квот или логов запросов.
- Позже вы ожидаете подмену модели, fallback или расширение числа провайдеров.
Для команд, использующих CC Switch и подход NewAPI, второй путь обычно проще сопровождать со временем, потому что клиент сохраняет одну OpenAI-совместимую структуру, а политика маршрутизации остаётся upstream.
Шаг 2: зафиксируйте точные ID моделей Gemini, которые вы разрешите
Не используйте «Gemini» как расплывчатое требование. Утвердите точные ID моделей для этого приложения и этой среды.
Этот обзор должен ответить на вопросы:
- Какая модель Gemini является производственной по умолчанию?
- Какие модели разрешены только для тестирования?
- Разрешены ли preview-модели в production вообще?
- Будет ли приложение показывать выбор модели или использовать одну фиксированную модель?
- Если включён fallback, какие не-Gemini модели допустимы и при каком условии?
Именно здесь многие команды создают инциденты, которых можно было избежать. Они корректно сохраняют upstream, а затем оставляют именование моделей достаточно размытым, чтобы тестовая и production-среда работали по-разному.
Если вам нужна помощь в согласовании названий моделей после того, как route уже запущен, изучите существующее руководство OpenAI-Compatible API Migration перед тем, как открывать интеграцию пользователям.
Шаг 3: сохраните один upstream и выполните smoke test перед загрузкой списка моделей
После ввода API key и base URL выполните один smoke test, прежде чем импортировать или показывать полный список моделей.
Ваш smoke test должен подтвердить:
| Тест | Ожидаемый результат |
|---|---|
| Auth | Upstream принимает ключ без локальных ошибок учётных данных |
| Route | Простой запрос chat completion возвращается с настроенного base URL |
| Model | Точный ID модели Gemini успешно разрешается |
| Logging | Вы можете найти запрос в выбранной вами зоне проверки |
| Billing or quota | Запрос виден там, где команда ожидает подтверждение использования |
Для команд, стандартизирующихся на одном gateway, это важнее, чем загрузка списка моделей. Загрузка списка моделей доказывает, что клиент видит названия. Она не доказывает, что путь production-запроса поддаётся проверке.
Шаг 4: проверьте тип ключа и владение проектом
Этот шаг легко пропустить, потому что запрос уже может работать.
Текущие рекомендации Google по ключам — причина не пропускать его. Google AI Studio теперь по умолчанию создаёт auth key, неограниченные standard keys уже ограничиваются более жёстко, и Google заявляет, что Gemini API будет отклонять standard keys в сентябре 2026 года. Это означает, что production-команды должны рассматривать тип ключа как часть готовности к запуску, а не как задачу на более позднюю очистку.
Используйте этот короткий обзор:
| Вопрос | Допустимый ответ |
|---|---|
| Кому принадлежит проект Gemini? | Указанный владелец или команда |
| Какой тип ключа используется? | Для новых production-настроек предпочтителен auth key |
| Где хранится ключ? | Централизованный secret manager или контролируемый platform secret |
| Как будет происходить его ротация? | Документированный владелец и процесс |
| Что происходит при всплеске использования? | Существует путь для billing alert или проверки quota |
Если вы централизуете трафик через один шлюз, проведите такой же анализ для ключа шлюза и учетной записи downstream-провайдера.
Шаг 5: решите, должна ли приложение напрямую показывать Gemini пользователям
Не стоит заранее считать, что ответ — да.
Во многих production-приложениях более удачный подход такой:
- Сначала направляйте Gemini upstream.
- Проверьте логи, задержки и обзор использования.
- Держите модель за feature flag или во внутреннем allowlist.
- Открывайте ее конечным пользователям только после прохождения review-gate.
Это особенно полезно в окружениях в стиле CC Switch и NewAPI, где одно изменение конфигурации может повлиять на нескольких операторов или путей приложения.
Шаг 6: добавьте review-gate для production
Именно эту часть большинство гайдов по настройке опускают. До переноса трафика требуйте короткий review-gate, который кто-то сможет одобрить за один проход.
Используйте этот точный чек-лист:
| Пункт review-gate | Условие прохождения |
|---|---|
| Сопоставление полей | Источник API key, base URL, режим провайдера и модель по умолчанию задокументированы |
| Доказательство smoke test | Зафиксирован один успешный запрос с конечным маршрутом |
| Allowlist моделей | Для приложения доступны только одобренные идентификаторы моделей Gemini |
| Видимость использования | Подтвержден путь к журналу запросов или проверке биллинга |
| Владение секретом | Указаны владелец ключа и путь его ротации |
| Rollback | Можно быстро восстановить предыдущую upstream- или model policy |
| Область действия | Команда знает, затрагивает ли это изменение одно приложение, одно workspace или многих клиентов |
Это самый короткий документ по настройке, который все еще защищает релиз.
Шаг 7: решите, как должен работать fallback, до того как включать его
Если вы используете один шлюз, возникает соблазн немедленно включить fallback. Не делайте этого, если не можете ответить на два вопроса:
- Какое условие сбоя должно запускать fallback?
- Приемлемо ли поведение fallback-модели для той же пользовательской задачи?
Для production-раскаток Gemini fallback часто безопаснее добавлять после первого cutover, а не во время него. Сначала подтвердите основной маршрут, затем добавьте fallback с собственными доказательствами тестирования.
Шаг 8: проверьте маршрут из приложения, а не только из локального скрипта
Локальный тест через curl необходим. Но его недостаточно.
Выполните одну проверку по реальному пути приложения и подтвердите:
- Приложение использует нужный upstream.
- Возвращаемая модель — ожидаемая модель Gemini.
- Наблюдаемость показывает тот же запрос.
- Любое поведение на уровне приложения для timeout, retry или quota по-прежнему работает.
Именно здесь появляются проблемы production, когда у приложения старые переменные окружения, кэшированные имена моделей или другой источник секрета, чем у инженера, который запускал первый тест.
Рекомендуемая схема rollout для команд в стиле CC Switch и NewAPI
Используйте поэтапный rollout, который сохраняет control plane простым:
- Добавьте один upstream, совместимый с OpenAI и поддерживающий Gemini.
- Протестируйте одну одобренную модель Gemini.
- Подтвердите логи и проверку использования.
- Предоставляйте доступ к модели только внутренним пользователям.
- Добавляйте fallback только после того, как основной маршрут станет стабильным.
- Расширяйте доступ на большее количество приложений только после того, как первое приложение пройдет контрольную проверку.
Сообщение о live routing от Flatkey полезно здесь, потому что тот же базовый URL может оставаться без изменений, пока ваша политика в отношении модели со временем становится строже. Если вы сравниваете влияние на стоимость или закупки до запуска, актуальная страница с ценами — это следующий правильный шаг.
Краткий документ по настройке, который можно утвердить внутри компании
Если вам нужна передаваемая на ревью инструкция, скопируйте эту структуру в вашу внутреннюю заметку по настройке:
| Поле | Значение |
|---|---|
| Название приложения | |
| Ответственный за upstream | |
| Режим провайдера | Совместимый с OpenAI |
| Базовый URL | https://router.flatkey.ai/v1 |
| Источник API-ключа | |
| Одобренные ID моделей Gemini | |
| Fallback включен | Да или Нет |
| Поверхность для проверки использования | |
| Поверхность для проверки биллинга или квоты | |
| Действие при откате | |
| Ревьюер | |
| Дата утверждения |
Этого достаточно, чтобы утвердить rollout Gemini, не превращая настройку в длинную архитектурную записку.
Если ваша команда также использует Claude Code в той же плоскости управления, статья CC Switch Claude Code setup with Flatkey and NewAPI может быть полезным дополнением, потому что она показывает тот же операционный шаблон со стороны клиента.
FAQ
Какой шаблон базового URL является самым безопасным для production-rollout Gemini в клиенте, совместимом с OpenAI?
Самый безопасный шаблон — один утвержденный базовый URL для каждой среды. Для прямого доступа к Gemini Google документирует https://generativelanguage.googleapis.com/v1beta/openai/. Для rollout через централизованный gateway используйте один одобренный маршрут gateway и держите это значение под контролем конфигурации.
Нужно ли использовать отдельный credential Gemini для каждого клиента CC Switch или NewAPI?
Обычно нет. Для production-команд один контролируемый источник секрета безопаснее, чем разрозненные локальные учетные данные. Компромисс в том, что вам нужно добавить контрольную проверку, потому что большее число клиентов может унаследовать тот же маршрут.
Нужно ли заменять мой SDK, чтобы использовать Gemini в приложении, совместимом с OpenAI?
Обычно нет. В текущей документации Google по Gemini прямо поддерживаются библиотеки OpenAI путем изменения ключа, базового URL и имени модели. Реальная работа заключается в проверке политики маршрута, именования модели, логирования и ответственности.
Что изменилось в Gemini API keys в 2026 году?
По состоянию на пятницу, 17 июля 2026 года, Google AI Studio по умолчанию создает новые ключи как auth keys, предупреждает, что стандартные ключи без ограничений не подходят для долгосрочного использования, и сообщает, что Gemini API будет отклонять стандартные ключи в сентябре 2026 года. Командам следует проверить тип ключа перед переводом в production.
Когда следует включать fallback для Gemini?
После того как основной маршрут Gemini станет стабильным. Сначала проверьте одну утвержденную модель Gemini через финальный путь приложения. Затем добавляйте fallback только если условие срабатывания и поведение резервной модели приемлемы для того же рабочего процесса.
Что следует проверить перед утверждением документации по настройке?
Проверьте точный базовый URL, источник ключа, утвержденные идентификаторы моделей Gemini, один успешный лог запроса, область проверки использования и действие отката. Если чего-либо из этого не хватает, настройка не готова к утверждению для production.
