简介

什么是 gemini-web2api ？

gemini-web2api 是一个开源的 Python 工具，它通过逆向 Google Gemini 网页端的 StreamGenerate 协议，将 Gemini Web 转换为 OpenAI 兼容的 API 接口。用户可以在任何支持 OpenAI API 的客户端（如 Cherry Studio、ChatBox 等）中，直接调用 Gemini 的模型能力，无需付费订阅、无需 API Key，只需一个免费的 Google 账号。

主要特点

• OpenAI 兼容：直接替换 /v1/chat/completions 和 /v1/models，支持 OpenAI SDK 和任意兼容客户端
• 可选 API Key：api_keys 为空时免密，填入后按 OpenAI Bearer Key 校验，灵活控制访问
• 多模型支持：涵盖 Flash、Flash Thinking（2 万字+长输出）、Pro、Auto、Lite 等多种模型
• 思考深度调节：通过 @think=N 后缀控制思考深度（0 最深、4 最浅），适应不同场景
• 工具调用：完整的 Function Calling 支持（OpenAI 格式），可扩展 AI Agent 能力
• 联网搜索：内置 Gemini 原生互联网搜索能力，无需额外配置
• 流式输出：支持 SSE Streaming，实时获取生成结果
• 跨平台零依赖：纯 Python 实现，仅依赖标准库，可在任何 Python 3.8+ 环境运行
• 双重 API 兼容：同时支持 OpenAI Responses API（Codex CLI）和 Google 原生 API（Gemini CLI）
• 开源免费：基于 MIT 协议开源，可免费使用和修改

应用场景

• AI 应用开发：开发者可以用 OpenAI SDK 直接调用 Gemini 模型进行开发测试，无需申请 Google API Key
• Chat 客户端集成：在 Cherry Studio、ChatBox、NextChat 等客户端中配置自定义 API，免费使用 Gemini 模型
• AI Agent 构建：利用 Function Calling 能力，构建基于 Gemini 的智能助手和自动化工具
• 后端服务对接：作为统一 API 网关，后端服务无需修改即可在 Gemini、OpenAI 等模型间切换

gemini-web2api 是一个轻量级的 API 转换工具，让你可以用最熟悉的 OpenAI 生态免费调用 Gemini 模型能力

安装

在群晖上以 Docker 方式安装。

提示：由于镜像托管在 ghcr.io，群晖 Docker 套件无法直接搜索，需要通过命令行拉取镜像。

准备

config.json

创建 config.json 文件，即可修改端口、API Key、代理等参数，而不用使用环境变量

{
  "port": 8481,
  "host": "0.0.0.0",
  "retry_attempts": 3,
  "retry_delay_sec": 2,
  "request_timeout_sec": 180,
  "api_keys": ["sk-your-key"],
  "cookie_file": null,
  "proxy": "http://192.168.0.206:2081",
  "log_requests": true
}

参数的简单说明

配置项	默认值	说明
port	8481	监听端口
host	0.0.0.0	监听地址
api_keys	["sk-your-key"]	API Key 列表，空数组则不校验
proxy	null	HTTP 代理地址
cookie_file	null	Cookie 文件路径
request_timeout_sec	180	请求超时时间
log_requests	true	是否记录请求日志

配置说明：

• api_keys 为空数组 [] 时，任何人都可以访问你的 API；填入一个或多个密钥后，/v1/* 接口需要 Authorization: Bearer <key> 或 x-api-key: <key>。
• 如果无法直接访问 gemini.google.com，需设置 proxy 参数。

获取 Cookie（可选）

如果需要使用 gemini-3.1-pro 等 Pro 模型，需要提供 Google 账号的 Cookie。不需要付费订阅，免费 Google 账号即可。

步骤如下：

• 1. 打开 Gemini 并登录

在 Chrome 浏览器中访问 gemini.google.com，并用任意 Google 账号登录

• 2. 打开开发者工具

按 F12 打开开发者工具，切换到 Application（应用程序）标签页

• 3. 找到 Cookie

在左侧导航栏找到 Cookies → https://gemini.google.com

• 4. 复制关键 Cookie 值

在列表中找到并复制以下 6 个 Cookie 的值：

• SID
• HSID
• SSID
• APISID
• SAPISID
• __Secure-1PSID

• 5. 创建 Cookie 文件

在 gemini-web2api 目录下创建 cookie.txt，格式如下：

SID=你的值; HSID=你的值; SSID=你的值; APISID=你的值; SAPISID=你的值; __Secure-1PSID=你的值

或者使用 JSON 格式：

{
  "cookie": "SID=xxx; HSID=xxx; SSID=xxx; APISID=xxx; SAPISID=xxx; __Secure-1PSID=xxx",
  "sapisid": "你的 SAPISID 值"
}

6. 修改配置

在 config.json 中设置 Cookie 文件路径：

{
  "cookie_file": "/app/cookie.txt"
}

注意：Cookie 有过期时间，如果发现 Pro 模型路由异常，重新执行以上步骤更新 Cookie 即可。

docker cli 安装

如果你熟悉命令行，可能用 docker cli 更快捷

# 新建文件夹 gemini-web2api 和 子目录
mkdir -p /volume1/docker/gemini-web2api

# 进入 gemini-web2api 目录
cd /volume1/docker/gemini-web2api

# 编辑 config.json 修改配置

# 运行容器
docker run -d \
  --name=gemini-web2api \
  --restart=unless-stopped \
  -p 8481:8481 \
  -v $(pwd)/config.json:/app/config.json \
  ghcr.io/sophomoresty/gemini-web2api:latest

如需挂载 Cookie 文件（使用 Pro 模型时）：

# 编辑 cookie.txt 修改配置

# 运行容器
docker run -d \
  --name=gemini-web2api \
  --restart=unless-stopped \
  -p 8481:8481 \
  -v $(pwd)/config.json:/app/config.json \
  -v $(pwd)/cookie.txt:/app/cookie.txt \
  ghcr.io/sophomoresty/gemini-web2api:latest

docker-compose 安装

也可以用 docker-compose 安装，将下面的内容保存为 docker-compose.yml 文件

version: '3.8'

services:
  gemini-web2api:
    image: ghcr.io/sophomoresty/gemini-web2api:latest
    container_name: gemini-web2api
    restart: unless-stopped
    ports:
      - "8481:8481"
    volumes:
      - ./config.json:/app/config.json    # 配置文件
      - ./cookie.txt:/app/cookie.txt      # Cookie 文件（可选）

然后通过 SSH 登录到您的群晖，执行下面的命令：

# 新建文件夹 gemini-web2api 和 子目录
mkdir -p /volume1/docker/gemini-web2api

# 进入 gemini-web2api 目录
cd /volume1/docker/gemini-web2api

# 编辑 config.json 修改配置

# 编辑 cookie.txt 修改配置

# 将 docker-compose.yml 放入当前目录

# 一键启动
docker-compose up -d

运行

在浏览器中访问 http://<群晖IP>:8481 即可验证服务是否启动成功

{
  "status": "ok",
  "version": "1.1.0",
  "models": [
    "gemini-3.5-flash",
    "gemini-3.5-flash-thinking",
    "gemini-3.1-pro",
    "gemini-3.1-pro-enhanced",
    "gemini-auto",
    "gemini-3.5-flash-thinking-lite",
    "gemini-flash-lite"
  ]
}

curl

直接用 curl 做个测试

curl http://192.168.0.197:8481/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-key" \
  -d '{"model":"gemini-3.5-flash","messages":[{"role":"user","content":"你好!"}]}'

输出格式化之后

{
  "id": "chatcmpl-8ae42541c426",
  "object": "chat.completion",
  "created": 1780212411,
  "model": "gemini-3.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！很高兴和你交流。今天有什么我可以帮你的吗？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 6,
    "total_tokens": 6
  }
}

Cherry Studio

也可以在任意 OpenAI 兼容客户端中配置，例如 Cherry Studio

字段	值
Base URL	http://<群晖IP>:8481/v1
API Key	sk-your-key（或 config.json 中配置的值）
Model	gemini-3.5-flash-thinking

点获取模型列表

和页面上一样，有 7 个模型

随便聊个天

注意事项

1. 镜像来自 ghcr.io：镜像托管在 ghcr.io，群晖 Docker 套件无法直接搜索，需要通过 SSH 命令行拉取 docker pull ghcr.io/sophomoresty/gemini-web2api:latest
2. 网络访问要求：服务器需要能够访问 gemini.google.com（在中国大陆等地区需配置代理）
3. Pro 模型需要 Cookie：匿名访问可用所有模型，但 gemini-3.1-pro 实际路由到 Flash；要获得真正的 Pro 路由，需提供 Cookie 文件
4. Cookie 获取：登录任意免费 Google 账号后，从浏览器开发者工具中复制 SID、HSID、SSID、APISID、SAPISID、__Secure-1PSID 等关键 Cookie
5. 频率限制：Google 可能限制高频请求，服务会自动重试，但持续高负载仍可能被限制，所以不建议用于编程、小龙虾等场合，避免账号被封

参考文档

Sophomoresty/gemini-web2api: Convert Google Gemini web into OpenAI-compatible API. Zero auth, cross-platform, single file.
地址：https://github.com/Sophomoresty/gemini-web2api