你的 Gemini 訂閱，
變成可以呼叫的 API

1為什麼會有這個東西

你已經在付 Gemini 的訂閱費，網頁版整天生圖、回答問題都沒問題。但只要換成排程工作、 Cloudflare Worker 或 Telegram 機器人想做同一件事，你就得回頭去買按量計費的 API 額度，買的是你早就擁有的能力。

這個服務夾在中間：一個無頭瀏覽器維持登入狀態，呼叫端只要講普通的 HTTP。一份登入、 多個消費端、不按張計費。輸出的圖會自動去掉可見浮水印，而且是從下載按鈕取原始尺寸， 不是抓網頁上那張被縮過的算圖。

2你會得到什麼

3安裝

請用 uv 或 pipx，直接 pip install 不會給 Playwright 隔離環境，瀏覽器會裝不起來。

uv tool install gemini-web
gemini-web install          # 下載 Playwright 要驅動的 Chromium
gemini-web login            # 開真的瀏覽器，登入 Google 後按 Enter

登入這步需要桌面環境（或透過 SSH 的 X forwarding），因為密碼要你自己輸入。 登入狀態存在 ~/.gemini-web/profiles/，之後就一直沿用。 要加第二個帳號是 gemini-web login -w 1，第三個是 -w 2，依此類推。

gemini-web serve --host 0.0.0.0 --port 8070

要常駐的話，scripts/install-service.sh 裡有現成的 systemd unit。

4怎麼用

# 文字對話
curl -X POST http://localhost:8070/api/chat \
  -H 'Content-Type: application/json' \
  -H 'x-goog-api-key: gmw_<你的金鑰>' \
  -d '{"prompt": "解釋量子力學"}'

# 文字生圖
curl -X POST http://localhost:8070/api/generate \
  -H 'Content-Type: application/json' \
  -H 'x-goog-api-key: gmw_<你的金鑰>' \
  -d '{"prompt": "畫一張台北 101 海報"}'

# 參考圖編輯（丟一張照片進去，拿一張改過的圖出來）
curl -X POST http://localhost:8070/api/edit \
  -H 'Content-Type: application/json' \
  -H 'x-goog-api-key: gmw_<你的金鑰>' \
  -d '{"prompt": "redraw as a 3x3 sticker sheet", "reference_image": "data:image/png;base64,..."}'

或是原本的 SDK 程式碼不動，只把位址指過來：

from google import genai

client = genai.Client(
    api_key="gmw_<你的金鑰>",
    http_options={"api_version": "v1beta", "base_url": "http://localhost:8070"},
)
print(client.models.generate_content(model="gemini-2.5-flash", contents="Hello").text)

只要你發過任何一把金鑰，上面每個端點都會要求帶 x-goog-api-key。在第一把金鑰出現之前服務維持開放， 本機開發不會被擋，但只要對外可達，第一天就該發金鑰。瀏覽器路燒的是登入帳號的 訂閱額度，而且沒有任何每把金鑰的速率限制會救你。

5多帳號 worker pool

把 WORKER_COUNT=N 設起來，服務就會開 N 個瀏覽器，各自吃 自己的 profile 目錄，也就是各自一個 Google 帳號。每個 worker 一次處理一筆請求， 所以 N 同時是你的併行度，也是你分攤用量的額度數。實測每個 worker 大約佔 0.6 到 0.7 GB 記憶體。

模式是管理後台 Overview 的一個下拉選單，設定存在資料庫裡，重啟後沿用。

擴充帳號之前有件事值得先知道：同一個 Gemini 網頁，在不同帳號長得不一樣。 選單項目會有出入，第一次使用上傳功能的帳號會多跳一個同意條款對話框，生成好的圖有時是 blob、有時要按下載鈕。所以「只有某一個 worker 壞掉、其他都好」是正常現象，而且元凶 通常不是登入。後台那欄每個 worker 的 24 小時成功率就是為此而存在，讓這件事一眼看得見， 而不是被 fallback 蓋過去。

6後台有什麼

/admin，用密碼加上一個 HMAC 簽章的 session cookie 保護：

• Overview：請求總數、成功、失敗、排隊加執行中、uptime，以及一張 worker 表格：帳號、存活、登入狀態、忙碌與 24 小時成功率。派工模式也在這裡切。
• API Keys：為每個呼叫端發一把 gmw_<token>，可停用或刪除。原始值只顯示一次，伺服器只留 sha256。環境變數 API_KEYS 裡的金鑰仍然有效，會以唯讀方式列出。
• Test：手動跑 generate、edit、chat，含參考圖上傳，讓你不必碰對方的程式就能重現他遇到的失敗。
• History：最近 500 筆請求，含用了哪把金鑰、哪個 worker、花了多久、輸出圖連結，以及那些圖幾時會被清掉。prompt 與 error 直接顯示前 90 字，整頁失敗不必逐筆點開才看得懂。

7選配的付費後路

瀏覽器路是每個帳號單線、一次 30 到 120 秒，而且 Gemini 一改版就可能壞。如果某個 呼叫端受不了這種脆弱，設定 GEMINI_OFFICIAL_API_KEY，服務 就能改把請求交給官方 Gemini Developer API：大約 10 秒，按量計費。

• GEMINI_OFFICIAL_MODE=off：完全不用。
• fallback（預設）：只有瀏覽器路失敗後才頂上。
• primary：一律直接走官方，跳過瀏覽器。
• ?official=1 可以強制單次走官方路。

付費路一律要求有效金鑰，所以開放的端點永遠不會被拿去衝你的帳單。但反過來要留意： 在 fallback 模式下，壞掉的 worker 從外面完全看不出來， 呼叫端照樣拿到圖，只是那張圖是按量計費生出來的。後台那欄成功率就是為了看穿這件事。