SDK и REST API: в чём разница и что выбрать

В предыдущих уроках ты обращался к API напрямую через requests: сам указывал URL, HTTP-метод, заголовки и параметры. В пятом уроке используется официальный SDK Gemini. Это не другой API, а более удобный способ работать с ним из Python.

Сначала короткий ответ

• REST API — правила общения с сервисом по HTTP: адреса, методы, заголовки, тело запроса и формат ответа.
• SDK — библиотека для конкретного языка, которая превращает эти правила в классы и методы.

SDK обычно сам отправляет HTTP-запрос. Он не заменяет серверный API и не отменяет статус-коды, квоты или сетевые ошибки.

Один запрос двумя способами

Например, Interactions API Gemini можно вызвать напрямую:

import requests

response = requests.post(
    "https://generativelanguage.googleapis.com/v1beta/interactions",
    headers={
        "x-goog-api-key": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "model": "gemini-3.6-flash",
        "input": "Объясни REST API двумя предложениями",
        "store": False,
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()

Через официальный пакет google-genai тот же смысл выражается короче:

from google import genai

with genai.Client(api_key=API_KEY) as client:
    interaction = client.interactions.create(
        model="gemini-3.6-flash",
        input="Объясни REST API двумя предложениями",
        store=False,
    )

print(interaction.output_text)

Во втором варианте SDK знает адрес endpoint, собирает тело запроса и превращает ответ в Python-объект. Но смысл операции остаётся тем же.

Что действительно даёт SDK

Официальный SDK обычно предоставляет:

• методы с понятными именами вместо ручной сборки URL;
• сериализацию Python-объектов в JSON и обратно;
• модели ответов и подсказки типов для IDE;
• удобный доступ к результату, например interaction.output_text;
• поддержку специальных возможностей API: streaming, structured output и продолжение interaction;
• единый способ настраивать клиент, timeout и другие HTTP-параметры.

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

Когда удобнее SDK

Выбирай официальный SDK, если:

• он активно поддерживается для твоего языка;
• API имеет сложные структуры, streaming или несколько режимов работы;
• важны типы, автодополнение и скорость разработки;
• документация сервиса показывает актуальные примеры через этот SDK.

Для Gemini сейчас используй google-genai. Старый пакет google-generativeai, импорт google.generativeai и настройка genai.configure() больше не подходят для нового проекта.

Когда удобнее прямой HTTP

Используй requests или httpx, если:

• официального SDK нет либо он отстаёт от API;
• нужен endpoint, который SDK ещё не поддерживает;
• важно полностью контролировать URL, заголовки и тело запроса;
• пишешь небольшой скрипт и не хочешь добавлять крупную зависимость;
• изучаешь механику HTTP и хочешь видеть каждый этап запроса.

Прямой HTTP — не «плохой» или устаревший вариант. Иногда он проще и прозрачнее.

Как оценить SDK перед установкой

Не выбирай библиотеку только по похожему названию. Проверь:

1. Ссылка на пакет есть в официальной документации сервиса.
2. Поддерживается нужный язык и нужная возможность API.
3. Примеры используют актуальный импорт и методы.
4. Версия зависимости зафиксирована разумным диапазоном в requirements.txt.
5. Понятно, какие ошибки выбрасывает библиотека и как задаются timeout или retry.

Для проекта урока зависимость выглядит так:

google-genai>=2.17,<3

Устанавливай зависимости из файла:

python -m pip install -r requirements.txt

Итог

REST API — это контракт сервиса, а SDK — удобный клиент для этого контракта. Сначала понимай, какой запрос выполняется, затем выбирай наиболее надёжный способ его отправить.

При любом подходе проверяй входные данные, храни ключ вне кода, собирай сетевую работу в одном месте и понятно обрабатывай ожидаемые ошибки. Для Gemini правильный выбор — актуальный официальный google-genai; для небольшого или неподдерживаемого endpoint прямой HTTP может оказаться лучше.