Gemini — нативный формат generateContent

Модели Gemini доступны и в OpenAI-совместимом режиме, и в нативном формате Google (/v1beta … :generateContent). Нативный формат открывает то, чего нет в OpenAI-режиме: точный контроль мышления, нативную мультимодальность (изображение/аудио/видео в одном запросе), выполнение кода и детальные поля расхода токенов.

Когда нужен нативный формат

• Полный контроль мышления: thinking_level (Gemini 3) / thinking_budget (2.5), резюме мыслей, thought signatures.
• Нативная мультимодальность: изображения/аудио/видео внутри parts, управление стоимостью через media_resolution — см. Vision.
• Выполнение кода: инструмент code_execution — Python в песочнице.
• Детальный расход: thoughts_token_count, cached_content_token_count.

Если нужен простой текстовый диалог или общий код под несколько провайдеров — берите OpenAI-совместимый режим.

Модели

У части моделей есть суффиксы -thinking / -nothinking (напр. gemini-3-flash-preview-nothinking) — фиксируют режим мышления без правки тела запроса. Полный список и цены — в каталоге.

Быстрый старт

Рекомендуется официальный единый SDK google-genai:

# pip install google-genai
from google import genai

client = genai.Client(
    api_key="sk-nexus-...",
    http_options={"base_url": "https://megaapi.ru"},
)
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Представься одной фразой.",
)
print(response.text)

curl "https://megaapi.ru/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: sk-nexus-..." \
  -d '{
    "contents": [{ "parts": [{ "text": "Представься одной фразой." }] }]
  }'

Контроль мышления

Gemini 3 управляет глубиной через thinking_level, серия 2.5 — через thinking_budget (число токенов; 0 отключает мышление). Токены мышления тарифицируются по цене вывода — выше уровень, дороже счёт.

from google.genai import types

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Реши задачу по шагам.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high", include_thoughts=True),
    ),
)

• Резюме мыслей: include_thoughts=True вернёт part'ы с thought=True.
• Thought signatures: у Gemini 3 — зашифрованное состояние рассуждения. В многоходовых сценариях (особенно с function calling) поле thought_signature из ответа нужно возвращать как есть, иначе цепочка рассуждения прервётся. Официальный SDK делает это автоматически; в «ручном» REST не теряйте поле.

Function Calling

Цикл тот же, что у OpenAI, но формат полей полностью другой — смешивать нельзя:

tools = [{
  "function_declarations": [{
    "name": "get_weather",
    "description": "Текущая погода в городе",
    "parameters": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"]
    }
  }]
}]

Неявное кэширование

Канал Gemini автоматически включает неявное кэширование: когда префикс запроса совпадает с недавним и достаточно длинный, попавшая часть тарифицируется со скидкой (до −90%), поле cached_content_token_count возвращается как есть — без правок кода и без меток.

Попадание видно в usage_metadata.cached_content_token_count (REST: usageMetadata.cachedContentTokenCount) — значение > 0 означает попадание. Для кэш-зависимых высокочастотных сценариев (агенты, RAG, пакетная обработка) выбирайте Claude или OpenAI.

Веб-поиск (Grounding with Google Search)

Нативный формат поддерживает официальный поиск Google: инструмент google_search в generateContent — модель реально ходит в интернет и возвращает ответ с источниками.

curl "https://megaapi.ru/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: sk-nexus-..." \
  -d '{
    "contents": [{"parts": [{"text": "Главные новости ИИ за неделю? Дай 3 пункта с источниками."}]}],
    "tools": [{"google_search": {}}]
  }'

Открыть Gemini в Студии → Function Calling Все модели Gemini