openai-gemini: an OpenAI-compatible proxy for the Gemini free tier

What openai-gemini actually solves

Google's Gemini API has a free tier with limits the README calls generous, but a large group of clients, SDKs and command-line tools only know how to talk to the OpenAI API. They hardcode paths like /v1/chat/completions, expect an OpenAI-shaped response, and offer no provider switch. openai-gemini sits between those two facts. It exposes an OpenAI-compatible endpoint that forwards to Gemini using your own API key, so the client keeps its existing code and you keep using the free tier.

The intended user is an individual, not a platform team. The README frames the endpoint as personal and the free hosting tiers as suitable for personal use. If you are building a product with per-tenant keys, quota accounting or an SLA, this is the wrong layer: it is a translation shim you deploy under your own account, and the Gemini key lives in that deployment's environment.

How the translation layer is put together

The repository is deliberately small. The top level holds entry points for four runtimes: node.mjs, deno.mjs, bun.mjs and src/worker.mjs, plus api/ and netlify/ directories for the platform-specific adapters. The shared logic lives in src/, which is why the dev scripts watch src/*.mjs alongside the entry file. Vercel, Netlify, Cloudflare Workers and Deno each get a thin wrapper around the same request handler.

On the wire, the proxy accepts an OpenAI Chat Completions request and maps its fields onto Gemini concepts. The README lists the mapping in detail: the OpenAI system role becomes system_instruction, tool_calls are supported, stop strings become stopSequences with a one-to-five item limit, and response_format covers text, json_object and a select subset of an OpenAPI 3.0 schema object. Media input is handled through Gemini's inlineData part, which is how the project supports vision and audio input as described in the OpenAI specs. Model selection is name-based: if the requested model starts with gemini-, gemma- or models/, that name is passed through; otherwise chat/completions falls back to gemini-flash-latest and embeddings falls back to gemini-embedding-001. Gemini-only features that have no OpenAI equivalent, thinking_config being the notable one, are reachable through the extra_body field.

Deploying openai-gemini and pointing a client at it

You need a personal Google API key from AI Studio before anything else. The README notes that even outside the supported regions it is possible to obtain one using a VPN, which is a statement about Google's availability rules rather than a recommendation from the project.

Deployment options are button-based for Vercel, Netlify and Cloudflare, or CLI-based. The Vercel path is the shortest to describe. After forking, the CLI flow is a single command from the repository root:

vercel deploy

For local work against the same code, the README gives `vercel dev`, and the Node entry point runs directly once dependencies are installed:

npm install
npm run start

Deno and Bun have their own scripts, `npm run start:deno` and `npm run start:bun`. Opening the deployed URL in a browser returns 404 Not Found. That is expected, since the endpoint is not meant for direct browser access.

To use it, set the OpenAI base URL in your client to the deployment address plus /v1. Command-line tools often take it as an environment variable, and the README gives two spellings because clients differ:

OPENAI_BASE_URL="https://my-super-proxy.vercel.app/v1"
OPENAI_API_BASE="https://my-super-proxy.vercel.app/v1"

The API key field in your client should hold the Gemini key. The README warns that the relevant setting is sometimes buried under advanced options or lives in a config file, so expect to hunt for it. Netlify is the one provider with two bases: /v1 for synchronous functions and /edge/v1 for edge functions, each with its own documented limits.

Where openai-gemini stops short

The supported-endpoint list is the honest part of this project, and it is short. chat/completions, embeddings and models are checked. The legacy completions endpoint is not. Within chat/completions, logit_bias, logprobs and top_logprobs are unchecked, so any client that reads token-level probabilities or constrains token choice will get nothing useful back.

Two behaviours are worth reading twice. The n parameter maps to Gemini's candidateCount and is capped below 8, and it does not work with streaming. parallel_tool_calls is listed as always active in Gemini, which means a client that sets it to false cannot actually turn it off. The README also states that the annotations message property is not implemented, so citations that some OpenAI responses carry will not appear.

There is a second class of limitation that has nothing to do with the code. The project runs on serverless platforms, and each platform documents its own function limits. Long streaming responses and large inline media payloads run into those ceilings, not into anything in src/. The README links the limits pages for Vercel Functions, Netlify synchronous and edge functions, and Cloudflare Workers rather than restating them. If your workload is a long agent loop with big images, read those pages before you commit.

openai-gemini compared with running a Gemini SDK directly

The obvious alternative is to call the Gemini API from Google's own SDK and drop the OpenAI-shaped client entirely. That path gives you the full surface: thinking configuration, annotations, the candidate counts Gemini actually supports, and no translation loss on fields the proxy marks unimplemented. The cost is rewriting the client integration, and for a tool you did not write, that is often not possible at all.

The second alternative is a self-hosted gateway that fronts multiple providers. Those exist to solve a different problem, routing and key management across several backends, and they typically expect you to run and update a service. openai-gemini takes the opposite position: one provider, one key, no server to maintain, deployed as a function on a free tier. The trade-off is exactly the field list above. You get compatibility with the OpenAI request shape, and you give up the parts of both APIs that do not overlap. If your client only sends messages, tools, temperature and a model name, that trade costs you nothing.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-03-17. That is roughly six months before today, so treat it as a project with a slow cadence rather than one receiving constant changes. The release history shows the pattern: gemini-3 tagged on 2025-12-22, gemini-2.5-flash on 2025-07-03, and gemini-2.0-flash-thinking-exp on 2024-12-26. Releases track upstream Gemini model launches, which is the maintenance work that matters here, since a new model family is what forces a change.

The dependency surface is one runtime package, @whatwg-node/server at version 0.9, plus nodemon 3 as a dev dependency. That is a small amount to audit and a small amount to upgrade. The practical upgrade cost is not in the code but in redeploying: if you used a button deploy, the repository was forked for you, and the README states the fork is necessary for continuous integration. Pulling upstream changes into that fork is your job.

The licence is MIT. That permits commercial use and modification with the copyright notice retained. It says nothing about Google's terms for the Gemini API itself, which govern your key and your usage regardless of what this proxy is licensed under. Read those separately; nothing here is legal advice.

Editorial conclusion

Adopt openai-gemini if you already have a Gemini API key and a tool that hardcodes the OpenAI endpoint, and you accept that only chat/completions, embeddings and models are wired up. Skip it if you need the legacy completions endpoint, logprobs, logit_bias, or parallel_tool_calls control, since the README marks those unimplemented or always-on. Verify first that your client lets you override the base URL at all, because the project notes that not every tool exposes that setting, and confirm your provider's function limits before you rely on long streaming responses.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. PublicAffairs/openai-gemini on GitHub
4. README
5. Releases