Repository files navigation

这是一个基于 Python 的代理服务器，用于将 Google AI Studio 的网页界面转换为 OpenAI 兼容的 API。通过 Camoufox (反指纹检测的 Firefox) 和 Playwright 自动化，提供稳定的 API 访问。

This project is generously sponsored by ZMTO. Visit their website:https://zmto.com/

本项目由 ZMTO 慷慨赞助服务器支持。访问他们的网站：https://zmto.com/

本项目的诞生与发展，离不开以下个人、组织和社区的慷慨支持与智慧贡献：

• 项目发起与主要开发: @CJackHwang (https://github.com/CJackHwang)
• 功能完善、页面操作优化思路贡献: @ayuayue (https://github.com/ayuayue)
• 实时流式功能优化与完善: @luispater (https://github.com/luispater)
• 3400+行主文件项目重构伟大贡献: @yattin (Holt) (https://github.com/yattin)
• 项目后期高质量维护: @Louie （https://github.com/NikkeTryHard）
• 社区支持与灵感碰撞: 特别感谢Linux.do 社区 成员们的热烈讨论、宝贵建议和问题反馈，你们的参与是项目前进的重要动力。

同时，我们衷心感谢所有通过提交 Issue、提供建议、分享使用体验、贡献代码修复等方式为本项目默默奉献的每一位朋友。是你们共同的努力，让这个项目变得更好！

这是当前维护的 Python 版本。不再维护的 Javascript 版本请参见deprecated_javascript_version/README.md。

• Python: >=3.9, <4.0 (推荐 3.10+ 以获得最佳性能，Docker 环境使用 3.10)
• 依赖管理:Poetry (现代化 Python 依赖管理工具，替代传统 requirements.txt)
• 类型检查:Pyright (可选，用于开发时类型检查和 IDE 支持)
• 操作系统: Windows, macOS, Linux (完全跨平台支持，Docker 部署支持 x86_64 和 ARM64)
• 内存: 建议 2GB+ 可用内存 (浏览器自动化需要)
• 网络: 稳定的互联网连接访问 Google AI Studio (支持代理配置)

• OpenAI 兼容 API: 支持/v1/chat/completions 端点，完全兼容 OpenAI 客户端和第三方工具
• 三层流式响应机制: 集成流式代理 → 外部 Helper 服务 → Playwright 页面交互的多重保障
• 智能模型切换: 通过 API 请求中的model 字段动态切换 AI Studio 中的模型
• 完整参数控制: 支持temperature、max_output_tokens、top_p、stop、reasoning_effort 等所有主要参数
• 反指纹检测: 使用 Camoufox 浏览器降低被检测为自动化脚本的风险
• 脚本注入功能 v3.0: 使用 Playwright 原生网络拦截，支持油猴脚本动态挂载，100%可靠 🆕
• 现代化 Web UI: 内置测试界面，支持实时聊天、状态监控、分级 API 密钥管理
• 图形界面启动器: 提供功能丰富的 GUI 启动器，简化配置和进程管理
• 灵活认证系统: 支持可选的 API 密钥认证，完全兼容 OpenAI 标准的 Bearer token 格式
• 模块化架构: 清晰的模块分离设计，api_utils/、browser_utils/、config/ 等独立模块
• 统一配置管理: 基于.env 文件的统一配置方式，支持环境变量覆盖，Docker 兼容
• 现代化开发工具: Poetry 依赖管理 + Pyright 类型检查，提供优秀的开发体验

graph TD    subgraph "用户端 (User End)"        User["用户 (User)"]        WebUI["Web UI (Browser)"]        API_Client["API 客户端 (API Client)"]    end    subgraph "启动与配置 (Launch & Config)"        GUI_Launch["gui_launcher.py (图形启动器)"]        CLI_Launch["launch_camoufox.py (命令行启动)"]        EnvConfig[".env (统一配置)"]        KeyFile["auth_profiles/key.txt (API Keys)"]        ConfigDir["config/ (配置模块)"]    end    subgraph "核心应用 (Core Application)"        FastAPI_App["api_utils/app.py (FastAPI 应用)"]        Routes["api_utils/routers/* (路由处理)"]        RequestProcessor["api_utils/request_processor.py (请求处理)"]        AuthUtils["api_utils/auth_utils.py (认证管理)"]        PageController["browser_utils/page_controller.py (页面控制)"]        ScriptManager["browser_utils/script_manager.py (脚本注入)"]        ModelManager["browser_utils/model_management.py (模型管理)"]        StreamProxy["stream/ (流式代理服务器)"]    end    subgraph "外部依赖 (External Dependencies)"        CamoufoxInstance["Camoufox 浏览器 (反指纹)"]        AI_Studio["Google AI Studio"]        UserScript["油猴脚本 (可选)"]    end    User -- "运行 (Run)" --> GUI_Launch    User -- "运行 (Run)" --> CLI_Launch    User -- "访问 (Access)" --> WebUI    GUI_Launch -- "启动 (Starts)" --> CLI_Launch    CLI_Launch -- "启动 (Starts)" --> FastAPI_App    CLI_Launch -- "配置 (Configures)" --> StreamProxy    API_Client -- "API 请求 (Request)" --> FastAPI_App    WebUI -- "聊天请求 (Chat Request)" --> FastAPI_App    FastAPI_App -- "读取配置 (Reads Config)" --> EnvConfig    FastAPI_App -- "使用路由 (Uses Routes)" --> Routes    AuthUtils -- "验证密钥 (Validates Key)" --> KeyFile    ConfigDir -- "提供设置 (Provides Settings)" --> EnvConfig    Routes -- "处理请求 (Processes Request)" --> RequestProcessor    Routes -- "认证管理 (Auth Management)" --> AuthUtils    RequestProcessor -- "控制浏览器 (Controls Browser)" --> PageController    RequestProcessor -- "通过代理 (Uses Proxy)" --> StreamProxy    PageController -- "模型管理 (Model Management)" --> ModelManager    PageController -- "脚本注入 (Script Injection)" --> ScriptManager    ScriptManager -- "加载脚本 (Loads Script)" --> UserScript    ScriptManager -- "增强功能 (Enhances)" --> CamoufoxInstance    PageController -- "自动化 (Automates)" --> CamoufoxInstance    CamoufoxInstance -- "访问 (Accesses)" --> AI_Studio    StreamProxy -- "转发请求 (Forwards Request)" --> AI_Studio    AI_Studio -- "响应 (Response)" --> CamoufoxInstance    AI_Studio -- "响应 (Response)" --> StreamProxy    CamoufoxInstance -- "返回数据 (Returns Data)" --> PageController    StreamProxy -- "返回数据 (Returns Data)" --> RequestProcessor    FastAPI_App -- "API 响应 (Response)" --> API_Client    FastAPI_App -- "UI 响应 (Response)" --> WebUI

推荐新用户按照快速开始指南 进行部署，预计 15-30 分钟即可完成。

# 1️⃣ 克隆并安装git clone https://github.com/CJackHwang/AIstudioProxyAPI.gitcd AIstudioProxyAPIpoetry install# 自动创建虚拟环境并安装依赖# 2️⃣ 配置环境cp .env.example .envnano .env# 编辑配置（可选，默认配置即可使用）# 3️⃣ 首次认证并启动poetry run python launch_camoufox.py --debug# 首次认证（需要登录 Google）# 认证成功后，按 Ctrl+C 停止，然后使用无头模式运行：poetry run python launch_camoufox.py --headless

# 健康检查curl http://127.0.0.1:2048/health# 获取模型列表curl http://127.0.0.1:2048/v1/models# 测试聊天（非流式）curl -X POST http://127.0.0.1:2048/v1/chat/completions \  -H"Content-Type: application/json" \  -d'{"model":"gemini-2.5-pro","messages":[{"role":"user","content":"Hello"}]}'# 测试流式聊天curl -X POST http://127.0.0.1:2048/v1/chat/completions \  -H"Content-Type: application/json" \  -d'{"model":"gemini-2.5-pro","messages":[{"role":"user","content":"讲个故事"}],"stream":true}' --no-buffer

打开浏览器访问http://127.0.0.1:2048/ 使用内置的 Web 聊天界面。

• Python 3.9+ (推荐 3.10 或 3.11)
• 2GB+ 可用内存
• 稳定的互联网连接

macOS/Linux:

curl -sSL https://raw.githubusercontent.com/CJackHwang/AIstudioProxyAPI/main/scripts/install.sh| bash

Windows (PowerShell):

iwr-useb https://raw.githubusercontent.com/CJackHwang/AIstudioProxyAPI/main/scripts/install.ps1| iex

# macOS/Linuxcurl -sSL https://install.python-poetry.org| python3 -# Windows (PowerShell)(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content| py -

git clone https://github.com/CJackHwang/AIstudioProxyAPI.gitcd AIstudioProxyAPI

poetry install

# 激活 Poetry 环境poetry shell# 安装 Playwright 浏览器playwright install firefox# 下载 Camoufox 数据文件camoufox fetch# 或使用备用方法python fetch_camoufox_data.py

# 导出 requirements.txtpoetryexport -f requirements.txt --output requirements.txt --without-hashes# 使用 uv (更快)pip install uvuv pip install -r requirements.txt# 使用 pip (传统方式)pip install -r requirements.txt

# 需要先手动配置 CAMOUFOX_WS_ENDPOINT 环境变量export CAMOUFOX_WS_ENDPOINT=ws://127.0.0.1:9222uvicorn server:app --host 0.0.0.0 --port 2048

# 实时日志tail -f logs/app.log# 错误日志grep -i error logs/app.log# 启动日志tail -f logs/launch_app.log

python launch_camoufox.py --help常用选项：  --headless              无头模式运行  --debug                 调试模式（显示浏览器窗口）  --virtual-display       使用虚拟显示（Linux 无 GUI）  --server-port PORT      FastAPI 端口（默认 2048）  --stream-port PORT      流式代理端口（默认 3120）  --internal-camoufox-proxy URL  浏览器代理地址

项目采用.env 文件进行配置管理，所有配置项集中管理，无需复杂的命令行参数。

# 1. 复制配置模板cp .env.example .env# 2. 编辑配置文件nano .env# 或使用其他编辑器

• ✅版本更新无忧:git pull 后配置保留，无需重新设置
• ✅启动命令简化: 一行命令启动，无需长串参数
• ✅安全性:.env 已被.gitignore 忽略，不会泄露敏感信息
• ✅Docker 兼容: Docker 和本地使用相同的配置方式

• 环境变量配置指南 - 配置管理和使用方法 ⭐
• 环境变量完整参考 - 所有配置项的详细说明 📋

• 快速开始指南 - 15分钟快速部署和测试 🎯
• 安装指南 - 详细的安装步骤和环境配置
• 环境变量配置指南 - .env 文件配置管理 ⭐
• 环境变量完整参考 - 所有配置项的详细说明 📋
• 认证设置指南 - 首次运行与认证文件设置
• 日常运行指南 - 日常使用和配置选项

• API 使用指南 - API 端点和客户端配置
• OpenAI 兼容性说明 - 与 OpenAI API 的差异和限制 🔄
• 客户端集成示例 - Python、JavaScript、cURL 等示例代码 💻
• Web UI 使用指南 - Web 界面功能说明
• 脚本注入指南 - 油猴脚本动态挂载功能使用指南 (v3.0) 🆕

• 流式处理模式详解 - 三层响应获取机制详细说明 🆕
• 高级配置指南 - 高级功能和配置选项
• 日志控制指南 - 日志系统配置和调试
• 故障排除指南 - 常见问题解决方案

• 平台差异说明 - Windows/macOS/Linux 差异与注意事项
• Docker 部署指南 (docker/README-Docker.md) - 完整容器化部署流程
• Docker 快速指南 (docker/README.md) - 一键 Compose 启动

• 项目架构指南 - 模块化架构设计和组件详解 🆕
• 开发者指南 - Poetry、Pyright 和开发工作流程
• 依赖版本说明 - Poetry 依赖管理和版本控制详解

以 Open WebUI 为例：

1. 打开 Open WebUI
2. 进入 "设置" -> "连接"
3. 在 "模型" 部分，点击 "添加模型"
4. 模型名称: 输入你想要的名字，例如aistudio-gemini-py
5. API 基础 URL: 输入http://127.0.0.1:2048/v1
6. API 密钥: 留空或输入任意字符
7. 保存设置并开始聊天

本项目支持通过 Docker 进行部署，使用Poetry 进行依赖管理，完全支持.env 配置文件！

📁注意: 所有 Docker 相关文件已移至docker/ 目录，保持项目根目录整洁。

# 1. 准备配置文件cd dockercp .env.docker .envnano .env# 编辑配置# 2. 使用 Docker Compose 启动docker compose up -d# 3. 查看日志docker compose logs -f# 4. 版本更新 (在 docker 目录下)bash update.sh

• Docker 部署指南 (docker/README-Docker.md) - 包含完整的 Poetry +.env 配置说明
• Docker 快速指南 (docker/README.md) - 快速开始指南

• ✅Poetry 依赖管理: 使用现代化的 Python 依赖管理工具
• ✅多阶段构建: 优化镜像大小和构建速度
• ✅配置统一: 使用.env 文件管理所有配置
• ✅版本更新:bash update.sh 即可完成更新
• ✅目录整洁: Docker 文件已移至docker/ 目录
• ✅跨平台支持: 支持 x86_64 和 ARM64 架构
• ⚠️认证文件: 首次运行需要在主机上获取认证文件，然后挂载到容器中

本项目使用Camoufox 来提供具有增强反指纹检测能力的浏览器实例。

• 核心目标: 模拟真实用户流量，避免被网站识别为自动化脚本或机器人
• 实现方式: Camoufox 基于 Firefox，通过修改浏览器底层 C++ 实现来伪装设备指纹（如屏幕、操作系统、WebGL、字体等），而不是通过容易被检测到的 JavaScript 注入
• Playwright 兼容: Camoufox 提供了与 Playwright 兼容的接口
• Python 接口: Camoufox 提供了 Python 包，可以通过camoufox.server.launch_server() 启动其服务，并通过 WebSocket 连接进行控制

使用 Camoufox 的主要目的是提高与 AI Studio 网页交互时的隐蔽性，减少被检测或限制的可能性。但请注意，没有任何反指纹技术是绝对完美的。

AI Studio Proxy API 由多个组件协同工作，提供完整的代理服务：

作用: 提供 OpenAI 兼容的 REST API 端点

功能:

• 处理/v1/chat/completions、/v1/models 等 API 请求
• 管理请求队列和并发控制
• 提供 Web UI 和健康检查端点
• 处理 API 密钥认证

启动方式:

# 通过 launch_camoufox.py 自动启动（推荐）python launch_camoufox.py --headless# 或直接启动（需要手动配置浏览器端点）uvicorn server:app --host 0.0.0.0 --port 2048

端口配置:.env 中的PORT 或DEFAULT_FASTAPI_PORT

作用: 提供具有反指纹检测能力的 Firefox 浏览器实例

功能:

• 模拟真实用户流量，降低被检测风险
• 通过修改浏览器底层 C++ 代码伪装设备指纹
• 提供 Playwright 兼容的 WebSocket 端点
• 自动访问和操作 Google AI Studio 页面

启动方式: 通过launch_camoufox.py 自动启动和管理

端口配置:.env 中的DEFAULT_CAMOUFOX_PORT (默认 9222)

连接方式: Playwright 通过 WebSocket (如ws://127.0.0.1:9222) 连接

作用: 控制浏览器执行自动化操作

功能:

• 管理 AI Studio 页面交互（输入提示、提取响应）
• 动态切换模型
• 设置模型参数（temperature、max_tokens 等）
• 捕获错误并生成快照

集成方式: 在 FastAPI 应用启动时初始化，连接到 Camoufox 浏览器

作用: 提供低延迟的流式响应代理

功能:

• 直接转发 AI Studio 的流式响应，减少延迟
• 在本地 (127.0.0.1:3120) 作为代理服务器运行
• 支持自签名证书管理（certs/ 目录）
• 作为三层响应获取机制的第一层

启动方式: FastAPI 应用启动时自动启动独立进程

端口配置:.env 中的STREAM_PORT (默认 3120，设为0 禁用)

工作流程:

客户端请求 → FastAPI → Stream Proxy → AI Studio                ↓            ↓         （备用）Playwright 页面交互

作用: 提供图形化的启动和配置界面

功能:

• 可视化配置端口、代理、认证等选项
• 一键启动/停止所有服务
• 实时查看日志输出
• 管理多个配置预设

启动方式:

python gui_launcher.py

项目采用创新的三层响应获取机制，在性能和可靠性之间取得平衡：

1. 第一层: 集成流式代理服务 (默认启用)

   • ⚡性能最优: 直接转发流式响应，延迟最低
   • 📍端口: 3120 (可通过STREAM_PORT 配置)
   • ✅适用场景: 流式请求、实时对话
   • ⚠️限制: 参数支持有限，主要支持基础参数

2. 第二层: 外部 Helper 服务 (可选配置)

   • 🔧需要: 有效的认证文件 (auth_profiles/active/*.json)
   • 📡配置: 通过--helper <endpoint> 或.env 配置
   • ✅适用场景: 需要额外功能的场景
   • ⚠️限制: 取决于 Helper 服务实现

3. 第三层: Playwright 页面交互 (最终后备)

   • 🎯功能完整: 支持所有参数和模型切换
   • 🔧参数:temperature,max_output_tokens,top_p,stop,reasoning_effort 等
   • ⏱️延迟较高: 需要页面操作，但功能最完整
   • ✅适用场景: 需要精确参数控制、模型切换

启用流式代理 (推荐):

STREAM_PORT=3120

禁用流式代理，使用 Playwright:

STREAM_PORT=0

配置 Helper 服务:

python launch_camoufox.py --helper http://helper.example.com:8080

重要: 客户端负责维护完整的聊天记录并将其发送给代理。

• ✅支持: 客户端管理对话历史，每次请求发送完整上下文
• ❌不支持: 在 AI Studio UI 内编辑或分叉历史消息
• 📝建议: 使用支持对话管理的客户端（如 Open WebUI、ChatBox 等）

以下是一些计划中的改进方向：

• 云服务器部署指南: 提供更详细的在主流云平台上部署和管理服务的指南
• 认证更新流程优化: 探索更便捷的认证文件更新机制，减少手动操作
• 流程健壮性优化: 减少错误几率和接近原生体验

欢迎提交 Issue 和 Pull Request！

AGPLv3

如果您觉得本项目对您有帮助，并且希望支持作者的持续开发，欢迎通过以下方式进行捐赠。您的支持是对我们最大的鼓励！