gemini-web2api

English | 中文文档

High-performance Go proxy converting Google Gemini's web interface into an OpenAI-compatible API. Zero cost, cross-platform, single static binary.

This is a complete Go rewrite of the original Python gemini-web2api. It features massive concurrency throughput, minimal memory footprint, and enhanced capabilities such as TLS Impersonation for WAF bypass.

Key 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, /v1/models, and /v1/responses (Codex CLI).
• Multimodal (Vision): Fully supports sending images (image_url / base64) to Gemini using Scotty Resumable Upload protocol natively with built-in image compression.
• TLS Impersonation: Built-in support to bypass Cloudflare/WAF by mimicking Chrome/Edge TLS fingerprints using tls-client 🔥.
• Tool Calling: Full function calling support (OpenAI format).
• Multiple Models: Flash (3.6), Extended Thinking (20k+ char output), Pro, Auto, Lite.
• Thinking Depth: Adjustable reasoning via @think=N suffix (0=deepest, 4=shallowest).
• Web Search: Built-in internet access (Gemini's native search).
• High Performance: Pure Go static binary with high concurrent SSE streaming throughput and minimal memory footprint.
• Cross-Platform: Zero runtime dependencies, single static binary.
• Codex CLI: Responses API (/v1/responses) for OpenAI Codex integration.
• Gemini CLI: Google native API (/v1beta/models) for Gemini CLI compatibility.

Quick Start

1. Download Pre-built Binary (Recommended)

Download the pre-compiled binary for your OS (Linux, macOS, Windows) from the Releases page:

Linux / macOS:

chmod +x gemini-web2api
./gemini-web2api --port 8081

Windows (PowerShell / Command Prompt):

.\gemini-web2api.exe --port 8081

2. Install via Go Toolchain

If you have Go 1.22+ installed on your system:

go install github.com/ikhsan3adi/gemini-web2api@latest

This compiles and places the binary directly into your $GOPATH/bin (or %USERPROFILE%\go\bin). Run it from anywhere:

gemini-web2api --port 8081

3. Build from Source

Prerequisites: Go 1.22+

git clone https://github.com/ikhsan3adi/gemini-web2api.git
cd gemini-web2api

After building, run the executable:

Linux / macOS:

go build -o gemini-web2api .
./gemini-web2api --port 8081

Windows (PowerShell / Command Prompt):

go build -o gemini-web2api.exe .
.\gemini-web2api.exe --port 8081

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

4. Run via Docker

Before running via Docker, copy the example config file:

cp config.example.json config.json

Option A: Run pre-built GHCR Image (No git clone needed)

docker run -d --name gemini-web2api -p 8081:8081 ghcr.io/ikhsan3adi/gemini-web2api:latest

Option B: Build and run locally

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

Option C: Docker Compose

docker compose up -d

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.

Client Configuration

Cherry Studio / ChatBox / any OpenAI client

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

Thinking Depth

Append @think=N to any model name to control reasoning logic:

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

Advanced Features (Go Exclusive)

1. Vision / Multimodal Uploads

Unlike the Python version which ignores images, this Go port actively intercepts image_url payloads (both base64 encoded and external HTTP URLs).
It initiates a background Scotty Resumable Upload session, converts the base64 image into Google internal WIZ blobs, and passes the WIZ image references directly to Gemini.
Just send OpenAI standard multimodal payloads and it will work!

2. TLS Impersonation (Bypass WAF)

If you run this tool in datacenters (like AWS/DigitalOcean) where Google blocks the IP with a 403 Forbidden, you can impersonate a real browser's TLS signature:

./gemini-web2api --impersonate chrome_120

Or in config.json: "impersonate": "chrome_120". Supported profiles include chrome_112 to chrome_130, edge, and safari.

Optional: Cookie for Pro

Anonymous access works for all models, but gemini-3.1-pro routes to Flash without authentication. To get real Pro routing, you need a Gemini Advanced (paid subscription) account cookie:

./gemini-web2api --cookie-file cookie.txt

How to get cookies

1. Open Chrome, go to gemini.google.com and sign in with a Gemini Advanced Google account
2. Open DevTools (F12) → Application → Cookies → https://gemini.google.com
3. Copy these cookie values: SID, HSID, SSID, APISID, SAPISID, __Secure-1PSID
4. Create cookie.txt in this format:

SID=your_sid; HSID=your_hsid; SSID=your_ssid; APISID=your_apisid; SAPISID=your_sapisid; __Secure-1PSID=your_1psid

Or use JSON format if you know your specific SAPISID hashing needs:

{ "cookie": "SID=xxx; HSID=xxx; ...", "sapisid": "your_sapisid_value" }

Alternative (browser extension): Use any "Export Cookies" extension to export cookies for gemini.google.com in Netscape format, then convert to the single-line format above.

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.

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,
  "impersonate": null,
  "log_requests": true
}

When api_keys is empty [], authentication is disabled. When keys are set, /v1/* endpoints require Authorization: Bearer <key>.

Proxy

If you cannot access gemini.google.com directly, configure a proxy:

Method 1: CLI argument

# Linux / macOS
./gemini-web2api --proxy http://127.0.0.1:7890

# Windows (PowerShell)
.\gemini-web2api.exe --proxy http://127.0.0.1:7890

Method 2: config.json

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

Method 3: Environment variable

# Linux / macOS (bash)
export HTTPS_PROXY=http://127.0.0.1:7890
./gemini-web2api

# Windows (PowerShell)
$env:HTTPS_PROXY="http://127.0.0.1:7890"
.\gemini-web2api.exe

# Windows (Command Prompt)
set HTTPS_PROXY=http://127.0.0.1:7890
gemini-web2api.exe

Limitations

• 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.

License

MIT License.