Gemini 3 API: первый запуск без боли. Туториал по Google AI Studio и Python SDK

Зачем вам этот гайд, если в интернете уже миллион туториалов?

Потому что 90% из них устарели через месяц после публикации. Google меняет API быстрее, чем вы успеваете прочитать документацию. На февраль 2026 года работа с Gemini 3 выглядит иначе, чем полгода назад. Новые модели, обновленный SDK, измененная аутентификация.

Если вы пытались следовать старому гайду и получали ошибку "Model not found" или "Invalid API key" – вы не одиноки. Google тихо убирает старые версии моделей, добавляет новые параметры, меняет названия эндпоинтов.

Что изменилось в Gemini 3 к 2026 году?

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

Старые модели вроде gemini-1.5-pro больше не доступны через стандартный API. Если ваш код обращается к ним – он сломается. Google не предупреждает об этом заранее, просто начинает возвращать 404.

1 Шаг 1: Получаем API ключ через Google AI Studio

Здесь большинство спотыкается. Не потому что сложно, а потому что Google постоянно меняет интерфейс. На февраль 2026 года путь такой:

1. Откройте Google AI Studio
2. Войдите под своим Google аккаунтом
3. В левом меню найдите раздел "Get API key" (раньше он был справа вверху)
4. Нажмите "Create API key"
5. Выберите проект или создайте новый

Важный момент: ключ создается для конкретного проекта Google Cloud. Если у вас его нет – система предложит создать автоматически. Это не то же самое, что проект в AI Studio.

После создания ключа скопируйте его. Он выглядит примерно так: AIzaSyB...123 (40 символов).

2 Шаг 2: Устанавливаем Python SDK (актуальная версия на 2026)

Здесь главная ошибка – установить через pip install google-generativeai без указания версии. Вы получите старый SDK, который не поддерживает Gemini 3.

Правильная команда:

pip install google-generativeai==0.8.0

Почему именно 0.8.0? Потому что это последняя стабильная версия на февраль 2026, которая точно работает с Gemini 3. Ранние версии (0.5.x, 0.6.x) могут не поддерживать новые параметры вроде response_mime_type или temperature выше 2.0.

Проверьте установку:

import google.generativeai as genai
print(genai.__version__)  # Должно показать 0.8.0 или выше

3 Шаг 3: Первый запрос – делаем правильно, а не "как в документации"

Документация Google показывает упрощенный пример. Он работает, но в реальном проекте вам нужно больше контроля. Вот как выглядит минимальный рабочий код:

import google.generativeai as genai

# Конфигурация (никогда не хардкодите ключ!)
genai.configure(api_key="YOUR_API_KEY_HERE")

# Создаем модель - ВАЖНО: используем актуальное имя
model = genai.GenerativeModel('gemini-3.0-pro')

# Простой запрос
response = model.generate_content("Привет, Gemini! Напиши короткое приветствие.")
print(response.text)

Если вы получили ошибку google.api_core.exceptions.NotFound: 404 Model 'gemini-3.0-pro' not found – значит, либо у вас старая версия SDK, либо вы неправильно указали имя модели.

Проверьте доступные модели:

for model in genai.list_models():
    print(model.name)

На февраль 2026 в списке должны быть как минимум gemini-3.0-pro и gemini-3.0-flash.

А теперь – как НЕ надо делать. Типичные ошибки новичков

Я видел эти ошибки в десятках проектов. Они кажутся мелочами, но ломают все.

Ошибка 1: Ключ в коде, а не в переменных окружения

Как делают все:

# ПЛОХО! Ключ в коде
genai.configure(api_key="AIzaSyB...123")

Как надо:

# ХОРОШО! Ключ из переменных окружения
import os
from dotenv import load_dotenv

load_dotenv()  # Загружает .env файл
api_key = os.getenv("GEMINI_API_KEY")
if not api_key:
    raise ValueError("GEMINI_API_KEY not found in environment variables")

genai.configure(api_key=api_key)

Создайте файл .env в корне проекта:

GEMINI_API_KEY=AIzaSyB...123

И добавьте .env в .gitignore.

Ошибка 2: Не обрабатывают ошибки API

Gemini API возвращает специфичные ошибки. Если их не ловить – приложение падает на первом же сбое.

import google.api_core.exceptions as gexc

try:
    response = model.generate_content("Твой запрос")
except gexc.ResourceExhausted:
    print("Лимит запросов исчерпан. Подождите или проверьте квоты.")
except gexc.InvalidArgument as e:
    print(f"Некорректные параметры: {e}")
except gexc.PermissionDenied:
    print("Проблема с API ключом или доступом к модели")
except Exception as e:
    print(f"Неизвестная ошибка: {type(e).__name__}: {e}")

Ошибка 3: Используют дефолтные параметры для production

Дефолтный temperature=0.9 слишком высок для предсказуемых ответов. Дефолтный max_output_tokens=2048 может быть избыточным.

Настройте под свою задачу:

response = model.generate_content(
    "Объясни квантовую запутанность простыми словами",
    generation_config=genai.GenerationConfig(
        temperature=0.3,           # Меньше креатива, больше фактов
        top_p=0.95,               # Контроль разнообразия
        top_k=40,                 # Ограничение словаря
        max_output_tokens=1024,   # Достаточно для объяснения
        stop_sequences=["###"]    # Стоп-символы
    )
)

Работа с мультимодальностью: картинки, PDF, аудио

Здесь Gemini 3 показывает свою силу. Но и здесь больше всего подводных камней.

Загрузка изображения:

import PIL.Image

# Открываем изображение
img = PIL.Image.open("diagram.png")

# Анализируем
response = model.generate_content([
    "Что изображено на этой диаграмме? Опиши подробно.",
    img
])
print(response.text)

Важно: Gemini 3 Vision работает только с моделями, содержащими -vision в названии. Но с февраля 2026 основные модели тоже поддерживают изображения через универсальный API.

Работа с PDF:

Прямую загрузку PDF Google не поддерживает. Нужно сначала конвертировать в текст или изображения. Самый простой способ – использовать библиотеку PyPDF2 для извлечения текста:

import PyPDF2

with open("document.pdf", "rb") as file:
    pdf_reader = PyPDF2.PdfReader(file)
    text = ""
    for page in pdf_reader.pages:
        text += page.extract_text()
    
    # Теперь анализируем текст
    response = model.generate_content(
        f"Проанализируй этот документ и выдели ключевые пункты:\n\n{text[:10000]}"  # Ограничиваем длину
    )

Стриминг ответов: не ждите минуту, получайте по частям

Для длинных ответов используйте стриминг. Пользователь видит ответ сразу, а не ждет полной генерации.

response = model.generate_content(
    "Напиши подробное руководство по Python от новичка до продвинутого уровня",
    stream=True
)

for chunk in response:
    if chunk.text:
        print(chunk.text, end="")  # Выводим по мере поступления

Это особенно важно для веб-приложений. Представьте чат-бота, который молчит 30 секунд, а потом вываливает стену текста.

Цены и лимиты: сколько это будет стоить в 2026

Google постоянно меняет тарифы. На февраль 2026 актуальны такие расценки (за 1 млн токенов):

• gemini-3.0-flash: $0.15 вход, $0.60 выход
• gemini-3.0-pro: $0.75 вход, $3.00 выход
• gemini-3.0-vision: $1.50 вход, $6.00 выход

Входные токены – это ваш промпт. Выходные – ответ модели. Vision дороже из-за обработки изображений.

Считайте токены, чтобы не получить неожиданный счет:

# Оцениваем количество токенов
prompt = "Ваш длинный промпт здесь"
count = model.count_tokens(prompt)
print(f"Токенов в промпте: {count.total_tokens}")

# После генерации можно посчитать и ответ
print(f"Токенов в ответе: {response.usage_metadata.total_token_count}")

Продвинутый паттерн: чат с историей

Простые generate_content не сохраняют контекст. Для диалога нужен другой подход:

# Создаем чат-сессию
chat = model.start_chat(history=[])

# Первое сообщение
response = chat.send_message("Привет! Я разработчик Python.")
print(f"Gemini: {response.text}")

# Второе сообщение с контекстом
response = chat.send_message("Посоветуй лучшие библиотеки для асинхронного программирования")
print(f"Gemini: {response.text}")

# История доступна
for message in chat.history:
    print(f"{message.role}: {message.parts[0].text}")

История автоматически отправляется с каждым запросом. Модель "помнит" разговор.

Деплой в продакшен: что проверить перед запуском

1. Резервный ключ API: Создайте два ключа. Если один отзовут – переключитесь на второй.
2. Рейт-лимитинг: Реализуйте очередь запросов. Не штурмуйте API 100 запросами в секунду.
3. Кеширование: Частые одинаковые запросы? Кешируйте ответы. Сэкономите деньги и время.
4. Мониторинг: Следите за ошибками 429 (Too Many Requests) и 503 (Service Unavailable).
5. Фолбэк: Что делать, если Gemini недоступен? Иметь запасной вариант (другая модель или статичный ответ).

Пример минимального продакшен-решения:

import time
from typing import Optional
import google.generativeai as genai
from google.api_core import exceptions

class GeminiClient:
    def __init__(self, api_key: str, model_name: str = "gemini-3.0-flash"):
        genai.configure(api_key=api_key)
        self.model = genai.GenerativeModel(model_name)
        self.last_request_time = 0
        self.min_interval = 0.1  # 100ms между запросами
    
    def generate_with_retry(self, prompt: str, max_retries: int = 3) -> Optional[str]:
        """Генерация с повторными попытками и rate limiting"""
        for attempt in range(max_retries):
            try:
                # Rate limiting
                elapsed = time.time() - self.last_request_time
                if elapsed < self.min_interval:
                    time.sleep(self.min_interval - elapsed)
                
                self.last_request_time = time.time()
                response = self.model.generate_content(prompt)
                return response.text
                
            except exceptions.ResourceExhausted:
                wait_time = 2 ** attempt  # Экспоненциальная задержка
                time.sleep(wait_time)
            except exceptions.ServiceUnavailable:
                if attempt == max_retries - 1:
                    return "Сервис временно недоступен. Попробуйте позже."
                time.sleep(1)
        return None

Что дальше? Куда расти после первого запуска

Вы сделали первый запрос. Работает. Что изучать дальше?

• Инструменты (tools): Заставляйте Gemini вызывать ваши функции. Например, "забронируй столик на 19:00" → Gemini вызывает ваш booking API.
• Системные промпты: Задавайте роль модели. "Ты – senior Python разработчик с 10-летним опытом. Отвечай как на код-ревью."
• Цепочки вызовов (chains): Разбивайте сложные задачи на шаги. Сначала анализ, затем генерация, потом проверка.
• Fine-tuning: Хотя Gemini 3 пока не поддерживает тонкую настройку через API, следите за анонсами. Google обещает эту функцию в 2026.

Самый интересный путь – интеграция Gemini с другими системами. Представьте: Gemini анализирует логи вашего приложения, находит аномалии, предлагает фиксы и даже создает тикет в Jira. Или автоматически генерирует документацию на основе кода.

Главный совет, который сэкономит вам недели

Не пытайтесь сразу построить сложную систему. Начните с простого прототипа. Сделайте одну функцию, которая работает. Потом добавьте обработку ошибок. Потом – кеширование. Потом – мониторинг.

Каждый раз, когда Google выпускает обновление (а это происходит раз в 1-2 месяца), проверяйте:

1. Работает ли ваш код с новой версией SDK?
2. Не появились ли новые, более дешевые модели?
3. Не изменились ли лимиты и цены?

И помните: документация Google устаревает быстрее, чем вы ее прочитаете. Всегда проверяйте на практике. Если что-то не работает – ищите ответ в changelog последней версии SDK, а не в Stack Overflow шестимесячной давности.

Теперь у вас есть работающий код. Не останавливайтесь на "Hello World". Постройте что-то полезное. Gemini 3 – это не просто чат-бот. Это полноценный партнер для разработки. Используйте его потенциал.