Вызов Gemini через OpenAI SDK: руководство по подключению с изменением только base_url, API Key и имени модели

Google говорит прямо: модели Gemini доступны через Python и TypeScript/JavaScript SDK от OpenAI, и по сути нужно изменить три строки кода. В официальной документации по совместимости указан endpoint https://generativelanguage.googleapis.com/v1beta/openai/, а пример модели — gemini-3.5-flash (Совместимость Google с OpenAI). Для существующих проектов на OpenAI SDK это очень удобно: не нужно сначала разбирать абстракцию provider, не нужно менять весь стек вызовов — сначала запустите и убедитесь, что всё работает.

Сначала уточните, какую модель вы собираетесь вызывать

По состоянию на 2026-06-14 страница моделей Google указывает Gemini 3.5 Flash как Stable и сообщает, что код модели — gemini-3.5-flash; у этой модели лимит входа 1 048 576 tokens, лимит выхода 65 536 tokens, она поддерживает входные данные в виде текста, изображений, видео, аудио и PDF, а на выходе выдаёт текст (Gemini 3.5 Flash). Страница модели последний раз обновлялась 2026-05-19 UTC.

Цены тоже нужно сверять с актуальной документацией на день использования. Страница цен Google последний раз обновлялась 2026-06-09 UTC; для gemini-3.5-flash в Standard paid tier указана цена за вход $1.50 / 1M tokens и за выход $9.00 / 1M tokens, причём цена выхода включает thinking tokens; для Batch — вход $0.75, выход $4.50 (Цены Gemini API).

Модель	Статус	Лимит входа	Standard вход	Standard выход
gemini-3.5-flash	Stable	1,048,576	$1.50 / 1M tokens	$9.00 / 1M tokens
gemini-3-flash-preview	Preview	см. страницу модели	$0.50 / 1M tokens	$3.00 / 1M tokens
gemini-3.1-flash-lite	Stable	см. страницу модели	$0.25 / 1M tokens	$1.50 / 1M tokens

gemini-3-flash-preview и gemini-3.1-flash-lite взяты с актуальных страниц моделей и цен Google (Модели, Цены). Preview-модели не стоит сразу использовать как production-значение по умолчанию: версии и лимиты могут меняться.

Python: направьте OpenAI client на Gemini

Сначала установите SDK:

pip install openai
export GEMINI_API_KEY="你的 Gemini API Key"

Затем сохраните привычный способ вызова OpenAI SDK:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {"role": "system", "content": "你是一个简洁的工程助手。"},
        {"role": "user", "content": "用三句话解释什么是 API 兼容层。"},
    ],
)

print(resp.choices[0].message.content)

Реальных изменений всего три: api_key заменить на Gemini key, base_url заменить на OpenAI-compatible endpoint от Google, model заменить на имя модели Gemini. Обратите внимание: в официальном примере URL заканчивается на /; не удаляйте его «на автомате», чтобы потом не разбираться с 404.

TypeScript: всё то же самое через baseURL

В Node-проекте всё аналогично:

npm install openai
export GEMINI_API_KEY="你的 Gemini API Key"

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const response = await openai.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    { role: "user", content: "给我一个 JSON Schema 校验的最小例子。" },
  ],
});

console.log(response.choices[0].message.content);

Если в вашем проекте provider уже вынесен в переменные окружения, изменений будет ещё меньше:

OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
OPENAI_API_KEY="$GEMINI_API_KEY"
OPENAI_MODEL="gemini-3.5-flash"

Во многих старых проектах ловушка именно здесь: ничего страшного, если переменная всё ещё называется OPENAI_API_KEY, её значением может быть Gemini key; то, куда на самом деле уйдёт запрос, определяет base_url/baseURL.

Что делать со streaming, tool calling и thinking

В документации Google по совместимости есть примеры для streaming, function calling, structured outputs, image understanding и других сценариев (Совместимость с OpenAI). В существующих проектах на OpenAI SDK обычно сначала проверяют три вещи: обычный chat, stream=True, tools/function calling. Если всё прошло, уже потом стоит разбираться с возможностями, специфичными для модели.

С параметрами thinking нужно быть осторожнее. В документации по совместимости сказано, что OpenAI-параметр reasoning_effort маппится на настройки thinking в Gemini; но у Gemini 3 и некоторых моделей 2.5 thinking нельзя полностью отключить. Мой совет простой: в первой версии не трогайте thinking, сначала на значениях по умолчанию постройте базовую линию качества и стоимости, а затем отдельно нагрузочно протестируйте длинные задачи, кодовых агентов и цепочки сложного рассуждения.

Если вы хотите меньше управлять разными Key

Прямое подключение к официальному API подходит для серьёзного production: биллинг, лимиты и политика данных прозрачны. Проблема в том, что команды часто используют не только Gemini, но ещё Claude, GPT, а иногда и разные key для разных инструментов. Более простой путь — использовать onehop: поменять base URL в OpenAI SDK на https://api.onehop.ai/v1 и через единый OpenAI/Anthropic-совместимый вход вызывать Claude/GPT/Gemini; новым аккаунтам дают $10, без привязки карты, что удобно для быстрых demo и внутренних инструментов.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEHOP_API_KEY"],
    base_url="https://api.onehop.ai/v1",
)

resp = client.chat.completions.create(
    model=os.environ["ONEHOP_MODEL"],
    messages=[{"role": "user", "content": "把这段日志总结成 5 条排障线索。"}],
)

print(resp.choices[0].message.content)

Здесь я намеренно вынес model в переменную окружения: имена моделей у gateway нужно сверять с консолью, не зашивайте их жёстко в код. Если хотите меньше возиться с биллингом разных провайдеров и слоями совместимости, можно сразу попробовать: вызывать Claude и другие модели через onehop, либо сначала получить кредит: зарегистрируйтесь и получите $10 тестового кредита.

Последняя проверка перед подключением

Перед выходом в production не ограничивайтесь проверкой «возвращается ли текст». Сделайте как минимум четыре проверки: во-первых, убедитесь, что модель всё ещё доступна на текущей странице моделей Google; во-вторых, сверьте на странице цен стоимость входа, выхода, Batch и Search grounding; в-третьих, полноценно логируйте ошибки 401, 429 и 5xx; в-четвёртых, сделайте base_url, api_key и model runtime-конфигурацией, чтобы для переключения модели не приходилось выпускать новый релиз.

Суть этого подключения не в том, чтобы «сменить поставщика моделей», а в том, чтобы развязать уровень SDK и поставщика моделей. Сначала запустите gemini-3.5-flash через официальную Google OpenAI compatibility, а потом решите: прямое подключение, gateway или оба варианта одновременно. Так изменений меньше, а откат быстрее.