Skip to Content
МоделиGeminiОбзор

Семейство Gemini

Текстовые модели Gemini от Google, прежде всего серия Gemini 3.x. Поддерживаются два способа вызова: нативный API Gemini (можно напрямую использовать официальный SDK google-genai) и OpenAI-совместимый API.

Типичные задачи

Управление thinking Thinking включён по умолчанию; как уменьшить его объём, если ответ занимает много времени.Google Поиск Получение актуальной информации из интернета с указанием источников.PDF и аудио Загрузка документов и аудио для анализа.Разбор ошибок Обрезанный ответ, модель снята с поддержки, превышение контекста.Использование в Gemini CLI Настройка подключения и частые вопросы.

Модели

Модели принимают на вход текст, изображения, аудио и PDF; контекст — около 1M токенов. Полный список моделей и актуальные цены см. на странице моделей ; их также можно получить через Models API. Модели генерации изображений описаны в разделе Nano Banana.

Основные ID моделей (копируйте без изменений)
Gemini 3.8 Flashgoogle/gemini-3.8-flash
Gemini 3.1 Pro Previewgoogle/gemini-3.1-pro-preview
Gemini 3.5 Flash-Litegoogle/gemini-3.5-flash-liteПо умолчанию без thinking; быстрые ответы
Gemini 3.5 Flashgoogle/gemini-3.5-flash

Префикс google/ в ID модели можно опустить. В адресе нативного API префикс тоже можно указывать или не указывать: подходят и models/google/gemini-3.8-flash:generateContent, и models/gemini-3.8-flash:generateContent.

Выбор API

ГлавноеЕсли нужно тонко управлять thinking или получать источники Google Поиска, используйте нативный API Gemini.
Нативный API Gemini (рекомендуется)OpenAI-совместимый API
АдресPOST https://api.ofox.ai/gemini/v1beta/models/<ID модели>:generateContentPOST https://api.ofox.ai/v1/chat/completions
SDKgoogle-genai, base_url — https://api.ofox.ai/geminiOpenAI SDK, base_url — https://api.ofox.ai/v1
Аутентификацияx-goog-api-key: <Key>; также принимается Authorization: Bearer <Key>Authorization: Bearer <Key>
Потоковый вывод:streamGenerateContent?alt=sse"stream": true
ThinkingthinkingConfig; можно получать сводку thinkingreasoning_effort или reasoning; возвращается reasoning_details
Google Поискtools: [{"google_search": {}}]; возвращаются источники и поисковые запросыweb_search_options; возвращается только ответ

Нативный API не поддерживает передачу ключа через URL-параметр ?key= — в этом случае возвращается 401. Используйте заголовок запроса.

Модели Gemini сейчас предоставляет Google Vertex AI (google_vertex). Полный список параметров запроса см. в разделе Generate Content.

Примеры вызова

gemini_basic.py
import os
from google import genai
 
client = genai.Client(
    api_key=os.environ["OFOX_API_KEY"],
    http_options={"api_version": "v1beta", "base_url": "https://api.ofox.ai/gemini"},
)
 
resp = client.models.generate_content(
    model="google/gemini-3.8-flash",
    contents="Объясни одним предложением, что такое идемпотентность.",
)
print(resp.text)

Кэширование промптов

Gemini автоматически выполняет неявное кэширование: если префикс запроса совпадает с недавними запросами и достаточно длинный, попавшая в кэш часть оплачивается по цене чтения из кэша; менять запросы не нужно.

ПараметрОписание
Проверка попаданияВ нативном API usageMetadata.cachedContentTokenCount больше 0; в OpenAI-совместимом API usage.prompt_tokens_details.cached_tokens больше 0
СтабильностьНеявное кэширование работает по принципу best effort: даже запросы с одинаковым префиксом могут не попасть в кэш
Детерминированное кэшированиеЕсли нужно стабильно переиспользовать большие фрагменты содержимого, используйте явный кэш — см. Явный кэш Gemini

Типичные ошибки

ГлавноеЕсли ответ обрывается на середине, обычно это значит, что thinking израсходовал лимит вывода; это не ошибка — проверьте finishReason.
HTTP · статусТекст ошибкиПричинаРешение
200, finishReason: "MAX_TOKENS"—Суммарная длина thinking и ответа достигла maxOutputTokens, ответ обрезанУвеличьте maxOutputTokens или уменьшите объём thinking через thinkingLevel: "low". В OpenAI-совместимом API это finish_reason: "length"
400 INVALID_ARGUMENTThe input token count exceeds the maximum number of tokens allowed 1048576.Входные данные превышают контекст моделиСократите входные данные
410 model_deprecatedModel 'google/gemini-3-pro-preview' is deprecated and no longer accepts requests; please switch to an active modelPreview-модель снята с поддержкиПерейдите на стабильную версию или новую preview-версию, например google/gemini-3.1-pro-preview
404 model_not_foundModel 'google/gemini-9-pro' not foundОшибка в написании ID моделиСкопируйте ID модели с этой страницы
401—Ключ передан через ?key=Используйте заголовок x-goog-api-key
Таймаут запроса—Thinking включён по умолчанию, и сложные запросы выполняются долгоИспользуйте потоковый вывод, установите таймаут клиента не менее 300 секунд или уменьшите объём thinking

Прочие общие ошибки: Обработка ошибок.

Официальная документация

Официальная документация описывает поведение при прямом обращении к Google. При вызове через OfoxAI ID моделей и адреса API указывайте так, как описано на этой странице.

Часто задаваемые вопросы

Как записывать ID моделей Gemini?

Стандартная запись — google/gemini-3.8-flash; префикс google/ можно опустить. В адресе нативного API префикс тоже можно указывать или не указывать.

Что делать, если Gemini отвечает очень медленно?

Все модели Gemini, кроме Flash-Lite, по умолчанию используют thinking, и на сложные вопросы ответ может занимать больше минуты. Передайте thinkingLevel: "low", чтобы уменьшить объём thinking; у некоторых моделей можно передать thinkingBudget: 0, чтобы отключить thinking, — или перейдите на модель Flash-Lite, которая по умолчанию работает без thinking.

Как отключить thinking у Gemini?

У 3.5 Flash и 3 Flash Preview thinking отключается через thinkingBudget: 0. У 3.1 Pro Preview и 3.8 Flash полностью отключить его нельзя, но можно уменьшить объём через thinkingLevel: "low". Серия Flash-Lite по умолчанию работает без thinking.

Ответ Gemini обрезан, а finishReason равен MAX_TOKENS?

Токены thinking тоже учитываются в maxOutputTokens. Увеличьте maxOutputTokens или уменьшите объём thinking.

Может ли Gemini искать в интернете?

Да. В нативном API добавьте в tools {"google_search": {}} — в groundingMetadata ответа будут поисковые запросы и источники. В OpenAI-совместимом API передайте web_search_options: {}.

Как проходит аутентификация в нативном API Gemini?

Передайте API-ключ OfoxAI в заголовке x-goog-api-key; также принимается Authorization: Bearer. URL-параметр ?key= не поддерживается.

Ошибка 410 model_deprecated?

Эта preview-модель снята с поддержки, например gemini-3-pro-preview. Перейдите на google/gemini-3.1-pro-preview или стабильную модель.

Может ли Gemini анализировать аудио и PDF?

Да. В нативном API файлы в кодировке base64 передаются через inline_data; в OpenAI-совместимом API PDF передаётся в блоке содержимого file, а аудио — в блоке содержимого input_audio.

Обновлено
Thinking