AIstudioProxyAPI 介绍与选型指南

为「想把 Google AI Studio 网页版能力转成 OpenAI 兼容 API 自托管使用」的场景提供一款代理工具的完整认知与选型依据，覆盖项目定位、核心架构、功能特性、同类横向对比与选型建议。本篇为认知篇，全部信息来源于官方仓库与

AIstudioProxyAPIAIstudioProxyAPILLM2026/10/23

AIstudioProxyAPI 介绍与选型指南

目标：为「想把 Google AI Studio 网页版能力转成 OpenAI 兼容 API 自托管使用」的场景提供一款代理工具的完整认知与选型依据，覆盖项目定位、核心架构、功能特性、同类横向对比与选型建议。本篇为认知篇，全部信息来源于官方仓库与公开网络资料，实际部署与验证请参见后续部署与配置各篇。

一、环境信息

本篇为认知与选型文档，不依赖本地运行环境，以下为信息取证口径：

  • 信息来源：GitHub 官方仓库 CJackHwang/AIstudioProxyAPI（README、Releases、docs/ 目录文档）
  • 信息查询日期：2026-10-23
  • 官方仓库地址：https://github.com/CJackHwang/AIstudioProxyAPI
  • 官方主仓确认：经 GitHub 搜索与多个仓库聚合站（repositorystats.com、relatedrepos.com、reepo.dev）交叉核对，CJackHwang/AIstudioProxyAPI 为该项目唯一官方主仓；社区另有下游分支与同名变体仓库（如 iBUHub/AIStudioToAPI），均非本篇所述官方主仓
  • 官方文档目录：仓库内 docs/（quick-start、configuration-reference、api-usage、deployment-and-operations、troubleshooting 等）

二、软件概述

AIstudioProxyAPI 是一个将 Google AI Studio 网页版转换为 OpenAI 兼容 API 的自托管代理服务。它基于 Python + FastAPI 构建，通过 Camoufox + Playwright 浏览器自动化技术，在本地启动一个反指纹检测的 Firefox 浏览器实例访问 AI Studio 网页对话界面，将 OpenAI 格式的 API 请求转换为网页操作，再把网页返回结果按 OpenAI 标准格式返回给调用方（来源：官方仓库 README，查询日期 2026-10-23）。

💡 技术拓展：「网页转 API」是获取大模型能力的三大路径之一，常见路径对比：

路径原理代表特点
官方 API 直连调用厂商计费 APIGemini API + openai 适配层稳定合规，按量计费
网页逆向转 API浏览器自动化操作网页版AIstudioProxyAPI、gpt4free复用网页版免费额度，随网页改版需跟进
第三方聚合网关代理转发多模型one-api / new-api只做转发聚合，不解决上游来源

AIstudioProxyAPI 属于第二条路径：不调用 Gemini 官方计费 API，而是复用 Google AI Studio 网页版的对话能力。

基本信息（来源：仓库 README/LICENSE、shields.io 徽章，查询日期 2026-10-23）：

项目信息
开源许可AGPLv3
主要语言Python（FastAPI + Playwright + Camoufox），前端为 Node.js 构建
当前稳定版本v4.1.2_py（2026-04-18 发布）
GitHub Stars2.5k
GitHub Forks428
最近提交2026 年 4 月（截至查询日期）
依赖管理Poetry
系统要求Python ≥3.9 且 <4.0（推荐 3.10+/3.11+）、内存 ≥2GB（推荐 4GB）

三、核心架构

项目采用「启动器 + FastAPI 服务 + 浏览器自动化 + 流式代理」的四层结构（来源：官方仓库 README 架构图与 docs/ 目录，查询日期 2026-10-23）：

用户端                 启动与配置              核心服务                    外部依赖
---------             ------------           ----------------           --------------
Web UI ──────┐                              ┌─ FastAPI 应用 (api_utils)
API 客户端 ───┼──► launch_camoufox.py ◄── .env 配置
             │         │                     ├─ 页面控制与自动化 (browser_utils) ──► Camoufox 浏览器 ──► Google AI Studio
             │         │                     └─ 流式代理 (stream)
             │         └────────────────────► Camoufox 内部进程

各层职责：

  1. 启动层（launch_camoufox.py）：统一入口脚本，负责检查依赖、校验端口占用、管理认证文件、拉起 Camoufox 浏览器子进程，并以 WebSocket Endpoint（默认 ws://127.0.0.1:9222）方式把浏览器交给服务层；
  2. 服务层（api_utils/ + server.py）：FastAPI 应用，对外提供 OpenAI 兼容端点（/v1/chat/completions、/v1/models）、健康检查（/health）、密钥管理与队列控制等接口，内置 Web UI 管理面板；
  3. 浏览器自动化层（browser_utils/）：基于 Playwright 驱动 Camoufox（反指纹 Firefox），负责打开 AI Studio 页面、注入消息、抓取回复、切换模型与参数；
  4. 流式代理层（stream/）：独立端口（默认 3120）的流式转发服务，配合 SSE 输出实现打字机效果。

关键设计点：

  • Camoufox 而非普通 Chromium：Camoufox 是反指纹检测的 Firefox 定制版，可自定义操作系统指纹（默认按宿主系统自动设定），降低被 Google 风控识别的概率（来源：官方 README 与仓库描述）；
  • 认证文件化：登录态以 Playwright storage_state（cookies + localStorage）JSON 文件形式保存在 auth_profiles/（active/saved/emergency 三级目录），支持多配置轮转；
  • 函数调用三模式：OpenAI tools 参数支持 auto/native/emulated 三种处理模式，native 走 AI Studio UI 原生操作，emulated 走文本提示注入，auto 自动尝试 native 并在失败时回退 emulated（来源：README 与 .env.example 注释）。

四、功能特性

以下特性清单整理自官方仓库 README 与 .env.example 配置模板（来源：官方仓库，查询日期 2026-10-23）：

  1. OpenAI 兼容 API：支持 /v1/chat/completions（流式与非流式）与 /v1/models，主流 OpenAI SDK 客户端可直接对接；
  2. 函数调用三模式：auto / native / emulated，支持失败自动回退（FUNCTION_CALLING_NATIVE_FALLBACK）、UI 操作超时与重试次数可调；
  3. 认证轮转与 Cookie 刷新：多认证配置文件（active/saved/emergency），支持配额软/硬阈值触发轮转（QUOTA_SOFT_LIMIT/QUOTA_HARD_LIMIT）、周期性 Cookie 刷新（默认每 1800 秒）、按请求数保存、关停时保存；
  4. 思考预算（Thinking Budget）：支持 Gemini 思考模型的预算开关与档位预设（low/medium/high 对应 token 预算），支持 Gemini 3 Pro 思考等级；
  5. 多种启动模式：--debug（浏览器可见，交互式登录）、--headless（无头，服务器常驻）、--virtual-display（Xvfb 虚拟显示）、直接启动（DIRECT_LAUNCH）；
  6. 内置 Web UI：FastAPI 同源的设置页，提供状态检查、日志查看（WS /ws/logs）、密钥管理、代理配置、端口管理等管理接口；
  7. 请求队列控制：/v1/queue 查看排队、/v1/cancel/{req_id} 取消请求；
  8. API Key 鉴权：Authorization: Bearer <token> 或 X-API-Key 两种请求头，密钥经管理接口增删查；
  9. Docker 部署：官方提供 docker/docker-compose.yml 与 Dockerfile，支持内存限制、健康检查与认证目录挂载；
  10. 多实例管理器：scripts/multi-instance-manager/ 提供 Docker 隔离的多实例拉起脚本（来源：Releases v4.1.1_py 更新记录）。

五、快速开始（最小可用示例）

以下步骤摘自官方仓库 README 快速开始章节（来源：官方仓库 README，查询日期 2026-10-23；完整安装步骤与环境要求见本专栏后续部署篇）：

5.1 安装

git clone https://github.com/CJackHwang/AIstudioProxyAPI.git
cd AIstudioProxyAPI
poetry install --with dev

5.2 配置环境

cp .env.example .env

官方建议先确认 PORT、STREAM_PORT、UNIFIED_PROXY_CONFIG、LAUNCH_MODE、FUNCTION_CALLING_MODE 五个配置项。

5.3 启动

# 首次建议 debug，完成登录并保存 auth
poetry run python launch_camoufox.py --debug

# 日常建议 headless
poetry run python launch_camoufox.py --headless

5.4 调用验证

# 健康检查
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":"你好"}]}'

浏览器访问 http://127.0.0.1:2048/ 可使用内置 Web UI 管理面板。

⚠️ 注意：本项目需要你自备 Google 账号并在首次启动时完成 AI Studio 网页登录（保存认证文件后方可 headless 运行）。部署形态、依赖与实测排障细节请见《AIstudioProxyAPI 安装指南》。

六、适用场景与限制

6.1 适用场景

  1. 个人免费额度复用：已有 Google 账号，希望在自建应用（Open WebUI、自研 Bot 等）中复用 AI Studio 网页版的 Gemini 模型能力，而不直接采购官方 API 计费；
  2. 多客户端统一接入：将网页版封装为标准 OpenAI 接口，供聊天客户端、IDE 插件、自动化脚本等统一调用；
  3. 需要 tool call 的集成：依赖 OpenAI tools 协议的 Agent 框架，可借助其三模式函数调用桥接到 Gemini；
  4. 多账号轮转：准备多组认证文件，通过配额阈值自动轮转，缓解单账号限额（来源：README 认证轮转特性）。

6.2 已知限制

  1. 依赖 Google 账号与网页版稳定性：无账号无法使用；AI Studio 网页改版可能导致选择器失效，需跟进项目更新（Releases 中大量更新为 selector 修复，来源：Releases 记录，查询日期 2026-10-23）；
  2. 并发能力有限：浏览器自动化单页面操作，请求经队列串行处理，不适合高并发生产场景（架构为单浏览器实例 + 请求队列，来源：README 架构与 api-usage 文档）；
  3. 合规与风控风险：网页逆向使用方式不在 Google 官方 API 服务条款保障范围内，存在账号被风控的可能；官方通过反指纹 Camoufox、配额硬阈值 Kill Signal（QUOTA_HARD_LIMIT 默认 950000）等手段降低风险，但不能消除；
  4. 资源占用：需运行完整 Firefox 浏览器实例，官方要求内存 ≥2GB（推荐 4GB）；
  5. 版本命名特殊：Python 版本 tag 形如 v4.1.2_py，选版本时注意 _py 后缀（历史上另有非 _py 后缀的旧版本线）。

七、同类选型对比

「网页转 API / 免费大模型接入」方向的同类方案对比（数据来源：GitHub 仓库页与 shields.io 徽章，查询日期 2026-10-23）：

维度AIstudioProxyAPIgpt4freeWebAI-to-APIAIStudioToAPIgemini-openai-proxy
GitHub Stars2.5k67k1.4k1.8k722
开源许可AGPLv3GPL-3.0（部分 Provider 另有限制）未固定（以仓库为准）以仓库为准MIT
接入目标Google AI Studio 网页版多 Provider 聚合（含逆向站点）多家网页版（Gemini 等）AI Studio 网页版（同类实现）Gemini 官方 API
实现方式Camoufox+Playwright 浏览器自动化Python Provider 逆向请求浏览器自动化/接口逆向浏览器自动化官方 API 转 OpenAI 格式
认证要求Google 账号登录 + Cookie 文件部分无需登录/部分需依 Provider 而定Google 账号官方 API Key（计费）
OpenAI 兼容完整（chat/completions+models）完整部分端点完整完整
函数调用三模式（auto/native/emulated）有限弱有（同类实现）完整（透传官方）
流式输出支持（独立流代理端口）支持部分支持支持支持
稳定性来源网页选择器需随 AI Studio 改版跟进Provider 失效率高、质量参差依上游而定同左最稳定（官方契约）
合规风险中（网页逆向）高（多站点逆向）中中低（官方 API）
适用画像想稳定复用 AI Studio + tool call泛体验、多模型薅羊毛多家网页版聚合AI Studio 同类备选有预算、要稳定

选型解读：

  • 若目标是「稳定复用 Google AI Studio、需要函数调用与流式、可接受自备 Google 账号」→ AIstudioProxyAPI 是当前维护活跃（持续修 selector）、工程化程度高（Poetry + 测试 + CI/CD + 内置管理 UI + Docker 编排）的选择；
  • 若只想「泛泛体验多种免费模型、不在乎稳定性与合规」→ gpt4free 覆盖面更广，但 Provider 失效率高；
  • 若「有预算、追求生产稳定与合规」→ 直接用 Gemini 官方 API（gemini-openai-proxy 做格式适配），无风控与改版风险；
  • 同为 AI Studio 网页转 API 的 AIStudioToAPI 可作备选，AIstudioProxyAPI 的差异化在于认证轮转/Cookie 刷新体系、函数调用三模式与内置 Web UI 管理面板。

社区活跃度与版本节奏（查询日期 2026-10-23）：

  • 版本节奏：v4.x 线迭代较快，2026-04 内连续发布 v4.0.2_py → v4.1.2_py，另有 main 分支每日 Nightly 自动构建（预发布通道）；
  • 维护方式：主仓 CI 含 PR 检查、Release、Upstream Sync 工作流；贡献者含架构重构、页面操作优化、流式优化等多名协作者；
  • 风险提示：项目自述「课余时间有限，随缘更新」，网页改版窗口期可能出现短时不可用，选型时应接受「跟进上游更新」的运维成本。

八、参考链接

  1. 官方仓库：https://github.com/CJackHwang/AIstudioProxyAPI （查询日期 2026-10-23）
  2. Releases 页：https://github.com/CJackHwang/AIstudioProxyAPI/releases （查询日期 2026-10-23）
  3. 官方文档目录：https://github.com/CJackHwang/AIstudioProxyAPI/tree/main/docs （查询日期 2026-10-23）
  4. 配置参考：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/configuration-reference.md （查询日期 2026-10-23）
  5. API 使用说明：https://github.com/CJackHwang/AIstudioProxyAPI/blob/main/docs/api-usage.md （查询日期 2026-10-23）
  6. 同类项目（对比数据来源，查询日期 2026-10-23）：gpt4free https://github.com/xtekky/gpt4free ；WebAI-to-API https://github.com/Amm1rr/WebAI-to-API ；AIStudioToAPI https://github.com/iBUHub/AIStudioToAPI ；gemini-openai-proxy https://github.com/zhu327/gemini-openai-proxy
  7. 本专栏后续篇目：《AIstudioProxyAPI 安装指南》《AIstudioProxyAPI 配置参数详解》《AIstudioProxyAPI 常用 CLI 命令与工具详解》