Gemini-API：逆向工程出的 Gemini 网页版 Python 客户端，适合谁用

它解决的是官方 API 覆盖不到的需求

它解决的是官方 API 覆盖不到的需求。Google 的官方 Generative AI API 需要付费或申请配额，而且功能上并不总是与网页版同步。Gemini-API 反其道而行，直接模拟 gemini.google.com 网页端的内部请求，把网页上能做的事包装成 Python 接口。根据 README，它支持图像生成与编辑、视频和音频生成、Deep Research 全流程、Gemini Gems 系统提示词、扩展（如 YouTube 和 Gmail）等。目标用户很明确：想用网页版功能又不想手动操作浏览器的人，比如自动化脚本作者、个人助理开发者、或者需要批量处理内容的工程师。它不是一个通用 LLM 库，而是针对 Gemini 网页端的专用工具，这一点从它的异步设计和 cookie 管理方式就能看出来。

核心机制：cookie 驱动的逆向接口

这个库不依赖官方 API key，而是靠浏览器 cookie 认证。具体来说，你需要从 gemini.google.com 的开发者工具里复制两个 cookie 值：__Secure-1PSID 和 __Secure-1PSIDTS。库内部通过这两个值构造请求，模拟网页端的对话。关键设计是自动刷新 cookie。README 明确说这个功能默认开启，不需要 browser-cookie3 也能工作，目的是让常驻服务不会因为 cookie 过期而中断。刷新过程中可能要求你在浏览器里重新登录 Google 账号，这是预期行为。对于部署在 Docker 等容器环境的情况，可以用 GEMINI_COOKIE_PATH 环境变量指定 cookie 存储路径，配合 volume 持久化，避免每次重建容器都重新认证。这个机制意味着它不是简单的静态 cookie 复用，而是一个会主动维护会话状态的后台任务。

安装与认证：从 pip 到第一条消息

安装很简单，要求 Python 3.11 或更高版本。基础安装是 pip install -U gemini_webapi，若想从本地浏览器自动导入 cookie，可以安装 gemini_webapi[browser]，但 README 注明目前只支持 Firefox，其他浏览器支持情况需查看 browser-cookie3 项目。手动认证流程是：登录 gemini.google.com，打开开发者工具的 Network 面板，刷新页面，从任意请求里复制 __Secure-1PSID 和 __Secure-1PSIDTS 的值。之后初始化客户端时传入这两个值即可。官方文档给出一个 docker-compose 片段，通过 GEMINI_COOKIE_PATH 指向 /tmp/gemini_webapi，同时挂载 volume 到 ./gemini_cookies，这个配置能解决容器重建后 cookie 丢失的问题。整个过程不涉及 API key，也没有 OAuth 流程，对熟悉浏览器调试的开发者来说门槛较低，但对非技术用户并不友好。

功能全景：从文本到多模态生成

README 列出了大量用法，按功能分组。文本生成是最基本的，支持多轮对话、继续历史对话、读取和删除历史记录、临时模式、流式输出。模型选择上可以列出可用模型并切换，例如包含 nano-banana 这样的新模型。图像方面，既可以从回复中提取图片，也可以用自然语言生成和编辑图像。视频和音频生成属于原生支持，不需要额外插件。Deep Research 是一个完整的工作流，包含计划创建、状态轮询和结果获取。扩展功能允许调用 YouTube 和 Gmail 等 Gemini 扩展。回复分类输出把文本、思考过程、图像、视频和音频分开，方便程序化处理。另外还支持管理自定义 Gems，包括创建、更新和删除。这些功能覆盖面很广，几乎把网页端的交互都暴露成了 Python 方法，但这也意味着每个功能背后都对应一个网页端的内部接口，接口变动时这些方法都可能失效。

CLI 工具与异步设计

除了库本身，项目还附带一个 CLI 工具，用于快速交互。CLI 同样需要 cookie 设置，然后可以执行各种命令，甚至支持 Deep Research 工作流。这适合不想写 Python 代码、只想在终端里试一下的用户。库的底层是 asyncio，所有生成任务都是异步的，这符合常驻服务的需求，比如聊天机器人或后台处理任务。但异步也带来一个学习曲线：如果你不熟悉 asyncio 的事件循环，写同步代码时可能会踩坑。官方接口风格模仿 Google Generative AI 的 Python 快速入门，README 称之为 official flavor，意思是如果你用过官方库，迁移过来会比较顺手。不过这只是接口风格上的相似，底层完全不一样，官方库用的是 API key 和 HTTP 端点，而这里用的是 cookie 和逆向端点。

主要限制：稳定性与合规风险

逆向工程的本质决定了它的脆弱性。Google 可以随时更改网页端的内部请求格式、端点路径或认证机制，任何一次前端更新都可能让这个库失效。虽然项目活跃（最近发布 v2.1.1），但你不能指望它像官方 API 那样有服务等级协议。另一个限制是 cookie 刷新机制。自动刷新虽然方便，但需要浏览器环境参与，如果部署在无头服务器且没有浏览器登录会话，刷新过程可能会失败。README 提到的浏览器 cookie 导入只支持 Firefox，这对 Chrome 用户是个障碍。合规方面，使用 cookie 访问网页端服务可能违反 Google 的服务条款，尤其是大规模自动化调用时。许可证是 AGPL-3.0，这意味着如果你修改代码并部署为网络服务，需要开源你的修改版本。对于只想内部使用的脚本，这通常不是问题，但如果你想把它集成到闭源商业产品里，就需要仔细考虑许可证义务。

替代方案：官方 API 与直接网页自动化

最直接的替代是 Google Generative AI 官方 Python 库，它使用 API key，有明确的配额和计费，接口稳定且文档完善。差异在于官方库不支持网页版独有的功能，比如 Gems、扩展或 Deep Research，至少 README 没有暗示这些能力能在官方 API 中直接使用。另一个替代是直接写浏览器自动化，比如用 Selenium 或 Playwright 操作 gemini.google.com 页面。这种方式不依赖逆向接口，页面改动时你可能只需更新选择器，但缺点是速度慢、资源占用高，而且难以处理流式输出和异步任务。Gemini-API 处于两者之间：比官方 API 功能多，比浏览器自动化效率高，但牺牲了稳定性和官方支持。选择哪个取决于你的核心需求：如果要的是可靠的 API 调用，选官方；如果要的是网页版的特殊功能且能接受风险，这个库值得一试。

维护成本与升级路径

项目的发布历史显示 v2.0.0 在 2026 年 4 月发布，v2.1.1 在 2026 年 8 月发布，说明维护比较活跃。但活跃维护不等于接口稳定，每次升级都可能改变方法签名或内部数据结构。依赖方面，核心包只依赖 Python 标准库和必要的 HTTP 库，可选的 browser-cookie3 是唯一的外部依赖，且它本身也有自己的维护风险。升级时你需要关注 changelog 或 release notes，因为逆向库的破坏性变更可能比官方库更频繁。许可证 AGPL-3.0 要求如果你修改代码并对外提供网络服务，必须提供相应的源代码。这不是法律建议，但你应该咨询你的法务团队。对于个人项目，维护成本主要是定期检查 cookie 刷新是否正常，以及跟进新版本。如果你打算长期依赖它，建议固定版本号，并在升级前在测试环境验证核心功能。

编辑结论

Gemini-API 适合需要免费调用 Gemini 网页版能力、且能接受非官方接口风险的开发者，尤其是个人自动化脚本、原型验证或内部工具。不适合对稳定性、合规性或长期维护有要求的生产环境，因为逆向接口随时可能被 Google 修改，且 AGPL-3.0 许可证对商业闭源集成有传染性。采用前应先验证 cookie 自动刷新在目标网络环境下是否正常，检查当前版本是否支持你需要的模型（如 nano-banana），并确认你的使用场景不违反 Google 服务条款。若需要正式 API，应优先考虑 Google Generative AI 官方库。

官方来源

1. HanaokaYuzu/Gemini-API on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases