Gemini Web2API - Cloudflare Workers Deployment Documentation

中文文档 | Quick Setup Guide (~5 min, zero to deployed)

New here? Follow the Quick Setup Guide: cookie, KV, secrets, deploy, verify, first request.

Project Introduction

Gemini Web2API runs on Cloudflare Workers and converts the Gemini web interface to an OpenAI-compatible API. No server or API key is required.

Core Features

Zero-cost deployment is based on Cloudflare Workers free plan (100,000 requests per day)
Global acceleration is achieved through deployment to Cloudflare’s 300+ global edge nodes
OpenAI compatible: Compatible with /v1/chat/completions and /v1/models endpoints
Streaming output: SSE (Server-Sent Events) streaming response
Multi-fingerprint rotation uses 8 browser fingerprints + 6 language preferences randomly rotated to reduce detection probability
Multi-Cookie rotation supports configuring multiple Google account cookies, randomly selected for use
Concurrent safety provides request-level configuration isolation, eliminating configuration crosstalk in high-concurrency scenarios
Tool call support is compatible with OpenAI Function Calling format
ProxyScrape Auto Proxy Rotation automatically fetches free proxies from ProxyScrape (timeout ≤ 200ms API or GitHub raw), auto-tests connectivity against gemini.google.com:443, and supports HTTP/SOCKS4/SOCKS5 via cloudflare:sockets. It uses best-of-2 scoring so the fastest verified proxy wins most requests while slower ones still get periodic health checks. The pool updates every 24 hours (Cron Trigger + background refresh), candidate lists are cached in memory to avoid redundant upstream fetches, and everything falls back to a direct connection on failure.

Applicable Scenarios

Provide free Gemini API for NextChat, Cherry Studio, ChatBox and other clients
Used as Gemini model backend in tools like WorkBuddy
Personal learning, research and small project AI capability access

Quick Deployment

Step 1: Log in to Cloudflare

Open Cloudflare Dashboard
Log in to your Cloudflare account (free registration available if you don’t have one)
Go to the left menu Workers & Pages

Step 2: Create Worker

Click Create Application → Create Worker
Give your Worker a name (e.g., api)
Click the Deploy button
Click the Edit Code button
Clear the default code in the editor
Paste the complete project code into the editor
Click Save and Deploy in the top right corner

Step 3: Get Test Address

After successful deployment, your API address is:

https://your-worker-name.your-account-name.workers.dev

For example: https://api.geminai.workers.dev

Step 4: Verify Deployment

Visit the following address in your browser:

https://your-worker.workers.dev/health

If you see a JSON response similar to the following, deployment is successful:

{
  "status": "ok",
  "version": "1.7.3-cf-autoproxy",
  "platform": "Cloudflare Workers",
  "models": ["gemini-3.6-flash", "gemini-3.5-flash", "..."],
  "hasCookie": false,
  "hasSapisid": false
}

Client Configuration

NextChat (ChatGPT-Next-Web)

Configuration Item	Value
Interface Type	OpenAI
Interface Address	`https://your-worker.workers.dev/v1`
API Key	`now-and-then` (default key)
Model	`gemini-3.6-flash`

Cherry Studio

Configuration Item	Value
API Address	`https://your-worker.workers.dev/v1`
API Key	`now-and-then`
Model	`gemini-3.6-flash`

ChatBox

Configuration Item	Value
API Mode	OpenAI API
API Domain	`https://your-worker.workers.dev`
API Path	`/v1/chat/completions`
API Key	`now-and-then`

Using curl for Testing

# Non-streaming request
curl https://your-worker.workers.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer now-and-then" \
  -d '{
    "model": "gemini-3.6-flash",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'

# Streaming request (typewriter effect)
curl -N https://your-worker.workers.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer now-and-then" \
  -d '{
    "model": "gemini-3.6-flash",
    "messages": [{"role": "user", "content": "Tell me a story"}],
    "stream": true
  }'

Environment Variable Configuration (Optional)

Configure in Cloudflare Dashboard → Workers → Your Worker → Settings → Variables → Environment Variables:

Variable Name	Description	Example Value
`COOKIE_STRING`	Gemini Cookie, multiple separated by `\|`	`cookie1\| cookie2\| cookie3`
`SAPISID`	SAPISID value, multiple separated by `\|`	`sapisid1\| sapisid2\| sapisid3`
`API_KEY` / `API_KEYS`	API Key, supports single string, comma/pipe-separated multiple keys, or JSON array	`my-secret-key` or `key1, key2` or `["now-and-then", "my-key"]`

Gemini Configuration

Variable Name	Description	Example Value
`GEMINI_BL`	Gemini build tag (update when encountering 405)	`boq_assistant-bard-web-server_20260907.07_p0`
`DEFAULT_MODEL`	Default model	`gemini-3.6-flash`
`AUTH_USER`	Multi-account index	`0`

Performance Optimization

Variable Name	Description	Default Value
`RETRY_ATTEMPTS`	Retry attempts	`3`
`RETRY_DELAY_SEC`	Retry interval (seconds)	`2`
`REQUEST_TIMEOUT_SEC`	Request timeout (seconds)	`28`
`REQUEST_DEADLINE_MS`	Server-side per-request deadline (ms): return a structured 502 (`upstream_timeout`) instead of hanging when the upstream response is not ready in time: fires before client timeouts or platform limits. `0` disables	`50000`
`FINGERPRINT_JITTER_MS`	Random delay maximum value (milliseconds)	`1500`
`RATE_LIMIT_MAX`	Rate limit maximum request count	`3000`
`RATE_LIMIT_WINDOW`	Rate limit time window (seconds)	`60`

Auto Proxy Pool & 24h Update Configuration

Variable Name	Description	Default Value
`ENABLE_PROXY`	Enable/disable proxy rotation	`true`
`PROXY_SOURCE_URL`	Primary proxy source URL (ProxyScrape 200ms API)	`https://api.proxyscrape.com/v4/free-proxy-list/get?request=display_proxies&proxy_format=protocolipport&format=text&timeout=200`
`PROXY_FALLBACK_SOURCE_URL`	Fallback proxy source URL (GitHub raw full list)	`https://raw.githubusercontent.com/ProxyScrape/free-proxy-list/refs/heads/main/proxies/all/data.txt`
`STATIC_PROXIES` / `PROXY_URL`	Custom fixed proxies (comma/newline separated, e.g. `http://user:pass@ip:port`, `socks5://ip:port`)	(empty)
`AUTO_TEST_PROXY`	Auto-test proxies before adding to verified pool (includes a real TLS handshake; TLS-MITM proxies with forged `gemini.google.com` certificates are rejected)	`true`
`PROXY_TEST_TIMEOUT_MS`	Per-proxy connection test timeout (ms), covers tunnel + TLS handshake	`2000`
`PROXY_UPDATE_INTERVAL_HOURS`	Proxy pool auto-update interval (hours)	`24`
`PROXY_MAX_POOL_SIZE`	Maximum verified proxies to keep in pool	`12`
`PROXY_FALLBACK_DIRECT`	Fall back to direct connection if all proxies fail	`true`
`PROXY_ROTATION_MODE`	Proxy selection algorithm — see Proxy Rotation Modes below	`best-of-2`
`PROXY_SOURCE_FETCH_TIMEOUT_MS`	Hard timeout for fetching the proxy list source (ms) — prevents a stalled source from hanging the request	`8000`
`PROXY_HANDSHAKE_TIMEOUT_MS`	Hard timeout for the CONNECT/SOCKS tunnel handshake per proxy (ms) — dead proxies fail fast instead of stalling	`6000`
`PROXY_REFRESH_SYNC_MS`	Max synchronous wait for the cold-start pool refresh (ms) — past this the refresh continues in the background and the request goes direct	`8000`
`PROXY_BODY_IDLE_TIMEOUT_MS`	Body idle watchdog (ms): abort a proxied request if the upstream/proxy sends nothing for this long mid-response — a single dead proxy can no longer pin a request for ~56s. Also derived from it: the total proxy-rotation time budget (2× this value) bounds how long failed proxy attempts can delay a request before falling back to direct. `0` restores the legacy 2× `REQUEST_TIMEOUT_SEC` behavior	`20000`

Proxy Rotation Modes

Set PROXY_ROTATION_MODE to one of four values to control how the next proxy is chosen for each request. All modes share the same adaptive scoring layer: every successful request updates the proxy’s latency with an EWMA (α = 0.3) and resets its fail counter, so a proxy that just slowed down drops in rank within ~3 requests, and a recovered one climbs back. Every failed request increments fails, which halves that proxy’s score (exponential cooldown), and any proxy that hits 2 cumulative fails is evicted from the pool.

Mode	Selection rule	Cost	Best for
`best-of-2` (default)	Pick 2 distinct proxies at random, return the one with the higher score	O(1)	Production — near-optimal load balancing, naturally avoids the heavy-weight concentration of pure roulette
`round-robin`	Strict sequential walk through the pool, wrap around at the end	O(1)	Want perfect fairness, no quality signal
`random`	Pure uniform random, ignores latency and fails	O(1)	Debugging / baseline comparison
`weighted`	Inverse-latency roulette with a 10% exploration floor so the slowest proxy still gets probed	O(n)	Compatible with the legacy “Smart Round Robin” — use if you need explicit probability distribution over all proxies

Score formula (used by best-of-2 and weighted):

score = reliability / (latency + 1)
reliability = 1           if fails == 0
            = 0.5 ^ fails  otherwise

Latency defaults to 1000 ms if missing or non-positive, so the latency=0 path (pretest disabled) no longer collapses to 1/0 = Infinity.
fails resets to 0 on the first successful request, so a proxy recovers fully after one good call.

Examples:

# Default — power-of-two choices
PROXY_ROTATION_MODE=best-of-2

# Strict sequential, ignore quality
PROXY_ROTATION_MODE=round-robin

# Pure random, for A/B testing
PROXY_ROTATION_MODE=random

# Legacy inverse-latency weighted
PROXY_ROTATION_MODE=weighted

Invalid values are ignored and logged as a WARN; the worker keeps the default (best-of-2).

How the 24-Hour Update Works:

Cloudflare Cron Trigger (Recommended):
- When deploying via Wrangler, wrangler.jsonc already configures "triggers": { "crons": ["0 0 * * *"] }.
- In Cloudflare Dashboard: Go to Workers & Pages → Your Worker → Triggers → Cron Triggers → Add Cron Trigger → enter 0 0 * * * (every 24 hours at 00:00 UTC).
On-Demand Auto-Update:
- Even if you don’t configure a Cron Trigger, the Worker automatically checks the timestamp on incoming requests. If 24 hours have passed since the last update, it refreshes the proxy pool in the background using ctx.waitUntil() without slowing down user requests!
Cloudflare KV Persistence (Recommended with Cron):
- Bind a KV namespace named PROXY_KV to your Worker. Verified proxies will be cached in KV across all edge data center instances!
- The daily cron refresh runs in its own invocation with its own subrequest budget, tests the pool, and writes the verified result to KV — so user requests on any isolate load the warm pool from KV instead of paying the cold-start test cost.
- Setup: npx wrangler kv namespace create PROXY_KV, then paste the returned namespace id into the kv_namespaces block of wrangler.jsonc (a placeholder is already there).
- Without KV, the cron refresh only warms the cron’s own throwaway isolate; each user-facing isolate still does its own cold-start refresh.
Proxy Endpoints (all require a valid API key, same auth as /v1 endpoints):
- GET /proxies: View proxy pool status, active proxy count, latencies, and last/next update times.
- POST /proxies/refresh or GET /proxies/refresh: Force an immediate re-fetch and test of the proxy pool.
- GET /debug/proxies: Detailed pool diagnostics — per-proxy health (healthy/flaky), latency, fail counts, rotation scores (highest first), and internal state (candidate cache, refresh due, rotation mode).
- GET /health: Includes live proxy status in the health check JSON.
In-Memory Candidate Caching (Free):
- After fetching from the primary/fallback source, the parsed candidate list is cached per Worker Isolate (free, no KV cost).
- TTL equals PROXY_UPDATE_INTERVAL_HOURS (24h default). Within one cycle, refresh attempts reuse the cache and skip both the ProxyScrape and GitHub raw fetches.
- Manual /proxies/refresh calls bypass the cache (force=true) and always re-fetch.
- Empty results never poison the cache, so a transient primary failure won’t lock the pool.

Anonymous requests hit Gemini’s rate limits quickly (HTTP 429). A valid cookie lowers that risk and improves Pro model routing.

Obtaining Steps

Open Chrome/Edge browser
Visit https://gemini.google.com/app and log in to your Google account
Press F12 to open developer tools
Go to the Application tab
On the left, select Cookies → https://gemini.google.com
Find the following Cookies and copy their values:
- __Secure-1PSID
- __Secure-3PSID
- SAPISID

Combine into a complete Cookie string:

__Secure-1PSID=your_value; __Secure-3PSID=your_value; SAPISID=your_value

Multi-account Configuration

If you have multiple Google accounts, you can separate multiple Cookies with |:

COOKIE_STRING = "cookie_account1| cookie_account2| cookie_account3"
SAPISID = "sapisid_1| sapisid_2| sapisid_3"

Each request will randomly select a Cookie to use, greatly reducing the probability of a single account being rate-limited.

Updating BL Version

If you encounter HTTP 405: Method Not Allowed error, it means the Gemini frontend has been updated, and you need to synchronize the build tag update:

Open https://gemini.google.com/app in browser
Press F12 → Network tab
Search for boq_assistant in any request’s URL

Copy the latest version number, for example:

boq_assistant-bard-web-server_20260730.02_p0

Update the environment variable GEMINI_BL or the geminiBl configuration item in the code

Multi-fingerprint Rotation Mechanism

This program has a built-in browser fingerprint rotation system, where each request randomly selects different browser identifiers:

Fingerprint Type	Pool Size	Description
User-Agent	8 types	Weighted random, simulating real browser market share
Accept-Language	6 types	Uniform random, simulating users from different regions
Sec-Ch-Ua	3 types	Chrome version identifier (only added when Chrome UA)
Random Delay	0-1500ms	Add random delay before request to simulate human operation

Security Recommendations

Modify default API Key: Change now-and-then in apiKeys to your own key
Set rate limiting: Adjust RATE_LIMIT_MAX based on actual usage
Regularly update Cookie: Google Cookies expire and need regular replacement
Do not share Cookie: Cookie is equivalent to your Google account credentials

Frequently Asked Questions

Q: Returns `empty response from server`

Cause: NextChat streaming parsing issue.
Solution: Make sure you’re using the latest version of the code (SSE format has been fixed).

Q: Returns `HTTP 429: Too Many Requests`

Cause: Gemini rate limiting, anonymous request frequency limits are stricter.
Solution: Configure valid COOKIE_STRING and SAPISID.

Q: Returns `HTTP 405: Method Not Allowed`

Cause: BL version expired.
Solution: Update geminiBl configuration (see the “Updating BL Version” section above).

Q: Returns `invalid api key`

Cause: Client API Key configuration error.
Solution: Check if the client is configured with the correct API Key (default now-and-then).

Q: WorkBuddy usage shows crosstalk

Cause: Multi-model concurrent requests share global configuration.
Solution: Current version has resolved this issue through request-level configuration isolation.

Supported Model List

Model ID	Type	Description
`gemini-3.8-flash`	FAST	Newest all-round model (Gemini 3.8 Flash)
`gemini-3.7-flash`	FAST	Latest all-round model (Gemini 3.7 Flash)
`gemini-3.6-flash`	FAST	All-round model (Gemini 3.6 Flash)
`gemini-3.5-flash`	FAST	Alias for 3.6 Flash
`gemini-3.5-flash-thinking`	THINKING	Deep thinking mode
`gemini-3.1-pro`	PRO	Professional version (requires Cookie)
`gemini-auto`	AUTO	Automatic model selection
`gemini-3.5-flash-thinking-lite`	DYNAMIC	Adaptive dynamic thinking
`gemini-flash-lite`	LITE	Lightweight fast model
`gemini-2.5-flash`	FAST	Client compatibility alias (routes to 3.6 Flash)
`gemini-2.0-flash`	FAST	Client compatibility alias (routes to 3.6 Flash)
`gemini-2.5-pro`	PRO	Client compatibility alias (routes to 3.1 Pro)

Supports overriding thinking mode via @think= parameter:

gemini-3.6-flash@think=0: Flash model + deep thinking
gemini-3.1-pro@think=4: Pro model + automatic thinking

Changelog

Version	Date	Update Content
1.7.3	2026-09-11	Reduced default `PROXY_MAX_POOL_SIZE` from 30 to 12 so a cold-start pool refresh uses far fewer subrequests (~14 vs ~32)
1.7.2	2026-09-11	Fixed `Too many subrequests by single Worker invocation`: added a per-invocation subrequest budget: proxy pool refresh (source fetch + tests) is capped at 32 subrequests and stops early to reserve headroom for the actual Gemini request; proxy attempts and direct fallbacks are budget-tracked; fixed `startTls()` never working (`connect` missing `secureTransport: 'starttls'`) which made every proxied request hang
1.7.1	2026-09-10	Switched proxy rotation to Smart Round Robin (inverse-latency weighted), reduced default `PROXY_TEST_TIMEOUT_MS` from 2000 to 1000, added free in-memory candidate cache (TTL = update interval) to avoid redundant upstream fetches
1.7.0	2026-09-10	Added ProxyScrape auto proxy fetching (timeout ≤ 200ms API or GitHub raw), auto connectivity test system via cloudflare:sockets (HTTP CONNECT, SOCKS5, SOCKS4), 24-hour automatic background update & Cron Trigger support (`0 0 * * *`), automatic failover & fallback to direct connection, `/proxies` and `/proxies/refresh` management endpoints
1.6.0	2026-09-09	Upgraded to Chrome 132-134 fingerprint library, streaming request 429 automatic exponential backoff retry, support flexible environment variable `API_KEY` (string/comma-separated/JSON), added `gemini-3.7-flash` and 2.0/2.5 compatibility aliases, health check returns detailed status
1.5.0	2026-07-31	Added multi-fingerprint rotation, multi-Cookie rotation, random delay mechanism
1.4.0	2026-07-30	Fixed concurrent crosstalk, rate limiting memory safety
1.3.0	2026-07-29	Fixed SSE streaming format, NextChat compatibility
1.0.0	2026-07-16	Initial version, ported from gemini-web2api v1.1.0

License

This project is based on the original project gemini-web2api ported, following the original project’s open source license.

Getting Started

Deployment

Additional Info

Deploy Gemini Web2API to Cloudflare Workers

Gemini Web2API - Cloudflare Workers Deployment Documentation

Project Introduction

Core Features

Applicable Scenarios

Quick Deployment

Step 1: Log in to Cloudflare

Step 2: Create Worker

Step 3: Get Test Address

Step 4: Verify Deployment

Client Configuration

NextChat (ChatGPT-Next-Web)

Cherry Studio

ChatBox

Using curl for Testing

Environment Variable Configuration (Optional)

Gemini Configuration

Performance Optimization

Auto Proxy Pool & 24h Update Configuration

Proxy Rotation Modes

How the 24-Hour Update Works:

Obtaining Steps

Multi-account Configuration

Updating BL Version

Multi-fingerprint Rotation Mechanism

Security Recommendations

Frequently Asked Questions

Q: Returns `empty response from server`

Q: Returns `HTTP 429: Too Many Requests`

Q: Returns `HTTP 405: Method Not Allowed`

Q: Returns `invalid api key`

Q: WorkBuddy usage shows crosstalk

Supported Model List

Changelog

License

​Gemini Web2API - Cloudflare Workers Deployment Documentation

​Project Introduction

​Core Features

​Applicable Scenarios

​Quick Deployment

​Step 1: Log in to Cloudflare

​Step 2: Create Worker

​Step 3: Get Test Address

​Step 4: Verify Deployment

​Client Configuration

​NextChat (ChatGPT-Next-Web)

​Cherry Studio

​ChatBox

​Using curl for Testing

​Environment Variable Configuration (Optional)

​Authentication Related

​Gemini Configuration

​Performance Optimization

​Auto Proxy Pool & 24h Update Configuration

​Proxy Rotation Modes

​How the 24-Hour Update Works:

​How to Get Gemini Cookie

​Why Do You Need Cookie?

​Obtaining Steps

​Multi-account Configuration

​Updating BL Version

​Multi-fingerprint Rotation Mechanism

​Security Recommendations

​Frequently Asked Questions

​Q: Returns empty response from server

​Q: Returns HTTP 429: Too Many Requests

​Q: Returns HTTP 405: Method Not Allowed

​Q: Returns invalid api key

​Q: WorkBuddy usage shows crosstalk

​Supported Model List

​Changelog

​License

Gemini Web2API - Cloudflare Workers Deployment Documentation

Project Introduction

Core Features

Applicable Scenarios

Quick Deployment

Step 1: Log in to Cloudflare

Step 2: Create Worker

Step 3: Get Test Address

Step 4: Verify Deployment

Client Configuration

NextChat (ChatGPT-Next-Web)

Cherry Studio

ChatBox

Using curl for Testing

Environment Variable Configuration (Optional)

Authentication Related

Gemini Configuration

Performance Optimization

Auto Proxy Pool & 24h Update Configuration

Proxy Rotation Modes

How the 24-Hour Update Works:

How to Get Gemini Cookie

Why Do You Need Cookie?

Obtaining Steps

Multi-account Configuration

Updating BL Version

Multi-fingerprint Rotation Mechanism

Security Recommendations

Frequently Asked Questions

Q: Returns `empty response from server`

Q: Returns `HTTP 429: Too Many Requests`

Q: Returns `HTTP 405: Method Not Allowed`

Q: Returns `invalid api key`

Q: WorkBuddy usage shows crosstalk

Supported Model List

Changelog

License