Ключ Google AI Studio нужен для аутентификации запросов к Gemini Developer API. Он не покупается как лицензия, не заменяет подписку Gemini и не создаёт отдельный запас запросов. Ключ всегда связан с Google Cloud-проектом, поэтому важно контролировать не только строку секрета, но и сам проект.
Для русскоязычного пользователя есть обязательный шаг до регистрации. В проверенном 29 августа 2026 года официальном списке регионов Google AI Studio и Gemini API России нет. На той же странице указаны возраст 18+ и возможная проверка возраста. Если ваше фактическое использование не соответствует текущим условиям, прямой Developer API-маршрут следует остановить. Чужой аккаунт, фиктивный адрес, VPN или купленный «Google key» не превращают неподходящий аккаунт в допустимый.
Дальнейшие действия относятся только к пользователю, который реально находится в поддерживаемом регионе и выполняет требования аккаунта, организации и применимых условий.
Что должно принадлежать вам
Откройте страницу API Keys в Google AI Studio под аккаунтом, который должен управлять интеграцией. Для личного прототипа это может быть личный проект. Для команды заранее определите владельца проекта, администратора IAM, плательщика и ответственного за ротацию.
Согласно актуальной документации по ключам Gemini API, новый пользователь после принятия условий может получить проект и ключ по умолчанию. Если у аккаунта уже есть Cloud-проекты, AI Studio может не создать default project: нужный проект импортируется через Dashboard → Projects, после чего ключ создаётся на странице API Keys.
Перед созданием запишите project ID. Похожее имя проекта легко перепутать, а ID позволит позже сопоставить ключ с billing, usage, quota и развёрнутым сервисом.
Если кнопка создания недоступна, сохраните точный текст сообщения и проверьте выбранный проект. Для создания текущего ключа Google перечисляет разрешения на чтение проекта, создание ключа, включение сервиса, создание service account и binding ключа. Запрашивайте у администратора только необходимую роль; не используйте чужой ключ как замену IAM.
Почему старое руководство про standard key уже опасно
Новые ключи AI Studio создаются как authorization keys, связанные с service account. В столбце Key Type можно увидеть тип текущей записи. Google переводит Gemini API со standard keys на auth keys и в текущем документе назначает отказ от standard keys на сентябрь 2026 года.
Это изменяемый срок, поэтому перед миграцией нужно перечитать официальный документ. Нельзя считать мартовский скриншот или старый ролик постоянным контрактом. Если старый ключ отмечен как standard, unrestricted или blocked, создайте текущий тип в контролируемом проекте и запланируйте ротацию вместо повторной публикации старого секрета.
Сохраните ключ, не показывая его
Ключ даёт доступ к квоте проекта и при включённом billing может создавать расходы. Его нельзя размещать:
- в Git и истории коммитов;
- в production JavaScript, мобильном приложении или публичном расширении;
- в issue, полном дампе окружения, скриншоте и записи терминала;
- в URL, который попадёт в логи и аналитику.
Для локального окружения Google SDK распознаёт GEMINI_API_KEY и GOOGLE_API_KEY. Если установлены обе переменные, приоритет имеет GOOGLE_API_KEY.
bashexport GEMINI_API_KEY="YOUR_API_KEY"
В рабочей системе храните значение в server-side secret manager, а клиент пусть обращается к вашему backend. Наличие переменной можно проверить без вывода значения:
bashtest -n "${GEMINI_API_KEY:-}" \ && echo "GEMINI_API_KEY задан" \ || echo "GEMINI_API_KEY отсутствует"
Canary: один текущий запрос
Актуальный get-started Google показывает Interactions API и модель gemini-3.7-flash. Минимальный вызов передаёт секрет в заголовке:
bashcurl -sS -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3.7-flash", "input": "Коротко подтвердите, что API-соединение работает." }'
Успешный результат — структурированный interaction с завершённым статусом и output. Конкретная фраза модели не важна. Важно, что запрос ушёл на ожидаемый hostname, аутентифицировался нужным ключом и вернулся с успешным состоянием.
Модели и API surface меняются. Если текущий quickstart уже использует другое имя, обновите canary по первичному документу, а не подбирайте ID наугад.
Как читать ошибку, не перебирая ключи
Зафиксируйте HTTP status, обезличенное body, project ID, endpoint, model, UTC-время и request ID. Полный ключ не сохраняйте. Затем меняйте только один параметр.
| Наблюдение | Что проверять первым | Следующее действие |
|---|---|---|
| AI Studio не открывает управление ключами | Регион, возраст, verification, policy аккаунта | Сверить официальный список; остановить неподходящий direct route |
| Нельзя создать ключ | Project import и IAM | Подтвердить project ID и требуемые разрешения |
403 PERMISSION_DENIED | Активный ключ, проект, restriction или действие | Использовать пошаговую диагностику 403 |
429 RESOURCE_EXHAUSTED | Live limit выбранного проекта/модели/tier | Открыть AI Studio и руководство по лимитам |
| Model/route not found | Текущий model ID и версия API | Повторить официальный пример один раз |
| Временная ошибка сервера | Состояние сервиса и retry | Ограниченный exponential backoff без нового ключа |
Работающий canary не гарантирует production capacity. Бесплатный режим распространяется только на часть моделей и режимов, а фактические лимиты видны в AI Studio для конкретного проекта. Несколько ключей одного проекта не создают несколько quota pool.
Решение о Free, Paid, Prepay и стоимости следует принимать после успешной проверки. Для этого используйте отдельный разбор цены и маршрутов Gemini API и актуальную официальную pricing page. Перед production запишите project ID, владельца, тип ключа, место секрета, план ротации, разрешённый backend, модель, live limits и billing status.
