Gemini-API：逆向工程版 Google Gemini 异步 Python 接口

图1：Gemini-API 项目 Banner

一、背景故事：让 Gemini "挣脱"官方限制

2024年初，Google 推出 Gemini AI 助手，但官方 API 需要付费，且功能受限。有没有一种方式，能像使用普通 Python 库一样，调用 Gemini 网页版的完整能力？日本开发者 HanaokaYuzu（化名 UZQueen）用行动给出了答案——对 Gemini 网页端进行逆向工程，开发出了这款异步 Python 封装库。

这个项目的诞生，本质上源于一个技术社区的共同诉求：免费使用最强 AI 模型的所有功能。截至2026年6月，该项目已累计超过 3100 颗 GitHub Stars，成为 Gemini 非官方接口领域最具影响力的开源项目之一。

二、项目定位：非官方的"全能版" Gemini 接口

通俗来说，Gemini-API 可以理解为"给 Gemini 网页版写的 Python 遥控器"。如果你不想花钱开 Google AI Studio 的订阅，又想用上 Gemini 的图生图、视频生成、深度研究等高级功能，这个库就是最直接的方案。

它与官方 API 的核心区别在于：不花钱，但需要折腾一点认证流程。用户需要从浏览器中手动导出 Google 账号的 Cookie（__Secure-1PSID），填入代码里，就能以类似官方 SDK 的方式调用 Gemini 网页端所有能力，包括官方 API 需要付费才能解锁的功能。

三、核心技术架构

3.1 异步优先的设计哲学

项目完全基于 Python 的 asyncio 异步框架构建，所有 I/O 操作（网络请求、Cookie 刷新）均为非阻塞式。这使得 Gemini-API 可以同时管理大量并发对话，适合做聊天机器人后端、自动化脚本等场景。

核心技术栈：

• curl-cffi：带 TLS 指纹模拟的 HTTP 客户端，能绕过部分网站的 bot 检测
• orjson：超高速 JSON 序列化库，比标准库快 5-10 倍
• pydantic：数据模型校验，确保 API 返回结构稳定
• loguru：现代化日志库

3.2 Mixin 模块化架构

代码采用 Python 多继承 Mixin 模式组织，将功能拆分为三个独立模块：

Mixin 模块	职责
ChatMixin	对话生成、图片/视频生成、文件上传、多轮对话
GemMixin	Gemini Gems（自定义角色/System Prompt）管理
ResearchMixin	深度研究工作流（规划→轮询→结果获取）

这种设计让代码高度解耦，每个模块独立测试，新增功能只需添加新的 Mixin。

3.3 Cookie 自动刷新机制

传统逆向工程接口的痛点是 Cookie 会过期。该项目内置了自动后台刷新 Cookie 机制——即使长时间运行，也能自动续期，用户无需手动干预。这对于需要 7×24 小时运行的 AI 服务尤为重要。

四、核心功能详解

4.1 图像生成与编辑

Gemini-API 原生支持图片生成（Image Generation）和图片编辑（Image Editing），调用方式与 OpenAI DALL·E 类似，但底层是 Gemini 自己的图像模型。用户只需传入文字描述，库自动处理 API 请求、解析图片 URL 并返回给调用方。

4.2 视频与音频生成

除了图片，该库还支持生成视频和音频/音乐内容。这是 Google Gemini 网页端独有的功能，官方 API 中长期缺失。Gemini-API 填补了这一空白，让 Python 开发者也能便捷地用 Gemini 生成多媒体内容。

4.3 Deep Research 深度研究

Gemini 内置的 Deep Research 模式可以自主规划研究路径、搜索资料、整合结果。该库完整实现了这一流程的 API 调用：创建研究计划 → 轮询进度 → 获取完整报告。用户可以将其对接自己的知识库或 RPA 系统，构建自动化研究代理。

4.4 Gemini Gems 自定义角色

Gems 是 Gemini 的自定义助手功能，类似于 GPTs。用户可以通过 API 创建、更新、删除自定义角色，将特定知识或行为模式预置到 AI 助手中。Gemini-API 提供了完整的 CRUD 接口。

4.5 实时流式输出（Streaming）

支持 AsyncGenerator 模式的流式输出，AI 逐 token 返回结果。这对于需要实时展示 AI 思考过程的场景（如终端聊天机器人）非常有价值。

4.6 命令行工具（CLI）

内置独立 CLI 工具 gemini-webapi，无需写代码，直接在终端与 Gemini 对话。提供 Cookie 自动配置、对话历史管理、深度研究工作流等开箱即用的功能。

五、部署与使用门槛

5.1 安装方式

仅需一行命令：

pip install -U gemini_webapi

如需从本地浏览器自动导入 Cookie（最省事的方式），安装可选依赖：

pip install -U gemini_webapi[browser]

5.2 认证流程（主要门槛）

认证需要从浏览器手动导出 Google 账号 Cookie：

1. 登录 gemini.google.com
2. 按 F12 打开开发者工具 → Network 选项卡
3. 刷新页面，任意请求中复制 __Secure-1PSID 和 __Secure-1PSIDTS 的值
4. 填入代码或 CLI 工具中

⚠️ 注意：Cookie 来自 Google 账号，涉及账号安全。建议使用专用小号，且不要在公开场合分享 Cookie 值。

5.3 硬件与软件需求

项目	要求
Python 版本	≥ 3.10
内存	≥ 512MB
磁盘	≥ 50MB
GPU	不需要
代理	某些地区可能需要

由于项目无 Docker 支持、无 Web UI，部署难度归为"简单"——安装依赖 + 配置 Cookie 即可运行，但不属于"一键部署"范畴。

六、局限性与风险

6.1 合法性争议

逆向工程 Google 服务在法律上处于灰色地带。AGPL-3.0 许可证本身没问题，但使用 Cookie 模拟登录可能违反 Google 服务条款。Google 有权随时封禁相关 Cookie 或调整接口，项目维护者需要持续跟进接口变化，维护成本较高。

6.2 接口脆弱性

由于依赖 Gemini 网页端接口而非官方 API，Google 每次更新网页端都可能导致接口失效。近年来 Gemini 团队接口变动频繁，该项目已多次发布修复版本，用户需要注意及时更新。

6.3 Cookie 失效风险

即使有自动刷新机制，长时间运行仍可能因 Google 账号风控导致 Cookie 失效。项目维护者在 Issues 中记录了大量此类问题，用户需有心理准备。

七、行业意义与生态价值

Gemini-API 的出现，折射出 AI 领域一个持续存在的矛盾：官方 API 的功能阉割与用户对完整能力的需求之间的张力。

在 GPT-4 时代，就有 GPT-4-API、free-gpt 等类似项目。Gemini-API 延续了这一传统，但 Gemini 自身的图像/视频生成和 Deep Research 能力确实强于同期竞品，因此该项目在开源社区的吸引力持续不减。

从技术角度看，该项目的代码质量相当高：完整的类型注解、pytest 测试套件、自动化 CI/CD、pydantic 数据校验、多级异常处理，都体现了专业开发者的工程素养。作为学习异步编程、网络请求处理、API 设计的参考项目，也有一定的教学价值。

---

项目基本信息

• 🌟 Stars：3,114
• 🍴 Forks：473
• 📝 许可证：AGPL-3.0
• 🐍 语言：Python（3.10+）
• 🔗 主页：https://pypi.org/project/gemini-webapi/