Gemini-web2api : Gemini 网页端转为通用api接口

项目地址：https://github.com/Sophomoresty/gemini-web2api

项目介绍

无需官方 API Key、单文件极简架构、直接将 Google Gemini 网页端接口转换为标准的 OpenAI /v1 规范。你可以无缝对接 Cherry Studio、ChatBox、NextChat 等主流客户端，甚至作为本地开发环境与自动化工具的免费驱动引擎。

核心亮点与特性

• 零门槛即开即用：支持免认证匿名访问（无需填 Key），也可配置自定义 Token 实现接口鉴权保护。
• 标准协议全兼容：
  • 支持 OpenAI 规范的 /v1/chat/completions、/v1/models。
  • 具备完整的 SSE 流式输出（Streaming）支持。
  • 支持 Google 原生接口 /v1beta/models（可兼容官方 Gemini CLI 工具）及 OpenAI Codex CLI 接口。
• 多模型与深度思考支持：
  • 支持 Flash、Flash Thinking（单次支持 2 万字超长输出）、Lite 等模型。
  • 自定义思考深度：支持使用 @think=N 后缀微调模型推理深度（0 代表最深，4 代表最浅）。
• 原生联网搜索：直接继承 Gemini Web 端的互联网实时检索能力。
• 极致轻量：纯 Python 编写，单文件架构，除 httpx 外零额外重度依赖。

技术原理

项目的核心是通过逆向 Gemini 网页端的通信链路，完成私有协议与标准 OpenAI 协议之间的适配桥接：

1. 协议逆向与伪装：解析 Gemini Web 的 StreamGenerate RPC 调用链路，将 OpenAI 发送的 messages 数组转化为 Gemini 内部接收的类 Protobuf 数据结构。
2. 模型动态路由：Gemini 网页端前端通过请求 Payload 中的特定字段（映射自前端 JS 的 MODE_CATEGORY 枚举）区分模型类型。程序在转发时自动注入该参数，实现模型切换。
3. 认证状态机：
   • 免登录模式：利用 Web 端开放的临时匿名会话机制直接请求，无需准备任何凭证。
   • Cookie 鉴权模式：解析并挂载用户的 Google 登录 Cookie 及 SNlM0e（XSRF Token），用于解锁更稳定的配额和高级会话。

快速上手

1.本地 Python 单文件启动

只需安装轻量网络库，即可一键拉起本地网关：

# 1. 安装依赖
pip install httpx

# 2. 运行代理服务（默认监听 http://localhost:8081）
python gemini_web2api.py

如果服务器环境无法直接访问 Google 服务，可以指定代理端口：

python gemini_web2api.py --proxy http://127.0.0.1:7890

2.Docker 容器化部署

在 VPS 上使用容器托管，直接利用 Docker 部署：

# 推荐使用 host 网络模式，避免 Docker NAT IP 触发上游风控限制
docker run -d \
  --name gemini-web2api \
  --restart unless-stopped \
  --network host \
  sophomoresty/gemini-web2api

注意：如果在桥接网络（Bridge）下偶现空响应（content: null），这通常是 Gemini 上游对部分 Docker 虚拟网段阻断所致，将容器网络切换为 host 模式即可解决。

客户端接入配置

以 Cherry Studio 或 ChatBox 等第三方客户端为例，新增自定义模型服务商即可：

• API 地址 / Base URL：http://localhost:8081/v1（或替换为你 VPS 的内网/公网解析域名）
• API Key：若服务端未启用鉴权，此处任意填写即可（如 sk-fake-key）；若开启了 api_keys，填入对应 Token。
• 可用模型 网页端所有模型均可以使用

特别注意

作为基于网页逆向的兼容方案，以下几点必须格外注意：

1. Pro 路由特性：在未挂载 Google One（Gemini Advanced）订阅 Cookie 的情况下，即便在客户端指定了 Pro 模型，后端通常也会静默回退至 Flash 核心。
2. 多模态与图片输入限制：Gemini 网页端图片上传依赖专有的 WIZ streaming RPC（ProcessFile）通道，因此该项目目前主要聚焦在文本交互，多模态文件上传可能受到限制或需要额外 Cookie 支持。
3. 会话模拟机制：接口每次接收请求视为单次交互，多轮对话主要依赖客户端在上下文中携带的历史 Message 进行模拟。
4. 频率与并发风控：虽然脚本自带请求重试机制，但作为网页代理方案，切忌进行短时间高频并发压测，建议主要用于个人本地工作流或开发自用。