Gemini-API：把 Gemini 網頁版變成可程式化的非官方 Python 工具
✨ Reverse-engineered Python API for Google Gemini web app
秒懂
- 它是什麼？
- 這是一個逆向工程自 Gemini 網頁版的非同步 Python 套件，能生成文字、圖片、影片與音訊，也能操作 Deep Research 與擴充功能。它繞過官方 API 的金鑰與計費，但代價是依賴未公開的網頁介面，穩定性與授權都需要仔細評估。
- 適合誰用？
- 如果你的目標是快速原型、個人自動化、或不想處理官方 API 的金鑰與配額，而且你能接受 Python 3.11 以上、非同步架構、以及隨時可能因 Google 變更網頁而失效的風險，那麼 Gemini-API 值得一試。它特別適合需要圖片生成、Deep Research、或 Gemini 擴充功能（如 YouTube、Gmail）的場景，因為這些在官方 API 中通常無法直接使用。
- 可以商用嗎？
- 可以，但條件嚴格。AGPL-3.0 是網路 copyleft 授權：如果別人透過網路使用你修改過的版本（例如作為託管服務），你必須以同一授權向他們提供原始碼。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 19 天前。
- 用什麼語言寫的？
- 主要是 Python（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它解決的問題：繞過官方 API 的限制
Google Gemini 的官方 API 需要 API 金鑰、有配額限制、而且通常不提供圖片生成、影片生成、或 Deep Research 這類進階功能。如果你只是想要一個能自動跟 Gemini 對話的腳本，卻又不想申請金鑰或處理計費，這個專案提供了一條捷徑。它直接與 gemini.google.com 的網頁介面互動，模擬你在瀏覽器中的操作。這意味著你不需要付費，也不需要官方 API 的存取權限。它主要服務的對象是開發者、自動化愛好者、以及想整合 Gemini 到自有服務但不想受官方 API 功能範圍限制的人。因為它使用非同步的 asyncio，適合需要同時處理多個請求或長時間運作的服務。但要注意，這種逆向工程的工具本質上依賴 Google 未公開的內部端點，任何網頁前端的改版都可能讓它失效。
運作機制：從 cookie 到分類輸出
這個套件的核心是模擬瀏覽器對 Gemini 網頁後端發送請求。它需要兩個關鍵的 cookie 值：__Secure-1PSID 與 __Secure-1PSIDTS。你從瀏覽器的開發者工具中複製這兩個值，然後傳給初始化函式。套件會用這些 cookie 來維持你的登入狀態。它有一個「自動刷新 cookie」的功能，會在背景定期更新 cookie，讓長時間運作的服務不需要手動重新登入。回應的資料結構經過分類，文字、思考過程（thoughts）、圖片、影片、音訊會被分開處理。這表示你可以單獨取出模型生成的圖片，而不必從混合的文字輸出中解析。它還支援串流模式，會逐步產生部分輸出，這對於需要即時回應的聊天機器人非常有用。整個架構是非同步的，所以你可以用 await 語法來呼叫生成函式。
安裝與認證：真實的指令與設定
安裝很直接，需要 Python 3.11 或更高版本。基本安裝指令是 pip install -U gemini_webapi。如果你想讓套件自動從瀏覽器匯入 cookie，可以安裝選用依賴：pip install -U gemini_webapi[browser]。目前這個選項只支援 Firefox，因為它依賴 browser-cookie3 這個套件。手動認證的步驟是：登入 gemini.google.com，開啟開發者工具，切到 Network 分頁，重新整理頁面，然後從任何請求中複製 __Secure-1PSID 與 __Secure-1PSIDTS 這兩個 cookie 的值。如果你把應用程式部署在 Docker 這類容器環境，可以設定環境變數 GEMINI_COOKIE_PATH 來指定自動刷新後 cookie 的儲存路徑。README 提供了一個 docker-compose.yml 的範例，將 /tmp/gemini_webapi 掛載為 volume。這代表你必須確保那個路徑是可寫入的，否則自動刷新功能會失敗。
功能範圍：不只是文字生成
這個套件的功能範圍比官方 API 寬廣得多。它支援圖片生成與編輯，你可以用自然語言描述想要的圖片。它也支援影片與音訊生成，這在官方 API 中通常不可用。它還實作了 Deep Research 的完整工作流程，包括建立計畫、輪詢狀態、以及取得結果。另外，它可以套用 Gemini Gems 的系統提示詞，也能管理自訂的 Gems，像是建立、更新、刪除。它甚至能與 Gemini 擴充功能整合，例如 YouTube 或 Gmail。回應中，你可以取得模型的思考過程，這對於除錯或理解模型的推理很有幫助。它還支援切換到其他回覆候選（reply candidates），這類似網頁版提供的多個草稿。最後，它有一個 CLI 工具，可以讓你不用寫 Python 程式就直接在命令列與 Gemini 互動。
真正的限制：依賴未公開介面的代價
最明顯的限制是穩定性。Gemini 網頁版的任何改版都可能破壞這個套件的運作。它不是官方支援的介面，所以沒有相容性保證。開發者必須持續追蹤 Google 的變更，並發布更新。從最近的發布紀錄來看，v2.1.1 在 2026 年 8 月發布，v2.0.0 在同年 4 月發布，這顯示專案有持續維護，但這也意味著你必須頻繁升級，才能避免 API 失效。第二個限制是 cookie 管理。自動刷新功能雖然方便，但 README 明確指出，它可能要求你再次在瀏覽器中登入 Google 帳號。這在 headless 或容器環境中可能造成問題，因為你無法輕鬆互動。如果你使用 browser-cookie3 自動匯入 cookie，目前只支援 Firefox，這限制了部署的彈性。第三，所有操作都綁定你的個人 Google 帳號，這可能涉及帳號被停用的風險，因為 Google 的服務條款通常不允許這種自動化存取。
替代方案：官方 API 與其他逆向工具
最直接的替代方案是 Google Generative AI 官方 Python 套件，它使用 API 金鑰，提供穩定的端點與明確的配額。官方 API 的優點是可靠、有文件、有 SLA，但缺點是功能範圍較窄，例如圖片生成與 Deep Research 通常不在其中。另一個替代方案是使用其他逆向工程的 Gemini 或 Bard API 專案，例如 gcloud 社群中常見的 bardapi 系列。這些專案與 Gemini-API 的差異在於實作細節：有些是同步的，有些只支援文字，有些則需要不同的 cookie 或認證流程。Gemini-API 的優勢在於它整合了多種媒體生成與擴充功能，而且提供了與官方 API 相似的介面風格，這降低了轉換成本。但你在選擇任何逆向工具時，都必須接受同樣的根本風險：它們都在與 Google 的內部變更賽跑。
維護與授權：你必須知道的成本
授權是 AGPL-3.0，這是一個具有傳染性的開源授權。如果你將這個套件整合到你的服務中，並透過網路提供服務，你可能需要將整個應用程式的原始碼以相同授權釋出。這對於商業或閉源的專案可能是重大的法律負擔。你應該在採用前諮詢法律專業人士，但從授權條款本身來看，它比 MIT 或 Apache 更嚴格。維護成本方面，由於專案依賴逆向工程，每次 Google 更新都可能需要你手動更新套件。發布頻率看起來是幾個月一次，這表示你必須定期檢查新版本。此外，cookie 自動刷新功能需要持續的背景執行緒，這會增加應用程式的複雜度。如果你部署在容器中，你必須管理 GEMINI_COOKIE_PATH 的持久化，否則每次重建容器都會要求重新認證。套件本身依賴 browser-cookie3 作為選用功能，這代表它有自己的維護週期與瀏覽器相容性問題。
編輯結論
如果你的目標是快速原型、個人自動化、或不想處理官方 API 的金鑰與配額，而且你能接受 Python 3.11 以上、非同步架構、以及隨時可能因 Google 變更網頁而失效的風險，那麼 Gemini-API 值得一試。它特別適合需要圖片生成、Deep Research、或 Gemini 擴充功能（如 YouTube、Gmail）的場景，因為這些在官方 API 中通常無法直接使用。但如果你要的是穩定、可預期的商業級服務，或者你的程式需要長時間無人值守地執行，請先確認自動刷新 cookie 的機制在你的環境中真的有效，並準備好監控 cookie 路徑的寫入權限。凡是需要 SLA、稽核軌跡、或合規保證的專案，都不該依賴這個逆向工具。你應該先閱讀 AGPL-3.0 授權條款，確認你的使用方式是否符合其對衍生作品與網路服務的規定，然後在隔離環境中測試 cookie 刷新與多輪對話的穩定性，再決定是否投入。這個專案的生命週期與 Google 的網頁前端綁在一起，沒有官方保證，只有持續的逆向工程。
社群筆記