Если вы уже используете OpenAI SDK, самый быстрый способ протестировать Gemini — изменить API-ключ, базовый URL и идентификатор модели. Официальный OpenAI-совместимый базовый URL Gemini API:
https://generativelanguage.googleapis.com/v1beta/openai/
Для Flatkey OpenAI-совместимый базовый URL маршрутизатора:
https://router.flatkey.ai/v1
В этом и заключается суть настройки базового URL совместимости Gemini API с OpenAI и маршрутизатора Flatkey: при прямом использовании Gemini применяется ключ Google API и OpenAI-совместимая конечная точка Google; при использовании Flatkey — ключ Flatkey, маршрутизатор Flatkey и идентификатор модели Gemini, доступный в вашей учетной записи Flatkey.
Используйте прямой маршрут Google, если вам нужен только Gemini и вы хотите максимально близкую к провайдеру настройку. Используйте маршрут Flatkey, если вы уже сравниваете Gemini с GPT, Claude, DeepSeek, Qwen или другими моделями и хотите один OpenAI-совместимый базовый URL, один список моделей и один журнал использования.
Базовый URL совместимости Gemini API с OpenAI и настройка маршрутизатора Flatkey — краткий обзор
| Вариант настройки | Базовый URL | API-ключ | Источник идентификатора модели | Лучше всего подходит для |
|---|---|---|---|---|
| Прямой Gemini | https://generativelanguage.googleapis.com/v1beta/openai/ |
Ключ Gemini API | Документация по моделям Google Gemini API или client.models.list() |
Вам нужен только Gemini, и вы хотите прямой доступ Google. |
| Маршрутизатор Flatkey | https://router.flatkey.ai/v1 |
Ключ Flatkey API | /v1/models Flatkey или Model Directory |
Вы хотите использовать Gemini рядом с другими поставщиками моделей под одним ключом. |
Не смешивайте эти два варианта. Ключ Gemini API не будет проходить аутентификацию в Flatkey, а ключ Flatkey не будет проходить аутентификацию на прямой конечной точке Gemini Google.
Настройка прямого Gemini с OpenAI SDK
OpenAI-совместимый слой Google позволяет сохранить форму OpenAI SDK для стандартных рабочих процессов chat-completion. Важное отличие — конфигурация клиента.
Python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
response = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[
{"role": "user", "content": "Напишите одно предложение о маршрутизации моделей."}
],
)
print(response.choices[0].message.content)
JavaScript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.GEMINI_API_KEY,
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});
const response = await client.chat.completions.create({
model: "gemini-3.8-flash",
messages: [
{ role: "user", content: "Напишите одно предложение о маршрутизации моделей." },
],
});
console.log(response.choices[0].message.content);
REST
curl https://generativelanguage.googleapis.com/v1beta/openai/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{"role": "user", "content": "Напишите одно предложение о маршрутизации модели."}
]
}'
Перед отправкой в продакшн запустите client.models.list() или GET /openai/models по тому же базовому URL. Это позволяет поймать самую распространенную ошибку: скопировать старый ID модели из блога и предполагать, что он по-прежнему существует для вашего аккаунта.
Настройка маршрутизатора Flatkey для Gemini
Flatkey сохраняет форму OpenAI SDK, но базовый URL и ключ снова меняются. Вы используете маршрутизатор Flatkey, а затем выбираете ID модели Gemini из ответа Flatkey /v1/models или из живого Model Directory.
Python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url="https://router.flatkey.ai/v1",
)
models = client.models.list()
gemini_models = [model.id for model in models.data if "gemini" in model.id]
print(gemini_models)
response = client.chat.completions.create(
model=os.environ.get("FLATKEY_GEMINI_MODEL", "gemini-2.5-flash"),
messages=[
{"role": "user", "content": "Напишите одно предложение о маршрутизации модели."}
],
)
print(response.choices[0].message.content)
JavaScript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: "https://router.flatkey.ai/v1",
});
const models = await client.models.list();
console.log(models.data.map((model) => model.id).filter((id) => id.includes("gemini")));
const response = await client.chat.completions.create({
model: process.env.FLATKEY_GEMINI_MODEL || "gemini-2.5-flash",
messages: [
{ role: "user", content: "Напишите одно предложение о маршрутизации модели." },
],
});
console.log(response.choices[0].message.content);
В продакшене не стоит предполагать, что прямой ID модели Google и ID маршрутизируемой модели Flatkey всегда будут одинаковыми. Рассматривайте список моделей как источник истины для того аккаунта, к которому вы обращаетесь.
Переменные окружения, чтобы переключение можно было легко откатить
Грамотная настройка Gemini API OpenAI Compatibility Base URL и Flatkey Router Setup должна позволять легко сравнивать прямые и маршрутизируемые тесты без правок кода приложения.
# Прямой Gemini
GEMINI_API_KEY="..."
GEMINI_OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
GEMINI_MODEL="gemini-3.8-flash"
# Маршрутизатор Flatkey
FLATKEY_API_KEY="..."
FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_GEMINI_MODEL="gemini-2.5-flash"
Затем выберите маршрут из конфигурации:
import os
from openai import OpenAI
route = os.environ.get("AI_ROUTE", "flatkey")
if route == "direct_gemini":
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url=os.environ["GEMINI_OPENAI_BASE_URL"],
)
model = os.environ["GEMINI_MODEL"]
else:
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ["FLATKEY_BASE_URL"],
)
model = os.environ["FLATKEY_GEMINI_MODEL"]
response = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": "Return exactly: route ok"}],
)
Этот шаблон позволяет независимому разработчику сначала протестировать прямой Gemini, затем добавить Flatkey и при необходимости откатиться без переписывания пути запроса.
Чек-лист smoke-теста перед переносом трафика
| Проверка | Прямой Gemini | Маршрутизатор Flatkey |
|---|---|---|
| Аутентификация | Убедитесь, что ключ Gemini работает только с конечной точкой Google. | Убедитесь, что ключ Flatkey работает только с router.flatkey.ai. |
| Список моделей | Выполните client.models.list() по базовому URL Gemini. |
Выполните client.models.list() в Flatkey и отфильтруйте IDs Gemini. |
| Базовый чат | Отправьте короткое нестриминговое завершение чата. | Отправьте тот же запрос через модель Gemini в Flatkey. |
| Стриминг | Проверьте стриминг только если ваше приложение использует стриминг. | Проверьте стриминг на точно маршрутизированной модели, прежде чем включать его для пользователей. |
| Вызов инструментов | Проверьте небольшую схему функции, если ваше приложение использует инструменты. | Подтвердите, что маршрутизированная модель поддерживает поведение инструментов, которое ожидает ваше приложение. |
| Структурированный вывод | Валидируйте реальный JSON-вывод, а не только статус 200. |
Валидируйте ту же схему и поведение повторных попыток. |
| Проверка использования | Проверьте использование Google и ошибки в аккаунте вашего провайдера. | Проверьте журналы использования Flatkey на модель, количество токенов, задержку и стоимость. |
Совместимость с OpenAI не означает, что все функции, специфичные для провайдера, ведут себя одинаково. Это означает, что форма вашего клиента может оставаться достаточно близкой для типовых рабочих процессов SDK. Smoke-тест должен охватывать функции, от которых действительно зависит ваше приложение.
Распространённые ошибки базового URL
Пропуск /openai/ на прямом маршруте Gemini
Для прямых OpenAI-совместимых вызовов Gemini используйте:
https://generativelanguage.googleapis.com/v1beta/openai/
Не используйте нативную конечную точку Gemini generateContent с кодом чата completions из OpenAI SDK. Примеры для нативного Gemini API и OpenAI-совместимые примеры — это разные формы запросов.
Использование base_url в Node или baseURL в Python
Конфигурация Python OpenAI SDK использует base_url. JavaScript SDK использует baseURL.
OpenAI(base_url="https://router.flatkey.ai/v1")
new OpenAI({ baseURL: "https://router.flatkey.ai/v1" })
Рассматривать ID моделей как постоянные
Названия моделей меняются быстрее, чем код настройки SDK. Для прямого подключения проверьте документацию Google по моделям или перечислите модели через совместимый с OpenAI endpoint Gemini. Для Flatkey проверьте /v1/models и Model Directory.
Пропуск логов
Первый успешный ответ — это не конец настройки. После первого запроса Flatkey откройте Usage Logs и проверьте модель, количество токенов, задержку и стоимость. Это делает настройку Gemini API OpenAI Compatibility Base URL и Flatkey Router Setup операционно отслеживаемой, а не просто синтаксически корректной.
Когда Flatkey добавляет ценность
Flatkey полезен, когда Gemini — это один маршрут в более широком стеке моделей. Например:
- Вы хотите иметь Gemini, Claude, GPT, DeepSeek и Qwen за одним совместимым с OpenAI базовым URL.
- Вы тестируете поведение fallback для моделей и не хотите, чтобы отдельные ключи провайдеров были разбросаны по приложениям и агентам.
- Вам нужен общий журнал использования для ID моделей, количества токенов, задержки и стоимости за запрос.
- Вы хотите, чтобы разработчики меняли параметр модели, не меняя клиент SDK.
Если ваше приложение всегда будет обращаться только к Gemini, прямой набор Google может быть достаточным. Если ваш продукт уже сравнивает провайдеров, маршрутизатор Flatkey дает более чистый путь миграции.
Внутренние ссылки, которые стоит держать открытыми
- Flatkey API quickstart
- OpenAI-compatible migration guide
- Gemini vs Claude route checks
- Flatkey Model Directory
- страница цен Flatkey
- страница статуса Flatkey
Часто задаваемые вопросы
Каков официальный базовый URL Gemini, совместимый с OpenAI?
Официальный базовый URL Gemini, совместимый с OpenAI, — https://generativelanguage.googleapis.com/v1beta/openai/. Используйте его с ключом Gemini API, а не с ключом Flatkey.
Какой базовый URL мне использовать для Gemini через Flatkey?
Используйте https://router.flatkey.ai/v1 с ключом Flatkey API. Затем выберите ID модели Gemini из ответа Flatkey на /v1/models или из актуального Model Directory.
Могу ли я использовать один и тот же ID модели Gemini в обоих местах?
Иногда да, но не стоит этого предполагать. Безопасный процесс — перечислить модели для точного маршрута и учетной записи, которые вы используете, а затем зафиксировать этот ID в конфигурации.
Означает ли совместимость с OpenAI полное совпадение по возможностям?
Нет. Рассматривайте совместимость с OpenAI как удобство для SDK и формата запроса. Перед запуском в production проверьте потоковую передачу, инструменты, структурированный вывод, файлы и мультимодальные входы на точной модели и маршруте.
Стоит ли indie hacker начинать напрямую или с Flatkey?
Начинайте напрямую, если вы только проверяете, что Gemini работает. Начинайте с Flatkey, если реальный вопрос — какая модель должна обеспечивать работу продукта, а не может ли Gemini в одиночку ответить на запрос.
Итог
Настройка Gemini API OpenAI Compatibility Base URL и Flatkey Router Setup проста, если разделить два маршрута:
- Direct Gemini:
https://generativelanguage.googleapis.com/v1beta/openai/ - Flatkey router:
https://router.flatkey.ai/v1
Храните ключи отдельно, перечисляйте модели перед вызовом chat completions, тестируйте функции, которые использует ваше приложение, и проверяйте использование после первого запроса. Когда будете готовы сравнивать Gemini с другими провайдерами через единый OpenAI-совместимый слой, создайте ключ Flatkey и переносите по одной рабочей нагрузке за раз.
