Gemini API OpenAI compatible access is useful for two different migration paths. Google documents a direct OpenAI-compatible endpoint for Gemini, and Flatkey gives teams a router path when they want Gemini access inside the same one-key gateway they use for other models.
The direct Google path is a base URL swap to https://generativelanguage.googleapis.com/v1beta/openai/ with a Gemini API key. The Flatkey path keeps the OpenAI SDK shape but points your client at https://router.flatkey.ai/v1, uses a Flatkey key, and selects a Gemini model ID from the Flatkey catalog before testing logs, cost, and feature support.
This guide explains how to use a Gemini API OpenAI compatible route safely. It covers what Google's compatibility docs actually support, where a router changes the operational model, and what to verify before moving production traffic.
Quick Answer: Gemini API OpenAI Compatible Routing
If your app already uses the OpenAI Python or JavaScript SDK, a Gemini API OpenAI compatible migration starts with configuration, not a rewrite.
| Decision | Direct Gemini API | Gemini Through Flatkey |
|---|---|---|
| API key | Gemini API key from Google AI Studio | Flatkey API key |
| Base URL | https://generativelanguage.googleapis.com/v1beta/openai/ |
https://router.flatkey.ai/v1 |
| Primary goal | Call Gemini using OpenAI SDK syntax | Route Gemini beside other model providers behind one key |
| Model choice | Google Gemini model ID from Google docs | Flatkey Gemini model ID from pricing or dashboard |
| Validation | Response, model behavior, Google billing | Response, Flatkey usage log, pricing unit, quota, rollback |
Use the direct Google endpoint when you only need Gemini and want provider-native account control. Use the Flatkey router when Gemini should sit beside GPT, Claude, DeepSeek, Qwen, image, video, and other model access behind one key, one dashboard, and one billing surface.
What Google's OpenAI Compatibility Docs Confirm
Google's OpenAI compatibility documentation says Gemini models can be accessed with OpenAI libraries for Python and JavaScript, plus REST, by updating the API key, base URL, and model. The documented direct base URL is https://generativelanguage.googleapis.com/v1beta/openai/.
The same page shows examples for chat completions, streaming responses, function calling, image understanding, and embeddings. It also notes that OpenAI-compatible file upload and download are currently not supported, so file workflows need Google GenAI client handling instead of assuming full OpenAI file parity.
That is the main lesson for any Gemini API OpenAI compatible guide: compatibility is endpoint and feature specific. A chat completion can be a clean base URL migration while file upload, image, batch, tool, or embedding workflows still deserve their own tests.
Where Flatkey Changes The Gemini Setup
Flatkey does not ask you to replace an OpenAI-compatible app with a new provider SDK for the first test. Flatkey's public product surface is built around one API key, no separate provider accounts, clear pricing, unified billing, and one dashboard for keys, usage, and routing. It also shows the OpenAI-compatible router base URL as https://router.flatkey.ai/v1.
For a Gemini API OpenAI compatible route through Flatkey, the important change is not the OpenAI SDK method name. The important change is operational:
- You select a Gemini model ID from Flatkey, not only from Google's docs.
- You verify usage and cost in Flatkey after the request, not only in the application response.
- You keep Gemini inside the same routing and quota workflow as other providers.
- You avoid creating a separate provider-account path for every team or tool.
- You keep rollback simple by controlling base URL, key, and model through configuration.
Flatkey's live pricing snapshot checked for this article included Gemini-named catalog rows, but availability and exact model names can change. Treat the catalog as a publish-day source of truth: choose the model in pricing or the dashboard, then test the exact model ID before production traffic.
Base URL Migration Pattern
Start by separating the migration into three environment variables:
FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_GEMINI_MODEL="replace-with-flatkey-gemini-model-id"That gives you a clean switch for any Gemini API OpenAI compatible client. The app code keeps the OpenAI-compatible SDK path. Configuration decides whether the request goes to Google directly, Flatkey, or another compatible endpoint.
| Config Item | Why It Matters | What To Avoid |
|---|---|---|
| Base URL | Keeps the router choice outside business logic. | Hardcoding provider URLs in many files. |
| API key | Separates direct provider credentials from router credentials. | Reusing old provider keys for a Flatkey route. |
| Model ID | Lets you map a Google model to a Flatkey catalog model deliberately. | Assuming every provider model alias exists behind the router. |
| Rollback values | Lets you restore the previous route quickly. | Making rollback require a code deploy. |
Python Template For Flatkey Gemini Routing
Template only: run this with a valid Flatkey key and a confirmed Flatkey Gemini model ID before using it in production.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_GEMINI_MODEL"],
messages=[
{
"role": "user",
"content": "Reply with one sentence confirming the Gemini route is configured.",
}
],
)
print(response.choices[0].message.content)
print(response.usage)The OpenAI SDK method is familiar, but do not treat this as a completed Gemini API OpenAI compatible migration until the Flatkey usage log shows the request, model, token usage, status, and cost.
JavaScript Template For Flatkey Gemini Routing
Template only: run with a valid Flatkey key and a confirmed model ID from the current Flatkey catalog.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.OPENAI_BASE_URL || "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_GEMINI_MODEL,
messages: [
{
role: "user",
content: "Reply with one sentence confirming the Gemini route is configured.",
},
],
});
console.log(response.choices[0].message.content);
console.log(response.usage);For teams already using OpenAI-compatible SDKs, this keeps the migration small. The production work is in feature validation, model mapping, quotas, and billing checks.
Feature Checklist Before Production
Use this checklist before treating a Gemini API OpenAI compatible route as ready.
| Feature | Google Docs Signal | Flatkey Router Check |
|---|---|---|
| Basic chat completions | OpenAI SDK and REST examples are documented. | Confirm response and Flatkey usage log. |
| Streaming | Google documents streaming with OpenAI-style calls. | Test stream handling, timeout, and partial output parsing. |
| Function calling | Google documents tool/function calling through compatibility examples. | Test your exact tool schema and tool choice behavior. |
| Image understanding | Google documents image input through chat completions. | Confirm the Flatkey model accepts the image format your SDK sends. |
| Embeddings and batch | Google documents embeddings and batch-related examples. | Test as a separate endpoint path, not as a chat assumption. |
| File upload/download | Google says OpenAI-compatible upload/download is currently not supported. | Use a separate provider-native file plan if your workflow depends on files. |
| Pricing | Google maintains a Gemini Developer API pricing page. | Use Flatkey pricing for routed usage, then verify actual cost logs. |
Smoke Test Runbook
A Gemini API OpenAI compatible smoke test should prove both API behavior and router visibility.
- Choose one Gemini model ID from the current Flatkey catalog.
- Create or select a low-risk Flatkey key for testing.
- Set
OPENAI_BASE_URLtohttps://router.flatkey.ai/v1. - Run a simple non-streaming chat prompt.
- Confirm the assistant message shape matches your app parser.
- Check Flatkey usage logs for model, status, tokens, and cost.
- Run a bad-model test and record the error shape.
- Run streaming, tool calls, vision, or embeddings only if your app uses them.
- Set a small quota before any real traffic is sent.
- Keep the previous provider base URL and model as rollback config.
The goal is not just to make a Gemini response appear. The goal is to know where the route went, what it cost, how failures look, and how quickly you can roll back.
Common Mistakes
- Using Google's direct Gemini OpenAI-compatible base URL when you intended to test Flatkey.
- Using a Google model ID without confirming the Flatkey catalog model string.
- Assuming file upload/download works through every OpenAI-compatible path.
- Testing only chat completions when production uses streaming or tools.
- Skipping the usage-log and billing check after a successful response.
- Publishing code snippets with real-looking keys or untested production model IDs.
These are small details, but they are where most Gemini API OpenAI compatible migrations fail. A router makes access easier; it does not remove the need to test the exact request shape.
How This Fits With Existing Flatkey Migration Guides
If this is your first router migration, start with the broader OpenAI-compatible API migration guide. It covers the base URL pattern, environment variables, smoke tests, rollback, and dashboard checks that apply to any provider.
Then use this Gemini-specific guide for the provider details: Google's direct compatibility endpoint, Gemini model selection, feature support, and file-handling limitations. For adjacent model-access patterns, compare the DeepSeek API access guide and the Claude API proxy vs router guide.
FAQ
Is the Gemini API OpenAI compatible?
Google documents OpenAI compatibility for Gemini through OpenAI Python and JavaScript libraries plus REST examples. That does not mean every OpenAI endpoint or parameter has identical behavior, so test the exact feature your app uses.
What is the direct Gemini OpenAI base URL?
Google's documented direct OpenAI-compatible base URL is https://generativelanguage.googleapis.com/v1beta/openai/. Use that when calling Google directly with a Gemini API key.
What base URL should I use for Gemini through Flatkey?
Use https://router.flatkey.ai/v1 for an OpenAI-compatible Flatkey route. Then choose a Gemini model ID from Flatkey pricing or the dashboard and test the request before production.
Can I use the same model ID from Google's docs in Flatkey?
Not automatically. Model strings and availability can vary by catalog and route. Pick the model ID from Flatkey on the day you test and keep it in configuration.
Does OpenAI-compatible mean full feature parity?
No. OpenAI-compatible usually means common request and response shapes work for supported endpoints. Google specifically notes that OpenAI-compatible upload and download are not currently supported, so feature-level testing is required.
How should I budget Gemini through a router?
Use Google's pricing docs for direct Gemini context and Flatkey pricing for routed usage. Then verify the actual request cost in Flatkey logs because model, cache, batch, and modality units can differ.
View Pricing Before You Route Production Traffic
Gemini API OpenAI compatible access is a practical migration path when your app already uses OpenAI-style SDK calls. Keep the change small: update the base URL, use a Flatkey key, select a current Gemini model, run the smoke tests, and verify usage and pricing before rollout.
View Pricing to confirm the current Flatkey Gemini model options and cost units before you send production traffic.
