Ошибка 400 API key not valid при первом запросе к Google Gemini API почти всегда означает, что ключ создан не в том проекте, скопирован с лишними пробелами или передан не в том параметре — а не в том, что «API не работает». Проверка ключа занимает пару минут и решает большинство проблем новичков ещё до написания кода.
Ниже разберём, как получить ключ в Google AI Studio, какие модели доступны через API, как отправить первый запрос и что делать с типичными ошибками. Материал ориентирован на разработчиков и энтузиастов, которые хотят встроить генеративный ИИ в свои скрипты, ботов или приложения.
Что такое Gemini API и чем он отличается от чата Gemini
Gemini API — это программный интерфейс от Google, который позволяет отправлять запросы к моделям семейства Gemini напрямую из кода: из Python-скрипта, серверного приложения или мобильного клиента. В отличие от веб-чата, здесь вы сами управляете промптами, параметрами генерации, историей диалога и обработкой ответов.
Ключевое отличие от веб-версии — гибкость. Через API можно строить цепочки запросов, подключать функции (function calling), передавать изображения и документы, настраивать системные инструкции. Веб-чат такого не умеет — это готовый продукт, а не инструмент разработки.
Доступ к API предоставляется через Google AI Studio — бесплатную панель для экспериментов, а для продакшен-нагрузок и корпоративных сценариев существует Vertex AI на платформе Google Cloud. Для старта и прототипирования достаточно AI Studio.
Как получить API-ключ в Google AI Studio
Первый шаг — регистрация ключа. Понадобится обычный Google-аккаунт, дополнительной оплаты для создания ключа не требуется: у API есть бесплатный уровень с ограничениями по частоте запросов.
Порядок действий:
- 🔑 Откройте Google AI Studio и войдите под своим Google-аккаунтом.
- 🛠️ Найдите раздел получения API-ключа (кнопка вида
Get API key). - 📁 Создайте ключ в новом проекте или привяжите к существующему проекту Google Cloud.
- 📋 Скопируйте ключ и сохраните его в надёжном месте — в открытом виде он показывается ограниченно.
☑️ Проверка перед первым запросом
⚠️ Внимание: API-ключ — это фактически пароль от вашей квоты и привязанного биллинга. Никогда не публикуйте его в репозиториях, не вшивайте в клиентские приложения и не передавайте третьим лицам. Скомпрометированный ключ нужно сразу отозвать в AI Studio и создать новый.
Доступные модели и их назначение
Семейство Gemini включает несколько моделей с разным балансом скорости, стоимости и качества. Линейка периодически обновляется, поэтому актуальный список и идентификаторы моделей стоит сверять в официальной документации — имена версий меняются по мере выхода новых поколений.
Условно модели делятся на назначения: быстрые (для чат-ботов, классификации, коротких ответов) и флагманские (для сложных рассуждений, анализа документов, генерации кода). Быстрые варианты дешевле и отвечают с меньшей задержкой, флагманские лучше справляются с многошаговыми задачами.
| Тип модели | Типичные задачи | Скорость ответа | Относительная стоимость |
|---|---|---|---|
| Быстрые (Flash-серия) | Чаты, суммаризация, классификация | Высокая | Низкая |
| Флагманские (Pro-серия) | Код, аналитика, сложные рассуждения | Средняя | Выше |
| Мультимодальные | Анализ изображений, аудио, документов | Зависит от входных данных | По тарифу модели |
| Embedding-модели | Семантический поиск, векторные базы | Высокая | Низкая |
Какую модель выбрать для старта? Для прототипа берите быструю модель — её квоты на бесплатном уровне выше, а качества хватает для отладки логики. Переходить на флагманскую версию имеет смысл, когда вы уперлись в качество ответов, а не в гипотезу «а вдруг станет лучше».
Первый запрос: минимальный пример
Запрос к API отправляется по HTTPS на endpoint вида generativelanguage.googleapis.com с указанием модели в пути. Ниже — обобщённый пример на Python с использованием официальной библиотеки; точные имена методов могут отличаться в зависимости от версии SDK, поэтому сверяйтесь с документацией.
import google.generativeai as genai
genai.configure(api_key="ВАШ_КЛЮЧ")
model = genai.GenerativeModel("gemini-flash-latest")
response = model.generate_content("Объясни, что такое API, в двух предложениях")
print(response.text)
Тот же запрос можно выполнить через curl, передав ключ в параметре key или заголовке. Тело запроса — JSON с массивом contents, где указаны роль и текст сообщения. Ответ приходит в JSON, текст генерации лежит во вложенной структуре candidates.
Храните ключ в переменной окружения, а не строкой в коде:
export GEMINI_API_KEY="ваш_ключ"Квоты, лимиты и бесплатный уровень
Бесплатный уровень Gemini API ограничивает частоту запросов (RPM — запросов в минуту) и суточные объёмы. Конкретные значения зависят от модели и меняются со временем, поэтому здесь не приводим точные цифры — проверяйте актуальные лимиты в разделе квот вашего проекта в AI Studio или Google Cloud Console.
Для платного использования необходимо подключить биллинг к проекту Google Cloud. После этого лимиты повышаются, а оплата идёт за токены — единицы текста, в которые модель разбивает вход и выход. Длинные контексты и многословные ответы стоят дороже коротких.
Сократить расход помогают простые приёмы:
- ✂️ Обрезайте историю диалога — не отправляйте весь контекст при каждом запросе.
- 🎯 Используйте быструю модель там, где не нужны сложные рассуждения.
- 🧮 Ограничивайте длину ответа параметром
maxOutputTokens. - 💾 Кэшируйте повторяющиеся запросы на своей стороне.
Типичные ошибки и их решение
Большинство проблем при работе с Gemini API сводится к нескольким HTTP-кодам. Разберём, что они означают и где искать причину.
| Код | Вероятная причина | Что проверить |
|---|---|---|
| 400 | Некорректный запрос или ключ | Формат JSON, имя модели, целостность ключа |
| 403 | Нет доступа | Активность ключа, включён ли API в проекте, региональные ограничения |
| 429 | Превышена квота | Частота запросов, паузы и повторные попытки |
| 500/503 | Сбой на стороне сервиса | Повторить позже с экспоненциальной задержкой |
Ошибка 429 — самая частая на бесплатном уровне. Решение — не «жать чаще», а внедрить повторные попытки с задержкой (exponential backoff): ждать секунду, потом две, потом четыре. Также проверьте, не запускаете ли вы параллельные запросы, которые суммарно упираются в лимит.
⚠️ Внимание: ошибка 403 иногда связана с регионом — доступность API зависит от страны аккаунта и сервера. Если ключ валиден, API включён, а доступа нет, сверьтесь со списком поддерживаемых регионов в официальной документации Google.
Если ответ приходит, но выглядит «обрезанным», проверьте поле finishReason в ответе. Значение, связанное с лимитом токенов, означает, что генерация уперлась в maxOutputTokens — увеличьте параметр. Причиной также может быть срабатывание фильтров безопасности: тогда текст блокируется, и запрос стоит переформулировать.
Почему модель отвечает не в том формате
Если вы просите JSON, а получаете текст с пояснениями, добавьте в промпт явное требование формата и пример структуры. В новых версиях API есть параметр responseMimeType со значением application/json — он принудительно включает режим структурированного вывода, если ваша модель его поддерживает.
Безопасность и хранение ключей
Работа с API-ключами требует базовой гигиены, особенно если проект выкладывается на GitHub или разворачивается на сервере. Утечка ключа означает, что чужие запросы пойдут за ваш счёт и в счёт вашей квоты.
Минимальный набор правил: ключ — только в переменных окружения или менеджере секретов; файл .env добавлен в .gitignore; для серверного приложения запросы к Gemini идут через ваш бэкенд, а не напрямую из браузера или мобильного клиента. Клиентская интеграция «в лоб» раскрывает ключ любому, кто посмотрит трафик.
⚠️ Внимание: если ключ уже попал в публичный репозиторий, удаление коммита не спасает — история Git сохраняет данные. Ключ нужно немедленно отозвать и сгенерировать новый, а старый считать скомпрометированным навсегда.
FAQ: частые вопросы о Gemini API
Бесплатен ли Google Gemini API?
Да, существует бесплатный уровень с ограничениями по частоте и объёму запросов. Для снятия лимитов и промышленного использования подключается платный биллинг через Google Cloud с оплатой за токены.
Чем Gemini API отличается от Vertex AI?
Gemini API через AI Studio — быстрый способ начать: ключ за пару минут, минимум настройки. Vertex AI — корпоративная платформа Google Cloud с расширенным управлением доступом, мониторингом и интеграциями. Для прототипа достаточно первого, для продакшена в компании чаще выбирают второй.
Можно ли отправлять изображения через API?
Да, мультимодальные модели Gemini принимают изображения — файл передаётся в запросе в закодированном виде или по ссылке на загруженный объект. Проверяйте в документации, какие форматы и лимиты размера поддерживает выбранная модель.
Что делать при ошибке 429 на бесплатном тарифе?
Снизьте частоту запросов, добавьте паузы и повторные попытки с растущей задержкой. Если нагрузка стабильно превышает бесплатные лимиты, рассмотрите подключение платного биллинга.
Как узнать, сколько токенов потратил запрос?
В ответе API присутствует блок с метаданными использования (usage metadata), где указано количество токенов входа и выхода. Логируйте эти значения — так проще контролировать расход и находить «дорогие» запросы.