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

Google уже сказала это прямо: Gemini API поддерживает OpenAI compatibility, поэтому его можно вызывать через OpenAI Python SDK, JavaScript SDK и REST; в официальном примере base_url — это https://generativelanguage.googleapis.com/v1beta/openai/, а имя модели — gemini-3.5-flash (Google AI for Developers).
Для команд, у которых уже есть код на OpenAI SDK, это очень практично. Не нужно переписывать клиент, не нужно менять структуру сообщений: сначала замените три настройки, добейтесь успешного запуска, а потом решайте, нужны ли вам нативные возможности Gemini.

Сначала посмотрите, какие три места нужно изменить

В документации Google после примера всё написано очень ясно: меняются только три пункта — api_key, base_url, model. Сам OpenAI Python SDK также поддерживает настройку base_url или OPENAI_BASE_URL (openai-python), а в Node SDK соответствующее поле называется baseURL (openai-node).

Минимальный пример на Python:

from openai import OpenAI

client = OpenAI(
    api_key="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": "用一句话解释什么是向量数据库。"},
    ],
)

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

Если ваш старый код уже использует client.chat.completions.create(), скорее всего, достаточно вынести место инициализации клиента в конфигурацию. Не хардкодьте имя модели в бизнес-функциях: позже при переходе на Batch, Flex или при смене модели будет гораздо больнее.

В Node.js подход тот же

В JavaScript-версии нужно только заменить имя поля с base_url на baseURL:

import OpenAI from "openai";

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

const resp = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [{ role: "user", content: "给我一个 Redis 限流方案。" }],
});

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

REST тоже можно вызывать напрямую: POST https://generativelanguage.googleapis.com/v1beta/openai/chat/completions, в заголовке используйте Authorization: Bearer $GEMINI_API_KEY. Это удобно, если сначала нужно через curl исключить проблемы с SDK, прокси или переменными окружения.

Не оценивайте цену на глаз — считайте по выходным токенам

По состоянию на 2026-06-14 на официальной странице pricing для Gemini указана стандартная цена gemini-3.5-flash: вход — $1.50 / 1M tokens, выход — $9.00 / 1M tokens; для Batch и Flex: вход — $0.75 / 1M tokens, выход — $4.50 / 1M tokens (Gemini API pricing). Там же официально указано, что цена выхода включает thinking tokens, поэтому в задачах с рассуждением не стоит смотреть только на цену входа.

Режим	Вход / 1M tokens	Выход / 1M tokens	Подходящие сценарии
Standard	$1.50	$9.00	Онлайн-запросы, низкая задержка
Batch	$0.75	$4.50	Офлайн-пакетная обработка
Flex	$0.75	$4.50	Допустимо гибкое планирование

Моя рекомендация проста: чаты, агенты и плагины для редакторов сначала запускайте через Standard; суммаризацию логов, очистку данных и офлайн-оценку по возможности переводите на Batch/Flex. В задачах с длинным выходом разница в стоимости становится особенно заметной.

Самые частые ловушки при миграции

Во-первых, не забудьте /openai/ в конце base_url. Многие ошибки 404 и сообщения о несуществующей модели на самом деле возникают из-за обращения к нативному пути Gemini, а не к совместимому пути.
Во-вторых, разделяйте переменные окружения. OPENAI_API_KEY можно продолжать использовать для OpenAI, а для Gemini лучше завести отдельную GEMINI_API_KEY, чтобы в CI два provider не конкурировали за одну переменную.
В-третьих, сначала запустите models.list(). В документации Google есть примеры получения списка моделей и конкретной модели; перед продакшеном используйте их, чтобы проверить регион аккаунта, права доступа и ID модели.
В-четвёртых, для стриминга, function calling и ввода изображений в совместимом слое есть примеры, но не стоит по умолчанию считать, что все параметры OpenAI поддерживаются один к одному. Сначала сделайте регрессионную проверку на одном реальном бизнес-запросе.

Если вы хотите поддерживать меньше ключей

Если команда одновременно использует Claude, GPT и Gemini, по отдельности подавать заявки, привязывать карты и настраивать лимиты довольно утомительно. Более простой путь — использовать onehop: поменяйте base_url в OpenAI SDK на https://api.onehop.ai/v1, используйте ключ onehop — и сможете через OpenAI/Anthropic-совместимые интерфейсы вызывать Claude, GPT и Gemini. Его задача — избавить вас от лишней возни с интеграцией; цена ниже официальной, новым аккаунтам дают $10, карта не нужна.

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{"role": "user", "content": "把这段报错日志总结成三条原因。"}],
)

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

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

Вывод: сначала вынесите всё в конфигурацию, не хардкодьте поставщика

Самая ценная часть OpenAI compatibility в Gemini — не в том, что «появилась ещё одна модель», а в достаточно низкой стоимости миграции. Поместите base_url, api_key и model в конфигурацию, а бизнес-код продолжайте писать через chat completions из OpenAI SDK.
После успешного запуска добавьте ещё три вещи: логирование входных/выходных tokens, выбор Standard или Batch/Flex в зависимости от задачи и серый переключатель для ID модели. Тогда сегодня вы подключите Gemini, завтра Claude или другой совместимый сервис — и вам больше не придётся трогать основной бизнес-код.