Gemini Web2API

AI调用不再靠API Key，Gemini免费版秒变高性能助手，小白也能轻松部署。

你是否正在为官方API账户申请门槛高、信用卡认证卡壳而发愁？是否想在各种客户端里免费调用Gemini模型，却苦于没有Key？别急，开源社区有神奇力量——gemini-web2api来了。它不限制你的钱包，却能让你零成本自由调用Gemini。截至2026年6月，这款免费神器已让无数开发者尽享丝滑体验。

今天，作为一名技术评测者和AI工具重度用户，我将手把手带你了解这款工具。从安装部署到高阶玩法，一文通关。本文内容已于2026年6月基于项目最新版本实测更新。

一、gemini-web2api是什么？

gemini-web2api是一个由X-shuffle开发的开源Python项目。它巧妙地将Google Gemini网页端的AI能力封装成标准的OpenAI API格式，让你在任何支持OpenAI接口的客户端，免费调用Gemini的全部功能。项目地址：github.com/X-shuffle/gemini-web2api

也就是说，拥有gemini-web2api就相当于拥有了一座免费的Gemini模型桥梁。它可以让你使用任何一款兼容OpenAI API的软件——比如Cherry Studio、ChatBox等桌面客户端，或者直接在你的Python脚本里——无缝调用Gemini模型，甚至连代理和API Key都不用买。

Gemini官方提供两种使用路径：网页版（免费但有浏览器限制）与官方API（需付费Key）。gemini-web2api的出现打破了这种局面，它“借用”免费网页版的能力，在不付费且不违反使用道德的前提下，实现对Gemini模型的灵活调用。对于开发测试和小型个人项目来说，实用性拉满。

二、核心功能亮点

✅ 1. OpenAI标准完美兼容

支持标准/v1/chat/completions和/v1/models接口，无缝对接OpenAI SDK、Cherry Studio、ChatBox、Codex CLI等主流客户端，兼容OpenAI Responses API格式。

✅ 2. Flash Thinking深度推理

支持gemini-3.5-flash-thinking模型，最长输出可达2万字以上，可通过@think=N后缀灵活控制思考深度（N值0-4，0为最深，4为最浅），适应不同应用场景。

✅ 3. 联网搜索零配置

原生支持Gemini内置的互联网搜索能力，无需额外配置即可获取实时信息，确保返回内容的时效性与准确性。

✅ 4. 多模型自由选择

覆盖Flash、Pro、Auto、Lite等多种模型，满足从快速响应到复杂推理的各类需求，支持完整的Function Calling工具调用。

✅ 5. 极简零依赖部署

纯Python实现，仅使用标准库，无需额外依赖，真正做到跨平台即开即用（支持Windows/macOS/Linux）。服务启动后默认运行在http://localhost:8081/v1。

三、分步部署教程

我把安装方式分成三种：Python模式、Docker模式、群晖NAS模式。新手建议从Python模式开始，5分钟搞定。

方式一：Python本地快速部署（适合新手）

第1步：环境准备
确保已安装Python 3.8+和Git。代理（如Clash）必须开启，端口默认7897，以稳定连接Google服务。

第2步：克隆代码

git clone https://github.com/X-shuffle/gemini-web2api.git
cd gemini-web2api

第3步：安装依赖

pip install -r requirements.txt

或使用uv快速依赖：

uv add -r requirements.txt

第4步：启动服务

python -m gemini_web2api --proxy http://127.0.0.1:7897

看到Uvicorn running on http://0.0.0.0:8081提示即表示API服务成功启动。

第5步：测试调用

curl http://127.0.0.1:8081/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-3.5-flash","messages":[{"role":"user","content":"你好"}]}'

返回标准OpenAI格式JSON即代表部署成功。

方式二：Docker快速部署（推荐进阶用户）

对于不希望本地污染Python环境的用户，Docker是绝佳选择。

# 拉取镜像
docker pull ghcr.io/x-shuffle/gemini-web2api:latest

# 运行容器
docker run -d \
  -p 8081:8081 \
  -v $(pwd)/config.json:/app/config.json \
  ghcr.io/x-shuffle/gemini-web2api:latest

启动后服务地址为http://localhost:8081/v1，可配合Docker Compose统一编排管理。

方式三：群晖NAS部署（适合极客玩家）

国内玩家极多的群晖NAS也同样部署方便。

步骤简述：通过SSH登录群晖 → Docker命令拉取镜像 → 挂载本地config.json → 启动容器。配置参数可写在config.json中，自定义端口、代理及API Key。

config.json参数说明

{
  "port": 8481,           // 监听端口
  "host": "0.0.0.0",      // 监听地址
  "api_keys": [],         // API Key列表，为空则不校验
  "proxy": null,          // HTTP代理地址，如 http://127.0.0.1:7897
  "cookie_file": null,    // Cookie文件路径
  "request_timeout_sec": 180,   // 请求超时时间
  "log_requests": true    // 是否记录请求日志
}

配置要点：api_keys为空数组时，任何人都可访问你的API；填入密钥后，需在请求头携带Authorization: Bearer <key>。

四、Cookie配置解锁Pro模型

默认匿名访问时，Pro模型会降级到Flash级别。如需解锁真正的Pro模型路由，需要提供Google账号的Cookie。

获取步骤：

1. 浏览器登录 gemini.google.com
2. 按F12打开开发者工具 → Application → Cookies → https://gemini.google.com
3. 复制以下字段的值：SID、HSID、SSID、APISID、SAPISID、__Secure-1PSID
4. 将这些值按格式保存为cookie.txt，并在config.json中设置"cookie_file": "cookie.txt"
5. 重启服务，使用gemini-3.1-pro模型即可获得Pro能力

五、主流场景应用案例

📌 场景一：客户端集成

在Cherry Studio或ChatBox中配置自定义API地址——填写http://localhost:8081/v1，API Key任意字符串即可免费调用Gemini。兼容OpenAI格式的客户端均可零改动接入。

📌 场景二：Python脚本调用

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8081/v1",
    api_key="sk-any-key"      # api_keys为空时可随便填
)

response = client.chat.completions.create(
    model="gemini-3.5-flash-thinking",
    messages=[{"role": "user", "content": "用中文解释RAG技术"}]
)
print(response.choices[0].message.content)

运行以上代码即可获取Gemini流式或非流式的标准OpenAI格式响应。

六、与其他免费方案对比（横向比较）

相比gpt4free等多模型聚合方案，gemini-web2api轻量聚焦，部署极其简单，适合只需要免费利用Gemini官方顶级模型的用户。而token-free-gateway则覆盖了更多AI平台，适用于统一中转场景。

七、使用中的局限与建议

⚠️ 已知限制：

1. 多模态输入暂不支持：受限于Gemini Web专有协议，无法上传图片或文件，只能用纯文本提问。
2. 多轮对话需人工构造：对历史上下文的管理，全靠每次请求前自行整理Prompt。
3. 频率限制与风控风险：高频请求可能触发Google风控，返回429等错误，建议合理设置重试间隔。

💡 应对建议：

• 使用代理并开启随机IP轮换，降低风控可能性
• 在代码中引入retry机制（建议延迟2-5秒，重试3次）
• 多准备几个Google账号轮换使用
• 务必遵守Google服务条款，避免过量调用

八、结语：值不值得上手？

总的来说，gemini-web2api对于想零成本试水Gemini能力的开发者来说，绝对不容错过。无需任何认证、几乎无风险部署、无缝支持OpenAI生态这三大优势，让它在同类免费方案中脱颖而出。

当然，如果你追求生产环境的高并发性能与数据安全，建议优先考虑官方API；但对个人开发者、AI爱好者或希望迅速构建MVP的朋友来说，gemini-web2api是最理想的入门工具。现在就克隆代码，开始你的免费Gemini之旅吧！