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

По состоянию на 2026-06-14 документация Google по совместимости Gemini с OpenAI написана предельно прямо: если у вас уже есть код на Python или TypeScript с библиотеками OpenAI, подключить Gemini можно, изменив API Key, base_url и имя модели; в примере документации используется модель gemini-3.5-flash, а страница совместимости в последний раз обновлялась 2026-05-18 (Google AI for Developers). Это не «магия адаптационного слоя», а просто отправка запросов OpenAI SDK на совместимый endpoint, предоставленный Google.

Сначала установите SDK, не меняйте парадигму вызовов

Если ваш проект уже использует официальный OpenAI Python SDK, достаточно оставить chat.completions.create(). Репозиторий Python SDK от OpenAI по-прежнему является официальным источником клиента (openai-python), и совместимый интерфейс Google принимает именно такую форму вызовов.

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": "You are a concise code reviewer."},
        {"role": "user", "content": "Review this Python function for edge cases."},
    ],
)

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

API Key создается в Google AI Studio (AI Studio API key). Обратите внимание на завершающий слэш: /v1beta/openai/, а не /v1beta/models/... из обычного нативного интерфейса Gemini.

REST тоже можно вызывать в формате OpenAI

Для серверной части, отладки через curl и проверок работоспособности шлюза SDK не обязателен. В совместимой документации Google указан REST-путь /openai/chat/completions:

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [
      {"role": "user", "content": "Give me a 5-point migration checklist."}
    ]
  }'

При миграции сначала запустите именно эту команду. Она позволяет разделить проблемы с Key, именем модели, сетевым выходом и платежными правами — это экономит время по сравнению с debug прямо внутри бизнес-сервиса.

Как сопоставляется reasoning_effort

Управление thinking в Gemini частично пересекается с reasoning_effort в OpenAI, и Google явно говорит, что оба параметра не следует передавать одновременно. Совместимый слой сопоставляет параметры в стиле OpenAI с параметрами thinking в Gemini (Google OpenAI compatibility).

OpenAI reasoning_effort	Gemini 3 thinking_level	Gemini 2.5 thinking_budget
minimal	minimal или low	1024
low	low	1024
medium	medium	8192
high	high	24576

Для осторожной миграции сначала не передавайте reasoning_effort и дайте модели работать со значением по умолчанию. Если нужно контролировать расходы, добавьте low для задач с длинным контекстом, а затем наблюдайте за качеством вывода и счетом за token.

Не смотрите только на имя модели при оценке цены

На официальной странице цен Google четко указаны стандартные цены Gemini 2.5 Pro и Flash, единица измерения — за 1 миллион token, а цена вывода включает thinking tokens (Gemini API pricing).

Модель	Цена ввода	Цена вывода
gemini-2.5-pro, prompt ≤ 200k	$1.25	$10.00
gemini-2.5-pro, prompt > 200k	$2.50	$15.00
gemini-2.5-flash, текстовый/графический/видео-ввод	$0.30	$2.50
gemini-2.5-flash, аудиоввод	$1.00	$2.50

Моя рекомендация: для чатов, классификации и легких задач по коду сначала используйте Flash; для сложных рассуждений, синтеза длинных документов и рефакторинга кода переключайтесь на Pro. Порог prompt в 200k у Pro напрямую влияет на цену ввода и вывода, поэтому не стоит без разбора складывать туда логи, фрагменты из поиска и повторяющиеся system prompt.

Чеклист миграции

1. Замените OPENAI_API_KEY на GEMINI_API_KEY, сгенерированный в AI Studio.
2. Измените base_url на https://generativelanguage.googleapis.com/v1beta/openai/.
3. Замените имя модели на совместимую модель Gemini, например gemini-3.5-flash.
4. Сначала проверьте через REST curl, затем подключайте обратно SDK.
5. Временно отключите пользовательский reasoning_effort и добавьте его снова только после подтверждения качества.
6. Фиксируйте стоимость input, output и thinking token, особенно с учетом порога Pro в 200k.

Если вам также нужно подключать Claude/GPT

Если нужен только Gemini, самый чистый путь — официальный совместимый endpoint Google. Но как только в проекте одновременно нужны Claude, GPT и Gemini, несколько Key, несколько счетов и несколько SDK быстро начинают раздражать. Более простой путь — onehop: совместимость с OpenAI/Anthropic, меняете base_url на https://api.onehop.ai/v1 и можете вызывать Claude/GPT/Gemini через тот же OpenAI SDK; сервис делает упор на цены ниже официальных, $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="anthropic/claude-sonnet-4.5",
    messages=[{"role": "user", "content": "Refactor this API handler."}],
)
print(resp.choices[0].message.content)

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