gemini-web2api: The Shadow API That Makes Gemini Look Like OpenAI
A minimal Python proxy that reverse-engineers Google’s web chat surface, translates it into OpenAI-compatible requests, and smuggles in tool calling, streaming, and multimodal uploads.
- gemini-web2api is best understood as a compatibility layer, not a model wrapper, because it makes a web-only Gemini surface behave like an OpenAI backend.
- Its biggest trick is protocol translation, where structured chat input becomes Google-shaped request payloads and then returns as OpenAI-shaped streams.
- Tool calls and multimodal uploads are not native strengths here, they are reconstructed through prompt shims and a separate upload path.
- The project sits in a growing market where interface compatibility can matter more than official purity or architectural elegance.
A Gemini backend that pretends to be OpenAI. That is the real product here. If your tool already speaks OpenAI’s request shape, gemini-web2api lets it talk to Gemini with almost no client-side changes.
Convert Google Gemini web into OpenAI-compatible API. Zero auth, cross-platform, single file.
Why this repo exists
The official Gemini API already exists. This project aims at a different layer: the web surface, the browser session, the internals Google did not mean to expose as a public SDK. That matters if you want a drop-in backup for OpenAI-shaped apps, or if you want access to web-first behavior without rebuilding your stack around Google’s official path.
| Path | Setup | Compatibility | Fragility | Best for |
|---|---|---|---|---|
| Official Gemini API | API key, official docs, structured access | Native for Gemini clients, not OpenAI-shaped tools | Lower protocol risk, higher platform constraints | Teams that want supported, stable access |
| Generic browser automation | Custom scripts, browser sessions, scraping logic | Usually poor unless you build adapters yourself | High, because UI changes break flows | One-off experiments and bespoke automation |
| gemini-web2api | Run a Python proxy, point clients at it | High, because it speaks OpenAI-compatible requests | Medium to high, because it tracks a moving web surface | Apps that already depend on OpenAI-style endpoints |
The table is the point. This repo occupies the awkward but useful middle: more compatible than scraping, less official than the API, and much easier to slot into existing tooling than a fresh integration.
The real trick: protocol translation, not just request forwarding
How tool calls are faked into existence
The clever part in tools.py is not that Gemini suddenly gains a native tool API. It does not. The repo instead instructs the model to emit fenced tool_call blocks, then parses them back into structured calls. In other words, the system manufactures a tool protocol by making the model write one.
# Tool Use
You can call the following tools. Call format:
```tool_call
{"name": "func_name", "arguments": {...}}
```
# Parse back into structured calls
pattern = r'```tool_call\s*\n(.*?)\n```'| Native tool API | Prompt-injected tool calling |
|---|---|
| Model returns structured tool events directly | Model is coached to print a fenced block |
| Schema enforced by the platform | Schema reconstructed by the proxy |
| Usually stable across releases | Depends on prompt compliance and parser tolerance |
| Best when the provider owns the full stack | Best when the provider exposes only a web surface |
This is fragile, but not silly. It is a practical compromise when the underlying surface gives you text, not first-class function calls.
Why the multimodal path is the hardest part
Image support is the least visible part of the repo and the most browser-specific. The upload flow in multimodal.py has to discover session tokens, perform a resumable upload handshake, and hand Gemini a file reference it will accept. That is a separate protocol stack, not a small extension.
That is also why the project feels more like infrastructure than a helper script. The proxy is doing the annoying work that makes a polished client experience possible: cookies, session state, upload choreography, and stream reassembly.
The author chose boring tools on purpose
This project is for educational purposes only. Do not use it for commercial purposes. The author is not responsible for any consequences caused by the use of this project.
The codebase leans into the standard library, thin abstractions, and a small footprint. That choice matters because reverse-engineering projects do not fail from lack of features first. They fail from entropy. Simplicity buys the author a better chance of keeping up with a moving target.
The same logic shows up in the server design and cookie reload behavior. The goal is not elegance for its own sake. The goal is a proxy that can survive real traffic, real sessions, and the churn of a web product that was never meant to be a stable backend.
What this project says about the AI stack
`gemini-web2api` sits in a larger pattern: the most valuable AI layer is often not the model, but the interface that makes the model easy to consume. Official APIs, unofficial wrappers, browser automation, and compatibility layers are competing to own that interface.
| Layer | What it optimizes for | What it sacrifices |
|---|---|---|
| Official API | Stability and support | Access to web-only behavior |
| Browser automation | Maximum reach into the UI | Reliability and clean integration |
| Compatibility proxy | Client reuse and drop-in adoption | Long-term certainty |
That trade-off is the whole thesis. If your app, agent, or workflow already assumes an OpenAI-shaped world, the fastest path to Gemini may be a bridge that speaks both dialects. This repo is that bridge.
Bottom line
gemini-web2api is valuable because it turns a fragile web UI into something that behaves like a programmable backend. It is also a reminder that in AI infrastructure, interface control is often more important than raw model access.
