Gemini API: как получить ключ и сделать первый запрос

Gemini API даёт доступ к моделям Google (текст, изображения, анализ данных) прямо из вашего кода. Разберём по шагам: как получить ключ, сделать первый запрос на JavaScript и не наделать типичных ошибок с безопасностью и лимитами. Никакого опыта работы с API для старта не требуется.

Что такое Gemini API

Gemini API (интерфейс программного доступа к моделям Gemini) — это способ обращаться к искусственному интеллекту Google не через сайт-чат, а программно: ваше приложение отправляет запрос и получает ответ модели. Так делают чат-ботов, генерацию описаний, анализ текста, извлечение данных и десятки других функций внутри собственных сервисов.

Важно различать два уровня. Обычный запрос к модели — «спросил и получил ответ». Более сложные агентные сценарии (когда ИИ сам планирует действия и вызывает инструменты) — это уже отдельная история; о ней мы писали в разборе Managed Agents в Gemini API. В этой статье остановимся на базе — одиночном запросе, с которого начинают все.

Шаг 1. Получаем API-ключ

API-ключ (секретный код доступа, по которому Google понимает, что запрос отправляете именно вы) выдаётся бесплатно в Google AI Studio.

1. Откройте aistudio.google.com/apikey и войдите в аккаунт Google.

2. Нажмите «Create API key» (создать ключ).

3. Скопируйте значение — оно начинается с AIza….

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

Шаг 2. Устанавливаем SDK и делаем первый запрос

Для JavaScript есть официальный пакет @google/genai. Установите его:

npm install @google/genai

Передайте ключ через переменную окружения (environment variable — значение, которое хранится вне кода), а не строкой в файле. Например, положите его в .env или задайте в терминале:

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

Минимальный первый запрос:

import { GoogleGenAI } from "@google/genai";

// Ключ читается из переменной окружения GEMINI_API_KEY
const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "Объясни простыми словами, что такое API, одним абзацем.",
  });

  console.log(response.text);
}

main().catch((error) => {
  console.error(error instanceof Error ? error.message : error);
  process.exitCode = 1;
});

Что здесь происходит: создаём клиент (он сам берёт ключ из окружения), отправляем в модель текстовый запрос и печатаем ответ из поля response.text. Модель gemini-2.5-flash — быстрая и недорогая, подходит для старта. Актуальный список моделей стоит сверять в документации: имена и версии периодически меняются, появляются более новые семейства.

Без SDK: запрос напрямую по HTTP

Если не хотите ставить библиотеку или пишете не на JavaScript, к Gemini API можно обратиться обычным HTTP-запросом. Обратите внимание: ключ передаётся заголовком x-goog-api-key, а не в адресе (URL) — так он не попадёт в логи сервера и историю браузера.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Привет! Ответь одним предложением."}]}]}'

Ответ придёт в формате JSON; текст модели лежит внутри массива candidates. Тот же принцип работает из любого языка, где есть HTTP-клиент.

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

Самая частая и дорогая ошибка новичка — «засветить» ключ. Несколько правил:

• Ключ живёт только в переменной окружения или в защищённом хранилище секретов — не в исходном коде.

• Добавьте .env в .gitignore, чтобы ключ не попал в репозиторий.

• Никогда не вызывайте Gemini API напрямую из браузера или мобильного приложения: там ключ виден любому пользователю. Запросы к модели должны идти через ваш сервер (backend), который и хранит ключ.

• Если ключ всё же засветился — немедленно отзовите его в Google AI Studio и создайте новый.

• Заведите отдельные ключи под разные проекты, чтобы их было проще отзывать.

Бесплатный тариф и лимиты

У Gemini API есть бесплатный уровень (free tier) с ограничениями по частоте запросов. Ключевые лимиты измеряются в трёх величинах:

• RPM (requests per minute) — запросов в минуту;

• TPM (tokens per minute) — токенов в минуту (токен — кусочек текста, единица, которой измеряется объём);

• RPD (requests per day) — запросов в сутки.

Для экспериментов и небольшого проекта бесплатного тарифа обычно достаточно. Когда нагрузка вырастет, подключается оплата, и лимиты повышаются в зависимости от тарифного уровня. Следите за фактическим расходом в панели Google AI Studio, чтобы неожиданный всплеск запросов не привёл к счёту или упёршемуся лимиту.

Частые ошибки и что они значат

• 400 (Bad Request) — неверный запрос: чаще всего опечатка в имени модели или неправильная структура contents.

• 401 / 403 — проблема с ключом: не задан, недействителен или у него нет доступа к нужной модели.

• 429 (Too Many Requests) — упёрлись в лимит частоты или исчерпали квоту. Добавьте паузы между запросами или поднимите тариф.

• 500 / 503 — временная проблема на стороне сервиса: имеет смысл повторить запрос с небольшой задержкой.

Полезная привычка с самого начала — оборачивать вызовы в обработку ошибок (как в примере выше) и логировать код ошибки, но никогда не писать в лог сам ключ.

Что дальше

После первого запроса логично освоить: потоковый вывод ответа (streaming — текст приходит по мере генерации), системные инструкции (задать модели роль и правила), структурированный ответ в JSON и работу с изображениями. Отдельное большое направление — подключение внешних инструментов к модели по стандарту MCP; если оно вам нужно, начните с материала про обновление MCP, а затем посмотрите, как это устроено в Managed Agents.

Вывод

Чтобы начать работать с Gemini API, достаточно трёх шагов: получить бесплатный ключ в Google AI Studio, установить пакет @google/genai и отправить первый запрос через generateContent. Дальше усложняете по мере задач. Главное правило с самого начала — относиться к API-ключу как к паролю: держать его в переменных окружения, не пускать на фронтенд и отзывать при малейшем сомнении. Тогда старт будет и быстрым, и безопасным.