Gemini API key: как получить ключ и что делать, если он не работает

Gemini API key — это строка, по которой сервис узнаёт, кто отправляет запрос и с чьего баланса списывать токены. Получить её можно двумя способами: создать ключ в Google AI Studio или взять ключ шлюза, через который модель Gemini 3.8 Flash вызывается в обычном OpenAI-формате. Ниже оба пути по шагам, почему из России ключ Google часто не работает, как хранить ключ и что проверить, если запросы отклоняются.

Данные о Google взяты из документации ai.google.dev на 18 октября 2026, цены Zukko тоже на эту дату. Интерфейсы меняются, поэтому названия кнопок в вашем окне могут слегка отличаться.

Два пути: сравнение

Путь 1. Ключ в Google AI Studio

Порядок по документации Google:

1. Откройте Google AI Studio и войдите аккаунтом Google. Нужен возраст 18+ и подтверждение возраста в аккаунте.
2. Примите условия использования. Если вы новый пользователь, AI Studio сам создаст проект Google Cloud и ключ по умолчанию.
3. Перейдите на страницу API keys (aistudio.google.com/apikey). Для нового ключа нажмите Create API key и выберите проект.
4. Скопируйте ключ и сохраните в переменную окружения.

Если у вас уже есть аккаунт Google Cloud, AI Studio не создаёт проект сам: сначала импортируйте существующий проект в разделе Dashboard, затем Projects, затем Import projects, и только после этого создайте ключ на странице API keys. Если кнопка создания неактивна и пишет про отсутствие прав, нужна роль администратора проекта (например, Project Editor) или новый проект без привязки к организации.

Клиентские библиотеки Google сами читают переменные GEMINI_API_KEY и GOOGLE_API_KEY (при наличии обеих приоритет у GOOGLE_API_KEY):

export GEMINI_API_KEY="ваш_ключ_google"

Что стоит знать о самих ключах:

• с 28 мая 2026 новые ключи, созданные в AI Studio, создаются как authorization keys, привязанные к сервисному аккаунту, и по умолчанию ограничены Gemini API;
• Gemini API отвергает запросы с неограниченными «стандартными» ключами, а ключи с явными ограничениями продолжают работать;
• если ключ попал в открытый доступ, Google его блокирует, и вы увидите сообщение, что ключ помечен как утёкший: нужен новый.

Почему из России ключ Google часто не работает

Gemini API и Google AI Studio доступны не во всех странах. На странице Available regions Google перечисляет страны и территории, и России в этом списке нет (страница обновлялась в апреле 2026). Поэтому типичный сценарий: ключ создать не удаётся, AI Studio сообщает о недоступности в регионе, или прямые запросы отклоняются. Это не ошибка в вашем коде, и править её настройками клиента нельзя. Схемы обхода мы не рекомендуем.

Путь 2. Ключ шлюза: Gemini 3.8 Flash по OpenAI-формату

Для работы из России практичнее второй путь. Доступ к Gemini идёт через шлюз Zukko: оплата СБП, картой MasterCard или криптой, баланс в долларах, без подписки.

1. Зарегистрируйтесь в кабинете↗ и подтвердите email (без подтверждения API не тратит баланс и возвращает 403).
2. Откройте страницу API-ключей↗ и создайте ключ: задайте имя, при желании дневной и месячный лимит в долларах и список разрешённых моделей (allowed_models).
3. Скопируйте ключ fetch_...: полный ключ показывается один раз, потом его не посмотреть, только выпустить новый.
4. Пополните баланс. Минимум $1. СБП идёт в рублях по рыночному курсу, платёжная страница добавляет 8,5% сверху: для $5 это 5 × 1.085 = $5.425 в пересчёте. Карты MasterCard — комиссия около 13%, суммы $2–$594. Также доступна криптовалюта.
5. Отправьте первый запрос.

export OPENAI_BASE_URL="https://api.zukko.pro/v1"
export OPENAI_API_KEY="fetch_ваш_ключ"

from openai import OpenAI

client = OpenAI()  # берёт OPENAI_BASE_URL и OPENAI_API_KEY

r = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[{"role": "user", "content": "Напиши одну строку: проверка ключа"}],
)
print(r.choices[0].message.content)

То же через curl:

curl https://api.zukko.pro/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-3.8-flash","messages":[{"role":"user","content":"Привет"}]}'

Базовый адрес заканчивается на /v1: так работают клиенты на OpenAI SDK. Подробнее про заголовки — в разделе аутентификации↗, а общий порядок действий — в быстром старте↗.

Сколько стоит вызов

Цены Zukko на 18 октября 2026 для gemini-3.8-flash: $0.125 за 1M входных и $0.6 за 1M выходных токенов. Контекст 1M токенов, на вход принимается только текст. Для сравнения, официальные цены из нашей таблицы — $0.75 и $3.75.

Пример: запрос на 3000 входных и 600 выходных токенов стоит 3000 × 0.125 / 1 000 000 + 600 × 0.6 / 1 000 000 = 0.000375 + 0.00036 = $0.000735. На $1 приходится около 1360 таких запросов (1 / 0.000735). Реальный расход у моделей Gemini 3.x может быть выше из-за токенов рассуждений, которые по документации Google тарифицируются как выходные, поэтому прогоните сотню запросов и посмотрите итог в разделе «Использование».

Актуальные цены и список моделей: GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете.

Как хранить ключ безопасно

Правила одинаковы для любого ключа:

• не кладите ключ в код и не коммитьте его в репозиторий: утёкший ключ Google блокирует, а ключ шлюза кто угодно может потратить;
• используйте переменные окружения или менеджер секретов;
• заведите отдельный ключ на каждый проект, чтобы отзывать их независимо;
• в кабинете Zukko ограничьте ключ дневным и месячным лимитом в долларах и списком моделей: даже при утечке потери ограничены;
• при подозрении на утечку выпустите новый ключ и отзовите старый. Порядок действий — в статье Утёк API-ключ: что делать↗, а практики хранения — в материале Безопасное хранение API-ключей↗.

Ключ не работает: что проверить

Если вы работаете с ключом Google, сверьте также: нет ли в окружении второй переменной (GOOGLE_API_KEY приоритетнее GEMINI_API_KEY), не заблокирован ли ключ как утёкший и не неограниченный ли это «стандартный» ключ.

Частые вопросы

Как получить Gemini API key бесплатно?

В Google AI Studio есть бесплатный уровень с ограниченными лимитами, причём содержимое запросов на нём может использоваться для улучшения продуктов Google. Лимиты бесплатного уровня Google меняет, актуальные смотрите в его документации; доступность зависит от региона.

Можно ли получить Gemini API key в России?

Прямой ключ Google из России получить обычно не удаётся: России нет в списке регионов Gemini API. Практичный вариант — ключ шлюза Zukko, оплата СБП, картой MasterCard или криптой.

Нужно ли менять код, если у меня уже есть код на OpenAI SDK?

Нет, достаточно указать base_url="https://api.zukko.pro/v1", ключ fetch_... и модель gemini-3.8-flash.

Сколько ключей можно создать?

Можно создавать несколько ключей, у каждого свои имя, лимиты и список разрешённых моделей. Заводите отдельный ключ на каждый проект.