Подключение Gemini API: AI Studio, ключ и первый запрос (2026)

Самый короткий путь к Gemini API такой: открыть AI Studio под аккаунтом Google, создать API-ключ, установить SDK и отправить первый запрос generateContent. Если всё идёт гладко, весь процесс занимает меньше двадцати минут. Реально застрять можно не на вопросе «работает ли вызов», а на неверной точке входа, ошибке в ID модели, путанице между бесплатным и платным уровнем и ключе, положенном туда, где его быть не должно.

Ниже — порядок реального подключения: сначала различия AI Studio и Vertex AI, затем создание ключа, установка SDK, запросы curl и Python, работа с именами моделей, системными инструкциями, потоковым выводом и настройками безопасности, а в конце — частые причины 400, 403 и 429 и чек-лист безопасности ключа.

Примечание: Google и Gemini — товарные знаки Google LLC. Названия моделей, бесплатные квоты и правила биллинга могут меняться; примеры отражают распространённый порядок по состоянию на октябрь 2026 года. Точные данные смотрите в официальной документации Google и на странице тарифов.

1. Сначала различите AI Studio и Vertex AI

У Gemini API есть две распространённые точки входа с разными системами аккаунтов и управления. Неверный выбор приводит к переделке прав или расчётов.

Параметр	Google AI Studio	Vertex AI
Вход	Браузерная консоль для быстрого знакомства разработчиков	Консоль Google Cloud для проектной работы
Требования к аккаунту	Достаточно аккаунта Google	Проект Cloud, платёжный аккаунт и права IAM
Учётные данные	API-ключ, созданный в AI Studio	Сервисный аккаунт или управляемый ключ вместе с IAM
Биллинг	Бесплатный и платный уровни	Расчёты по проекту Cloud
Регионы и данные	По условиям AI Studio	Выбор региона, условия Cloud и настройки проекта
Когда подходит	Прототипы, обучение, небольшая проверка	Производственные системы, аудит и высокие требования к правам

Индивидуальные разработчики и небольшие команды обычно сначала проходят путь в AI Studio; вопросы договоров, регионов данных и единого аудита заставляют оценивать Vertex AI. Ключи, квоты и счета двух платформ нельзя смешивать, и не стоит вызывать интерфейс Vertex AI ключом из AI Studio.

2. Создание первого API-ключа

Войдите в Google AI Studio под аккаунтом Google.
Откройте страницу управления API-ключами и выберите создание ключа.
Выберите проект Google Cloud; если проекта нет, создайте его по подсказке на странице.
Скопируйте созданный ключ и сразу сохраните в серверной переменной окружения или менеджере паролей.
Отправьте тестовое сообщение в Playground и убедитесь, что ключ и модель работают.
Дайте ключу понятное имя, чтобы упростить будущую ротацию и отзыв.

AI Studio предлагает бесплатный уровень для знакомства; доступные модели, скорость запросов и квоты зависят от аккаунта и периода. После включения биллинга в связанном проекте Cloud можно перейти на платный уровень. Не считайте цифры квот из старых статей текущим обещанием — ориентируйтесь на консоль и официальные объяснения.

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

3. Установка SDK и первый запрос

Для Python рекомендуется версия 3.10 и выше; устанавливайте официальный SDK в виртуальном окружении.

python3 -m venv .venv
source .venv/bin/activate
pip install -U google-genai
export GEMINI_API_KEY="ваш-ключ"

Сначала исключите влияние SDK с помощью curl. Вместо ID модели используйте заглушку, а реальное имя возьмите из списка моделей или со страницы тарифов.

curl "https://generativelanguage.googleapis.com/v1beta/models/<ID-модели>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Объясни одной фразой, что такое API-шлюз"}]}
    ],
    "generationConfig": {"maxOutputTokens": 256, "temperature": 0.7}
  }'

После ответа 200 от curl переходите на Python SDK:

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

resp = client.models.generate_content(
    model="<ID-модели>",
    contents="Объясни одной фразой, что такое API-шлюз",
)
print(resp.text)

В model указывается полный ID модели, а не только название серии. Разные модели поддерживают разные типы входа и параметры; ошибка проявится в 400 или 404.

4. Имена моделей, системные инструкции и параметры генерации

ID модели Gemini обычно состоит из названия серии и версии. Надёжнее всего сначала запросить список моделей, доступных текущему аккаунту:

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Не угадывайте модели, которых нет в списке. При выборе распределяйте задачи: для лёгких — низкая задержка, для сложных рассуждений и длинных документов — старший уровень; конкретные уровни и цены смотрите на странице тарифов.

ID моделей обновляются вместе с версиями, старые могут быть помечены как устаревшие или отключены. Храните имя модели в конфигурационном файле, а не в разных местах кода, чтобы при обновлении менять его в одном месте и проверять регрессионными примерами, что вывод заметно не изменился.

Системные инструкции фиксируют роль и правила вывода; они подходят для перевода, извлечения данных и поддержки:

resp = client.models.generate_content(
    model="<ID-модели>",
    contents="Переведи эту фразу на английский: подключение завершено",
    config={"system_instruction": "Ты переводчик технической документации, выводи только перевод."},
)

Распространённые параметры генерации — temperature, maxOutputTokens и topP. Если нужен структурированный результат, можно попросить модель вернуть JSON и разобрать его с проверкой в коде; не предполагайте, что модель всегда соблюдает формат, — повторы при сбое и запасную логику нужно предусмотреть заранее.

5. Потоковый вывод и настройки безопасности

Потоковый вывод подходит для чат-интерфейсов и длинных ответов. В REST добавьте :streamGenerateContent после метода и параметр alt=sse; в Python SDK используйте generate_content_stream:

for chunk in client.models.generate_content_stream(
    model="<ID-модели>",
    contents="Объясни в трёх пунктах, что такое ограничение скорости",
):
    print(chunk.text, end="")

Настройки безопасности позволяют менять пороги блокировки по категориям: оскорбления, ненависть, сексуальный контент и опасные темы. Пороги по умолчанию подходят большинству бизнес-сценариев; снижение блокировки расширяет допустимый контент и требует оценки с учётом политики продукта и местного законодательства. Не отключайте настройки безопасности целиком ради «прохождения тестов», особенно в публичных продуктах.

6. Как разбирать 400, 403 и 429

Код	Частая причина	Направление действий
400	Ошибка структуры JSON, неподдерживаемый параметр, несоответствие ID модели и интерфейса	Проверьте тело запроса по полям, начните с минимального запроса
403	Ключ недействителен или ограничен, API не включён, ограничение проекта или региона	Проверьте другой ключ, права проекта и состояние аккаунта
404	Опечатка в ID модели, неверная версия или путь интерфейса	Сверьтесь со списком моделей, проверьте `v1beta` и имя метода
429	Исчерпана бесплатная квота, слишком много запросов в минуту, высокий параллелизм	Пауза с повтором, снижение параллелизма, оценка платного уровня
500/503	Временный сбой на стороне сервиса	Ограниченное число повторов, затем деградация или смена канала

При 429 не отправляйте запрос сразу повторно. Правильный подход — пауза с экспоненциальной задержкой и случайным разбросом, ограничение числа попыток и запись неудачных запросов в лог. На бесплатном уровне ограничения скорости обычно строже; нагрузочные и пакетные задачи планируйте отдельно.

7. Чек-лист безопасности ключа

Ключ хранится только в серверных переменных окружения или сервисе управления секретами, не во фронтенде, репозитории и переписке.
Для производства, теста и разработки — отдельные ключи с изоляцией квот и прав.
Регулярная ротация; при увольнении или завершении проекта ключ сразу отзывается.
В облачной консоли ограничьте API, которые может вызывать ключ, чтобы уменьшить последствия утечки.
Включите оповещения о расходе: при аномальных вызовах сначала остановите ключ, затем разбирайтесь.
Не показывайте полный ключ на скриншотах, записях экрана и в заявках.

8. Подключение Gemini через OpenAI-совместимый вход

Если у команды уже есть OpenAI SDK и весь код вызовов, можно использовать OpenAI-совместимый вход ZSQH AI Gateway с Base URL https://ai.zhongshangqihang.com/v1. Достаточно изменить три места: base_url, api_key и model:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="<название модели Gemini со страницы тарифов>",
    messages=[{"role": "user", "content": "Ответь только OK"}],
)
print(resp.choices[0].message.content)

Этот способ подходит командам, которым нужны единый счёт по нескольким моделям, расчёты в юанях и доступная сеть в Китае. Полная совместимость нативных параметров Gemini и полей мультимодальности не гарантируется; перед миграцией проверьте каждый пункт реальными запросами. Регистрация — здесь, модели и цены — на странице тарифов.

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

Есть ли у Gemini API бесплатная квота?

В AI Studio есть бесплатный уровень, но доступные модели, скорость и квоты меняются, а условия обработки данных могут отличаться от платного уровня. Для прототипа бесплатный уровень подходит; для рабочего бизнеса стоит заново оценить квоты и затраты по платному уровню.

Что делать при утечке API-ключа?

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

Можно ли вызывать Gemini API напрямую из Китая?

Качество канала зависит от региона и оператора, возможны таймауты и сбои соединения. Распространённый подход — разместить запросы на сервере со стабильным доступом или использовать шлюз с поддержкой OpenAI-совместимого интерфейса; конкретные ограничения зависят от фактического канала и официальных условий.

Почему curl работает, а Python SDK выдаёт ошибку?

Проверьте актуальность версии SDK и зависимостей, затем согласованность записи model, настроек прокси и переменных окружения. Если SDK возвращает 404, сосредоточьтесь на ID модели и пути интерфейса и не меняйте несколько переменных одновременно.

Можно ли вызывать Gemini API напрямую через OpenAI SDK?

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

Что дальше

Сначала пройдите минимальный запрос по описанному порядку, затем подключайте бизнес-логирование, повторы и мониторинг расхода. Если нужно управлять вызовами Gemini и других моделей, счетами в юанях и правами ключей из одной панели, начните с регистрации в ZSQH AI Gateway; цены — на странице тарифов.