gemini‑web2api – Turn Google Gemini’s web UI into an OpenAI‑compatible API

What it is – A single‑file Python server that talks to the private Gemini web endpoints and re‑exposes them as the OpenAI /v1/chat/completions (and related) API. It lets any OpenAI‑compatible client (ChatGPT‑style UI, openai Python SDK, curl, etc.) use Gemini models without a Google‑specific client.

---

Core features (as described in the README)

Feature	What it means
OpenAI‑compatible endpoints	Implements /v1/chat/completions, /v1/models, plus a special /v1/responses for Codex‑style use and the native Gemini /v1beta/* endpoints.
Optional API‑key auth	If api_keys in config.json is empty the server is open; otherwise it requires a Bearer token (or x‑api‑key).
Tool/function calling	Accepts OpenAI‑style function definitions and returns function‑call objects, enabling tool use.
Multimodal image input	Supports OpenAI‑style image_url messages (URL or base64) for Gemini’s image‑understanding endpoint.
Streaming (SSE)	Uses httpx to forward Gemini’s Server‑Sent Events so clients can receive partial tokens.
Multiple Gemini models	Provides aliases such as gemini-3.6-flash, gemini-3.5-flash-thinking, gemini-3.1-pro, etc., with output length hints (10‑20 k characters).
Adjustable “thinking depth”	Append @think=N (0‑4) to a model name to request deeper or shallower reasoning.
Web search integration	Leverages Gemini’s built‑in search, so a prompt can trigger internet look‑ups automatically.
Cross‑platform, single‑file	Pure Python (requires only httpx).
Docker support	Official Dockerfile and compose snippet for easy deployment.
Proxy support	Can route traffic through an HTTP proxy (CLI flag, config, or HTTPS_PROXY).

---

Quick start (from the README)

pip install httpx               # only dependency
python gemini_web2api.py        # starts server on http://localhost:8081/v1

Using an OpenAI client

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8081/v1", api_key="sk‑your‑key")
resp = client.chat.completions.create(
    model="gemini-3.5-flash-thinking",
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)
print(resp.choices[0].message.content)

The same endpoint works with curl, Postman, or any UI that lets you set a custom base URL.

---

Configuration highlights

• config.json lives next to the script. Key fields:
  • port, host – where the server listens.
  • api_keys – list of strings; if empty, no auth is required.
  • cookie_file – path to a file containing Google authentication cookies (required for the paid Gemini Advanced models and for image upload).
  • auth_user / xsrf_token – needed when the cookie belongs to a multi‑account Google session.
  • proxy – optional HTTP proxy URL.
  • temporary_chats – when true, conversations are not saved to the Google account history.
• Example config.json is provided in the repo; copy config.example.json and edit as needed.

---

Model list (README table)

Model name	Description	Approx. max output
gemini-3.6-flash (alias gemini-3.5-flash)	General‑purpose, latest model	~12 k characters
gemini-3.5-flash-thinking	“Extended thinking”, longest output	~20 k characters
gemini-3.5-flash-thinking-lite	Adaptive depth, medium output	~15 k characters
gemini-3.1-pro	Advanced math & code (needs paid‑subscription cookie)	~12 k characters
gemini-auto	Auto‑selects best model	varies
gemini-flash-lite	Fastest, lightweight	~10 k characters

Depth can be changed with @think=N suffix (0 = deepest, 4 = shallowest).

---

Limitations & gotchas (as listed)

• Image upload may need cookies – anonymous users cannot use the multimodal endpoint; provide a valid Gemini Advanced cookie.
• “Pro” label is only UI – without a paid subscription cookie, gemini-3.1-pro falls back to the Flash model.
• Stateless per request – the server does not keep conversation state; you must include prior messages in the request payload if you want multi‑turn context.
• Google rate‑limits – heavy traffic can be throttled; the server retries a few times but sustained abuse may be blocked.
• Docker networking – some NAT ranges are blocked by Gemini; use host networking if you see empty responses.

---

How it works (briefly)

The script reverse‑engineers the protobuf‑like payload that the Gemini web app sends to its StreamGenerate endpoint. It translates OpenAI JSON request bodies into that format, forwards the request with httpx, then converts the response back into OpenAI‑style JSON (including streaming chunks). Model selection is driven by a field ([79]) extracted from Gemini’s frontend JavaScript.

---

License

MIT – you can freely use, modify, and redistribute the code.