API-ключ Google AI Studio: создайте ключ, а затем проверьте 6 условий запуска

Сначала создайте Gemini API key в Google AI Studio. Сам факт создания ключа означает только одно: у вас появилась строка учетных данных. Он еще не доказывает, что первый запрос к Gemini API пройдет успешно. Работоспособность зависит от Google Cloud проекта, региона, billing или Free Tier, выбранной модели, active limits и того, не был ли ключ уже раскрыт или ограничен.

Перед кодом проверьте шесть вещей:

Где создавать API-ключ Google AI Studio

Официальный путь начинается в Google AI Studio API Keys. Войдите в Google-аккаунт, выберите или создайте Google Cloud проект, затем создайте Gemini API key. Документация Using Gemini API keys фиксирует главный принцип: для Gemini API нужен API key, а создавать и управлять такими ключами нужно через Google AI Studio.

Выбор проекта важнее кнопки копирования. API key — не отдельный пароль без контекста. За ним стоит проект, владельцы, billing state, история usage, лимиты и путь восстановления. Если коллега прислал ключ из своего проекта, вы можете вызывать ту же модель, но расходовать другой бюджет, видеть другие лимиты и зависеть от другого администратора.

У новых пользователей Google может создать default project после принятия Terms of Service. Для первого теста это нормально, но рабочей команде все равно нужно знать название проекта, владельца и назначение: это временный прототип или проект для будущего production. Ошибка с default project часто приводит к тому, что разработчик смотрит quota в одном месте, а запросы идут через другой проект.

Ключ стоит скопировать один раз и сразу убрать из публичного кода. Для короткого локального теста можно передать ключ явно, но рабочая привычка должна быть другой: server-side environment variables, deployment secrets или secret manager. Не кладите ключ во frontend bundle, мобильное приложение, публичный репозиторий, скриншот, issue, ноутбук или чат.

Есть и граница интерфейса AI Studio. Он показывает unrestricted keys или ключи, ограниченные Generative Language API. Более тонкие API-key restrictions управляются в Google Cloud Console. Если ключ в проекте существует, но не выглядит как в учебном скриншоте, сначала проверьте проект и Cloud Console, а не создавайте дубликаты.

Какие 6 условий проверять после создания ключа

Большинство первых ошибок не лечится новым ключом. Обычно нужно проверить контракт, к которому ключ привязан.

Порядок проверки имеет смысл. Сначала проект, потому что все остальные панели относятся именно к нему. Затем регион, потому что неподдерживаемое место запуска не исправляется переписыванием кода. Потом billing и модель, потому что Free Tier и доступность модели не одно и то же. В конце — limits и безопасность: они часто объясняют ситуацию, когда вчера запрос проходил, а сегодня начал падать.

Если нужен глубокий разбор бесплатного tier и лимитов, используйте отдельный материал про Gemini API Free Tier. Здесь задача уже: безопасно создать ключ и доказать, что первый запрос действительно может пройти.

Как положить ключ в окружение и сделать первый запрос

Первый запрос должен быть минимальным. Его задача — проверить, что приложение читает ключ, вызывает актуальную модель и получает ответ без лишнего расхода токенов, concurrency и времени на отладку.

Для локального теста достаточно переменных окружения:

hljs bashКопировать
export GEMINI_API_KEY="реальный ключ хранится локально или на сервере"
export MODEL_ID="актуальный model ID из документации Google"

Минимальный curl может выглядеть так:

hljs bashКопировать
curl "https://generativelanguage.googleapis.com/v1beta/models/${MODEL_ID}:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          { "text": "Reply with one short sentence." }
        ]
      }
    ]
  }'

SDK может отличаться, но правило остается тем же: ключ читается из приватного окружения, prompt короткий, model ID берется из актуальной документации, а тест идет через тот же проект и тот же route, которые будут использоваться дальше. Файлы, tools, длинный контекст, очереди, retries и пользовательский трафик добавляйте только после чистого первого ответа.

Для frontend есть жесткая граница. Gemini API key — это credential, который может расходовать quota и показывать usage проекта. Не помещайте его в NEXT_PUBLIC_, client-side JavaScript, мобильный package, статический HTML или любой файл, который пользователь может скачать и посмотреть. Надежнее схема: браузер обращается к вашему backend, backend читает ключ из приватного окружения и вызывает Gemini API.

Бесплатное создание ключа не означает бесплатное использование

Google AI Studio может позволить создать ключ без платежа в момент создания. Но это не гарантия бесплатного доступа ко всем моделям, функциям, регионам и объемам трафика. Ключ аутентифицирует запрос, а usage принадлежит проекту.

Документация rate limits описывает ограничения вроде requests per minute, tokens per minute и requests per day. Эти лимиты относятся к проекту и состоянию модели, а не к каждой строке ключа. Несколько ключей внутри одного проекта полезны для rotation, разделения окружений и безопасности, но не являются способом умножить quota.

Документация billing разделяет Free Tier и Paid Tier. Free Tier может покрывать отдельные модели и условия. Paid Tier требует активного billing account и, на текущих setup-поверхностях, может требовать prepay, например 10 USD. Суммы, tier labels, credits и model rows меняются, поэтому перед запуском опирайтесь на актуальную billing-поверхность Google.

Free Tier подходит для обучения, прототипов и низкорисковых тестов. Production требует другой дисциплины: budget alerts, владелец проекта, логи, retry policy, data-handling review и план на повышенную quota или billing. Ключ, который сработал в демо, еще не является capacity plan.

Регион и 403 нужно отлаживать по конкретному route

Региональная доступность должна проверяться для той developer-поверхности, которую вы используете. Consumer Gemini, Google AI Studio, Gemini API, Vertex AI, Google Workspace и Android Studio tooling не являются одним контрактом.

Для настройки AI Studio и Gemini API используйте available regions. На 27 апреля 2026 года Taiwan указан в официальном списке Gemini API. Mainland China, Hong Kong и Macao не указаны в списке AI Studio / Gemini API. Это route-specific вывод, его нельзя автоматически переносить на consumer Gemini, Workspace или Vertex AI.

403 PERMISSION_DENIED лучше считать проблемой ownership и eligibility, а не сразу ошибкой кода. Документация troubleshooting указывает такие причины, как wrong key, insufficient permission, unsupported Free Tier region и authentication mismatch.

Если проблема шире и касается доступности Gemini в разных продуктах, используйте отдельный разбор регионов Gemini. Настройка API key должна оставаться в границах AI Studio, Gemini API, проекта и первого запроса.

Как восстанавливаться после 429, недоступной модели и утечки ключа

429 RESOURCE_EXHAUSTED обычно означает, что исчерпан один из лимитов. Это может быть request rate, token throughput, дневной объем, tier capacity или агрессивный retry loop. Быстрые повторы без backoff могут превратить небольшую quota-проблему в устойчивый отказ.

Восстанавливайтесь в таком порядке:

1. Убедитесь, какой Google Cloud проект стоит за ключом.
2. Откройте active limits в AI Studio для этого проекта.
3. Определите, уперлись ли вы в RPM, TPM, RPD или другой лимит.
4. Снизьте concurrency и добавьте exponential backoff.
5. Укоротите prompts, кэшируйте повторяющиеся запросы и остановите дублирующие retries.
6. Проверьте, что модель доступна при текущем billing и tier.
7. Запросите higher quota или переведите workload в billed project, если нормальный трафик продолжает упираться в лимиты.

С model errors нужна отдельная привычка. Не заменяйте один preview ID другим из видео или форума. Документация models является текущим источником имен и статусов. Важный пример: Gemini 3 Pro Preview был shut down 9 марта 2026 года, поэтому старые примеры с этим ID нельзя брать как надежную setup-базу.

Утечка ключа требует rotation, а не надежды. Если ключ попал в commit, screenshot, public log, client bundle, issue или сторонний онлайн-инструмент, создайте новый ключ, обновите server-side secrets, удалите публичные копии, проверьте usage и billing, затем отключите или удалите старый ключ. Google может проактивно блокировать раскрытые API keys, поэтому продолжать использовать старый ключ нельзя считать восстановлением.

Безопасность — часть setup, а не финальный штрих. Готовая интеграция должна отвечать на три вопроса: кто может прочитать ключ, где записан usage, кто делает rotation при утечке. Если ответов нет, настройка еще не закончена.

AI Studio, Vertex AI, Android Studio и gateway — разные маршруты

Похожие слова в туториалах часто относятся к разным продуктам. Сначала разделите route, затем копируйте команды.

Для базовой задачи используйте официальный AI Studio key route. Переходите к Vertex AI, если нужны Cloud IAM, regional endpoints, enterprise governance или существующие GCP-контроли. Оценивайте gateway только как отдельный provider contract с собственными model coverage, pricing, logs, support и exit plan. Не используйте gateway как доказательство официального обхода ограничений Google.

Финальный чеклист готовности

Настройку можно считать рабочей только тогда, когда на каждый вопрос есть конкретный ответ:

Если хотя бы один пункт неизвестен, ключ создан, но еще не настроен для реального workload. Закройте неизвестные пункты до подключения пользовательского трафика или долгих фоновых задач.

Часто задаваемые вопросы

API-ключ Google AI Studio бесплатный?

Создание ключа обычно не означает платеж само по себе, но usage зависит от проекта, модели, региона, Free Tier, billing state и active limits. Перед тем как считать workload бесплатным, проверьте актуальные billing и pricing поверхности Google.

Что использовать: GEMINI_API_KEY или GOOGLE_API_KEY?

Документация Gemini API key говорит, что библиотеки Gemini API могут использовать GEMINI_API_KEY или GOOGLE_API_KEY. Выберите один вариант для команды, задокументируйте место хранения и не выводите значение во frontend или публичный код.

Можно ли увеличить quota несколькими API keys?

Нет. Quota принадлежит проекту и model state, а не каждой строке ключа. Несколько keys в одном проекте нужны для rotation, разделения окружений и security management, но они не умножают active limits.

Почему новый ключ возвращает 403 PERMISSION_DENIED?

Частые причины: не тот проект, недостаточные permissions, неподдерживаемый регион или Free Tier location, billing requirement, unavailable model или authentication mismatch. Проверьте project, region, billing и model status до переписывания кода.

Почему вчера работало, а сегодня появился 429?

Проект мог исчерпать RPM, TPM, RPD или другой active limit. Retry loops, более длинные prompts, рост traffic, model change и изменение tier могут сломать запрос, который раньше проходил.

Можно ли напрямую использовать Google AI Studio / Gemini API из Mainland China, Hong Kong или Macao?

На 27 апреля 2026 года эти три региона не указаны в официальном списке AI Studio / Gemini API available regions, а Taiwan указан. Перед deployment заново проверяйте официальную страницу регионов, потому что поддержка может меняться.

Если consumer Gemini работает, значит Gemini API key тоже будет работать?

Нет. Consumer Gemini, AI Studio, Gemini API, Vertex AI, Workspace и Android Studio tooling имеют разные product, region, account, billing и data boundaries. Отлаживайте именно тот route, который использует ключ.

Что делать, если API key утек?

Создайте новый ключ, обновите server-side environment variables или secrets, удалите раскрытое значение из публичных мест, проверьте usage и billing, затем отключите или удалите старый ключ. Раскрытый ключ не стоит оставлять в работе.

Когда выбирать Vertex AI вместо AI Studio?

AI Studio / Gemini API подходит для быстрого developer setup и небольших интеграций. Vertex AI лучше подходит, когда нужны GCP IAM, regional endpoints, enterprise governance, Cloud billing controls и Cloud-native deployment contract.

Какой model ID указывать в примерах?

Используйте конфигурируемый MODEL_ID и берите значение из актуальной документации Google. Не hardcode старые preview IDs. Доступность, имена и preview status моделей могут меняться независимо от самого API key.