将浏览器版 Gemini 封装为 OpenAI 兼容 API 服务

方案简介

WebAI-to-API 是一个浏览器原生的 AI 运行时，它把基于浏览器的 AI 服务（如 Google Gemini）封装为 OpenAI 兼容的 /v1/chat/completions API。这样，任何支持 OpenAI 接口格式的客户端（如 Hermes Agent）都可以直接调用 Gemini 的能力，而无需官方 API Key。项目采用 Provider 架构进行统一路由，Gemini 可通过 WebAPI 后端或 Playwright 浏览器原生运行时访问。适合希望在本地自托管、将网页版 Gemini 转为标准 API 使用的开发者。

亮点与能力

• OpenAI 兼容的 /v1/chat/completions API
• 基于 Provider 的统一路由架构
• 流式响应支持（SSE）
• 会话延续支持
• 健康、就绪与运行时诊断端点
• Docker 部署支持
• 认证管理与浏览器登录流程
• 无状态（client-owned-history）聊天端点，支持流式与工具调用

组成与分工

• Gemini：目标 AI 服务，通过 WebAPI 后端或浏览器运行时提供模型能力
• Playwright：浏览器原生运行时，用于驱动浏览器方式访问 Gemini（安装时同步安装 Playwright Chromium）
• Poetry：Python 依赖与运行管理工具，用于启动服务与认证脚本
• Docker / Docker Compose：容器化部署方案，支持 docker compose up -d --build
• Swagger UI：服务器运行时提供交互式 API 文档
• SQLite：会话快照存储（无状态端点不使用）

前置要求

需要 Git、Python >=3.11,<3.13 以及 Poetry。在 Windows 上，为安全处理 Gemini WebAPI 临时 Cookie 缓存，请使用 Python 3.11.10+ 或 3.12.4+。

实施步骤

1. 安装与初始化

克隆仓库并运行平台对应的安装脚本：

bash
git clone https://github.com/Amm1rr/WebAI-to-API.git
cd WebAI-to-API
./install.sh

Windows PowerShell：

git clone https://github.com/Amm1rr/WebAI-to-API.git
cd WebAI-to-API
.\install.ps1

安装脚本会创建缺失的配置和运行时状态、安装项目依赖及 Playwright Chromium，并运行诊断。

2. 配置

检查生成的 config.conf，核心 Gemini 设置示例：

ini
[Gemini]
backend = webapi
default_model = gemini-3-flash
extended_thinking = false

3. 认证

浏览器方式登录 Gemini：

bash
poetry run python verify_login.py

Gemini WebAPI 也可使用配置的 cookies。

4. 启动服务

bash
poetry run python src/run.py

启动后：API 位于 http://localhost:6969，Dashboard 位于 http://localhost:6969/ui，Swagger UI 位于 http://localhost:6969/docs。

使用与配置要点

发送第一个请求验证服务：

bash
curl -X POST http://localhost:6969/v1/chat/completions \
-H "Content-Type: application/" \
-d '{
"model": "gemini-3-flash",
"messages": [

"role": "user",
"content": "Hello!"

模型路由：不带前缀的 Gemini 模型使用配置的 backend；playwright/... 强制浏览器原生路由。可用模型以 /v1/models 为准。

Docker 方式更新部署：

bash
git pull
APP_UID=$(id -u) APP_GID=$(id -g) docker compose up -d --build

Dashboard 提供运行时状态、认证视图、模型与 API 发现、playground 及会话管理。

注意事项与常见问题

• 安全限制：项目不提供调用方 API 认证，除非有外部认证与访问控制保护，否则保持默认 localhost 绑定。
• 文件支持：OpenAI 风格的文件内容部分仅 Gemini WebAPI 支持，Gemini Playwright 与 Atlas 目前不支持文件部分，且 WebAPI 不保证文本/文件交错顺序的精确保留。
• /v1/temporary/chat/completions 已弃用，仅作为兼容包装委托给 stateless 实现。

优缺点

• ✓ OpenAI 兼容接口，客户端通用
• ✓ 支持 Docker 一键部署
• ✕ 不提供调用方 API 鉴权
• ✕ Playwright 后端不支持文件部分

出处

本方案挖掘自开源项目 Amm1rr/WebAI-to-API，方案内容与实施命令均来自其 README 原文。