AI Studio 代理 API

将 Google AI Studio 网页界面转换为 OpenAI 兼容 API 的代理服务。通过 Camoufox + Playwright 自动化，提供稳定可控的 API 访问。

---

主要特性

• OpenAI 兼容 API：支持 /v1/chat/completions、/v1/models
• 函数调用三模式：auto / native / emulated，支持失败回退
• 认证轮转与 Cookie 刷新：支持 profile 自动轮转、周期刷新与关停保存
• 启动链路完整：CLI 启动器、内置 Web UI、桌面 GUI 启动器
• 现代化前端：内置设置页、状态检查与日志能力
• CI/CD 工作流：PR 检查、Release、Upstream Sync

系统要求

组件	要求	推荐
Python	>=3.9, <4.0	3.10+ / 3.11+
依赖管理	Poetry	最新版本
Node.js	前端构建需要	LTS
内存	>=2GB	>=4GB

---

🚀 快速开始

1. 克隆并安装

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

2. 配置环境

cp .env.example .env

建议先确认：PORT、STREAM_PORT、UNIFIED_PROXY_CONFIG、LAUNCH_MODE、FUNCTION_CALLING_MODE。

3. 首次认证并启动

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

# 日常建议 headless
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":"你好"}]}'

访问 http://127.0.0.1:2048/ 使用内置 Web UI。

---

系统架构

graph TD
    subgraph "用户端"
        User["用户"]
        WebUI["Web UI"]
        APIClient["API 客户端"]
    end

    subgraph "启动与配置"
        Launcher["launch_camoufox.py"]
        Env[".env 配置"]
    end

    subgraph "核心服务"
        FastAPI["FastAPI 应用<br/>api_utils/"]
        BrowserOps["页面控制与自动化<br/>browser_utils/"]
        StreamProxy["流式代理<br/>stream/"]
    end

    subgraph "外部依赖"
        Camoufox["Camoufox 浏览器"]
        AIStudio["Google AI Studio"]
    end

    User --> Launcher
    Launcher --> Env
    WebUI --> FastAPI
    APIClient --> FastAPI
    FastAPI --> BrowserOps
    FastAPI --> StreamProxy
    BrowserOps --> Camoufox --> AIStudio
    StreamProxy --> AIStudio

---

运行模式

命令	说明	场景
python launch_camoufox.py --headless	无头模式	日常使用、服务器
python launch_camoufox.py --debug	调试模式	首次认证、故障排查
python launch_camoufox.py --virtual-display	虚拟显示	Linux 无 GUI 环境

---

⚙️ 配置

项目使用 .env 统一配置管理：

cp .env.example .env

核心配置示例：

配置	默认值	说明
PORT	2048	主 API 端口
STREAM_PORT	3120	流式代理端口（0 关闭）
UNIFIED_PROXY_CONFIG	空	HTTP/HTTPS 代理
AUTO_ROTATE_AUTH_PROFILE	true	认证自动轮转
FUNCTION_CALLING_MODE	auto	函数调用模式

详细项见：配置参考

说明：配置默认值以 .env.example 为准；少数配置存在代码兜底默认值，详见配置参考中的说明。

---

📚 文档

• 文档总览
• 快速开始
• 部署与运维指南
• API 使用说明
• 函数调用模式
• 认证轮转与 Cookie 刷新
• 排障指南
• 开发、测试与发布
• 多实例 Docker 管理器

---

客户端配置示例

以 Open WebUI 为例：

1. 进入设置 -> 连接
2. API Base URL 填 http://127.0.0.1:2048/v1
3. 若你未配置 API Keys，可留空或填任意字符；若已配置，请填写有效 Key
4. 保存后即可对话

---

开发检查

poetry run ruff check .
poetry run pyright
poetry run pytest

前端构建：

cd static/frontend
npm ci
npm run build

---

致谢

• 项目发起与主要开发: @CJackHwang
• 核心维护（架构重构、测试体系）: @NikkeTryHard
• 功能完善、页面操作优化: @ayuayue
• 实时流式功能优化: @luispater
• 项目重构贡献: @yattin（Holt）
• 下游维护分支致谢作者: @MasuRii
• 社区支持: Linux.do 社区

License

AGPLv3

支持作者

如果本项目对你有帮助，欢迎支持作者持续开发：

AIstudioProxyAPI 快速上手指南

本指南帮助中国开发者快速部署并使用 AIstudioProxyAPI，将 Google AI Studio 网页界面转换为兼容 OpenAI 格式的 API 服务。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python：版本 >= 3.9 (推荐 3.10 或 3.11)
• 依赖管理工具：Poetry (必须安装最新版)
• Node.js：LTS 版本 (用于前端构建，若仅运行后端可忽略，但建议安装)
• 内存：至少 2GB (推荐 4GB 以上)

提示：国内用户安装 Poetry 或 Node.js 时，如遇网络缓慢，建议配置国内镜像源或使用代理加速。

2. 安装步骤

第一步：克隆项目

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

第二步：安装依赖

使用 Poetry 安装项目所需依赖（包含开发依赖以确保完整性）：

poetry install --with dev

国内加速提示：若 poetry install 下载缓慢，可临时配置 PyPI 国内源：

poetry config pypi-url.pypi https://pypi.tuna.tsinghua.edu.cn/simple/

第三步：配置环境变量

复制示例配置文件并生成 .env 文件：

cp .env.example .env

注：大多数情况下可直接使用默认配置启动，如需修改端口或代理，请编辑 .env 文件。

3. 基本使用

首次启动与认证

首次运行需要打开浏览器进行 Google 账号登录以获取授权。请使用 --debug 模式启动：

poetry run python launch_camoufox.py --debug

1. 脚本会自动启动浏览器窗口。
2. 在弹出的浏览器中登录您的 Google 账号并进入 AI Studio。
3. 登录成功后，程序会自动保存认证信息（Cookie/Profile）。
4. 按 Ctrl+C 停止当前进程。

日常运行

完成首次认证后，建议使用无头模式（后台运行）启动服务：

poetry run python launch_camoufox.py --headless

服务默认启动在 http://127.0.0.1:2048。

快速测试

使用 curl 命令验证服务是否正常运行：

1. 健康检查

curl http://127.0.0.1:2048/health

2. 获取模型列表

curl http://127.0.0.1:2048/v1/models

3. 发送聊天请求

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":"你好"}]}'

接入客户端

您可以将此服务作为 OpenAI 兼容接口接入任意支持该协议的客户端（如 Open WebUI, LangChain 等）：

• API Base URL: http://127.0.0.1:2048/v1
• API Key: 可留空或填写任意字符（除非您在 .env 中强制开启了密钥验证）
• 模型名称: 填写支持的 Gemini 模型，例如 gemini-2.5-pro

您也可以通过浏览器访问 http://127.0.0.1:2048/ 使用内置的 Web UI 进行调试和状态查看。