gemini-web2api

中文文档

Convert Google Gemini's web interface into an OpenAI-compatible API. Zero cost, cross-platform, single file.

Features

• Optional API Keys: no auth when api_keys is empty, OpenAI-style Bearer auth when configured
• OpenAI Compatible: Drop-in replacement for /v1/chat/completions and /v1/models
• Tool Calling: Full function calling support (OpenAI format)
• Multiple Models: Flash (3.6), Extended Thinking (20k+ char output), Pro, Auto, Lite
• Thinking Depth: Adjustable via @think=N suffix (0=deepest, 4=shallowest)
• Web Search: Built-in internet access (Gemini's native search)
• Cross-Platform: Pure Python, single optional dependency (httpx for streaming)
• Streaming: SSE streaming support via httpx
• Codex CLI: Responses API (/v1/responses) for OpenAI Codex integration
• Gemini CLI: Google native API (/v1beta/models) for Gemini CLI compatibility

Quick Start

pip install httpx
python gemini_web2api.py

Server starts at http://localhost:8081/v1.

Dual-Port Setup (Anonymous + Cookie)

You can run two instances side by side, each on its own port: one anonymous, one with a cookie.

Create two config files (see .env.example),

.env.anon (anonymous):

PORT=8081

.env.cookie (with cookie):

PORT=8082
COOKIE_FILE=cookie.txt

Start both ports with one command:

python start_all.py

Port	Config	Routing behavior
8081	.env.anon	Anonymous, all models route to Flash-Lite
8082	.env.cookie	Cookie auth, model categories take effect

Point clients at 8081 for anonymous, 8082 for authenticated — the two don't interfere. The startup banner prints Env file: and Cookie: yes/none (anonymous) so you can tell instances apart.

Or start them separately:

python -m gemini_web2api --env-file .env.anon
python -m gemini_web2api --env-file .env.cookie

Note: if the file COOKIE_FILE points to does not exist, the instance silently runs in anonymous mode without erroring. See Cookie configuration below.

Client Configuration

Cherry Studio / ChatBox / any OpenAI client

Field	Value
Base URL	http://localhost:8081/v1
API Key	any api_keys value from config.json; anything if not configured
Model	gemini-3.5-flash-thinking

curl

bash / macOS / Linux

curl http://localhost:8081/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-key" \
  -d '{"model":"gemini-3.5-flash","messages":[{"role":"user","content":"Hello!"}]}'

PowerShell (Windows)

curl.exe --% http://127.0.0.1:8081/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer sk-your-key" -d "{\"model\":\"gemini-3.5-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello!\"}]}"

Note: On Windows PowerShell, use curl.exe and --% so PowerShell does not reinterpret JSON quoting or curl options.

OpenAI Python SDK

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)

Gemini CLI

export GEMINI_API_KEY=none
export GOOGLE_GEMINI_BASE_URL=http://localhost:8081
gemini

Supports Google native API endpoints:

• GET /v1beta/models — list models
• POST /v1beta/models/{model}:generateContent — non-streaming
• POST /v1beta/models/{model}:streamGenerateContent — streaming (SSE)

Available Models

Model	Description	Output
gemini-3.8-flash	All-around model (latest)	~12k chars
gemini-3.6-flash	All-around model	~12k chars
gemini-3.5-flash	Alias for gemini-3.6-flash	~12k chars
gemini-3.5-flash-thinking	Extended thinking, longest output	~20k chars
gemini-3.5-flash-thinking-lite	Adaptive thinking depth	~15k chars
gemini-3.1-pro	Advanced math & code (needs cookie)	~12k chars
gemini-auto	Auto model selection	varies
gemini-flash-lite	Fastest answers, lightweight	~10k chars

Thinking Depth

Append @think=N to any model name:

gemini-3.5-flash-thinking@think=0   # deepest (default)
gemini-3.5-flash-thinking@think=2   # medium
gemini-3.5-flash-thinking@think=4   # shallowest

Cookie Configuration (Detailed)

Why a cookie is needed

Model selection sends a "model category" to the Gemini backend via the [79] field of the request payload, but for anonymous requests the backend ignores the category and routes every model to Flash-Lite (verified by testing). With a cookie, the category is honored:

• gemini-3.8-flash / gemini-3.6-flash (FAST category) → routes to whatever the account's FAST tier currently serves
• gemini-3.1-pro (PRO category) → free Google accounts silently fall back to Flash; Gemini Advanced (paid subscription) is required for real Pro routing
• There is no official unauthenticated API: the free Gemini API tier requires a Google account + AI Studio key; anonymous access is only the web chat's basic tier

Method 1: bundled browser extension (recommended)

The extension exports cookie + SAPISID + XSRF token + gemini_bl in one go:

1. Open chrome://extensions in Chrome → enable Developer mode → Load unpacked → select the gemini-cookie-sync-extension directory from this repo

2. Open gemini.google.com/app, sign in to your Google account, refresh the page

3. Click the extension icon → Inspect session, and confirm it shows:

   XSRF / SNlM0e: present
   gemini_bl / cfb2h: present
   

4. Click Export gemini-auth.json — you get a complete auth file with cookie, sapisid, xsrf_token, gemini_bl, and auth_user

5. Set "cookie_file": "gemini-auth.json" in config.json

The bl version of gemini.google.com changes with deployments; the exported gemini_bl is the current value and more reliable than hand-filling.

Method 2: manual extraction from DevTools

1. Open gemini.google.com, sign in, press F12 to open DevTools

2. Application tab → Cookies in the sidebar → https://gemini.google.com

3. Copy these cookies:

   Cookie	Purpose
   SID / HSID / SSID	Google sign-in state
   APISID / SAPISID	API auth (SAPISID is also used for sapisidhash)
   __Secure-1PSID	Session credential

4. Create cookie.txt in the project root, JSON format:

{"cookie": "SID=xxx; HSID=xxx; SSID=xxx; APISID=xxx; SAPISID=xxx; __Secure-1PSID=xxx", "sapisid": "your SAPISID value"}

Or the plain single-line format:

SID=xxx; HSID=xxx; SSID=xxx; APISID=xxx; SAPISID=xxx; __Secure-1PSID=xxx

Start with:

python gemini_web2api.py --cookie-file cookie.txt

Authenticated account path and XSRF token

If the signed-in Gemini page URL contains an account index, such as:

https://gemini.google.com/u/1/app/...

set auth_user to that index. Authenticated web requests may also require the page XSRF token. In the rendered Gemini page source, this token is exposed as SNlM0e; pass it as xsrf_token in config.json. The server sends it as the at form field.

Example:

{
  "cookie_file": "/app/cookie.txt",
  "auth_user": "1",
  "xsrf_token": "AOOh0P...",
  "gemini_bl": "boq_assistant-bard-web-server_YYYYMMDD.xx_p0"
}

If authenticated requests return HTTP 400 with an xsrf error, refresh Gemini Web, update xsrf_token, and make sure auth_user matches the /u/<index>/ part of the browser URL.

Pro routing requires Gemini Advanced (paid subscription). A free Google account cookie will authenticate but silently fall back to Flash.

Verify the routing takes effect

After starting the cookie instance, send a request and check the server log:

curl http://localhost:8082/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-key" \
  -d '{"model":"gemini-3.8-flash","messages":[{"role":"user","content":"hi"}]}'

The server log prints the model name the backend actually routed to:

[xx:xx:xx] actual model from response: 3.X Flash

That is the model really served by the FAST tier. If it still shows 3.5 Flash-Lite, check the cookie file path and whether the session is still valid.

Configuration

Create config.json in the same directory:

{
  "port": 8081,
  "host": "0.0.0.0",
  "retry_attempts": 3,
  "retry_delay_sec": 2,
  "request_timeout_sec": 180,
  "gemini_bl": "boq_assistant-bard-web-server_20260716.08_p0",
  "auth_user": null,
  "xsrf_token": null,
  "api_keys": ["sk-your-key"],
  "cookie_file": null,
  "proxy": null,
  "log_requests": true,
  "temporary_chats": false
}

Set temporary_chats to true to use Gemini Web temporary chats instead of persisting conversations to the account history.

When api_keys is [], authentication is disabled. When one or more keys are set, /v1/* endpoints require Authorization: Bearer <key> or x-api-key: <key>.

Context Cache

The proxy provides local SQLite-backed context caching. Create a cache with POST /v1/caches, then pass its cache_id in Chat Completions or Responses requests. With auto_cache enabled, stable system context and prior turns in multi-turn requests are cached automatically. Cache usage is reported as the estimated usage.prompt_tokens_details.cached_tokens field; this is proxy-side accounting and is not an upstream Gemini billing value.

Docker

cp config.example.json config.json
docker build -t gemini-web2api .
docker run -d --name gemini-web2api -p 8081:8081 -v ./config.json:/app/config.json gemini-web2api

Or use Docker Compose:

cp config.example.json config.json
docker compose up -d

To mount a cookie file:

docker run -d --name gemini-web2api -p 8081:8081 -v ./config.json:/app/config.json -v ./cookie.txt:/app/cookie.txt gemini-web2api

Set "cookie_file": "/app/cookie.txt" in config.json.

Note: If you get empty responses (content: null) with Docker's default bridge network, switch to host networking: docker run --network host ... or add network_mode: host in your compose file. This is caused by Gemini's upstream rejecting requests from certain Docker NAT IP ranges.

Proxy

If you cannot access gemini.google.com directly (connection timeout), configure a proxy:

Method 1: CLI argument

python gemini_web2api.py --proxy http://127.0.0.1:7890

Method 2: config.json

{"proxy": "http://127.0.0.1:7890"}

Method 3: Environment variable (auto-detected)

export HTTPS_PROXY=http://127.0.0.1:7890
python gemini_web2api.py

Works with Clash, V2Ray, Shadowsocks, or any HTTP proxy.

Tool Calling

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather for a city",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
        }
    }]
)

Image Input

OpenAI-style multimodal messages are supported for Chat Completions and the Responses API. Use either HTTP(S) image URLs or base64 data URLs:

resp = client.chat.completions.create(
    model="gemini-3.6-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this image"},
            {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}}
        ]
    }]
)

Limitations

• Image upload may require cookies: Multimodal input uses Gemini Web's image upload endpoint. If anonymous upload fails, configure a Gemini cookie.
• Not real Pro/Ultra: Without a paid subscription cookie, gemini-3.1-pro routes to the same Flash model. The "Pro" label is a UI preference, not a backend model switch.
• Single-turn only: Each request is an independent conversation. Multi-turn context is simulated by including previous messages in the prompt.
• Rate limits: Google may throttle high-frequency requests. The server retries automatically but sustained heavy use may be blocked.

Requirements

• Python 3.8+
• httpx (pip install httpx) — used for streaming requests
• Network access to gemini.google.com (proxy/VPN may be needed in some regions)

How It Works

This tool reverse-engineers Google Gemini's web StreamGenerate protocol. It sends requests to the same endpoint that the Gemini web app uses, converting between OpenAI's API format and Gemini's internal protobuf-like format.

The model selection is controlled by field [79] in the request payload, mapped from Gemini's frontend JavaScript source (MODE_CATEGORY enum).

Acknowledgments

• Inspired by the open-source API proxy ecosystem

License

MIT

---

致谢

本项目的开发 agent 能力由 GenericAgent 提供。

🚩 友情链接