aistudio-api

Google AI Studio 反向代理服务，将 Web 端 AI Studio 转换为标准 Google Gemini API 协议接口。

English Documentation

---

目录

• 核心特性
• 技术架构与文档
• 快速开始
  • Android (Termux)
  • Windows
  • Linux / macOS
  • Docker 部署
• 配置与环境变量
• API 调用示例
  • cURL 调用
  • Python SDK (google-genai)
  • 工具调用 (Function Calling)
• Web 管理控制台
• 开发与测试
• 开源协议

---

核心特性

功能模块	说明
Gemini 协议兼容	支持 /v1beta/... 接口规范，包括 Thinking 思维链、多模态、Function Calling 工具调用及图片生成
动态模型发现	自动向上游同步可用模型列表，支持 gemini-3.7-flash、gemini-3.8-flash 等最新模型
多账号自动轮换	支持多账号管理与故障自动切换，按模型独立记录 429 配额，每日美西午夜自动重置
运行状态持久化	模型调用量、Token 消耗统计 (stats.json) 以及账号 429 限额与冷却状态 (rotator_state.json) 自动落盘，容器/服务重启不丢失状态
下游参数容错与丢弃	支持配置 drop_unsupported_params 自动过滤下游传入的非标准安全分类（如 HARM_CATEGORY_CIVIC_INTEGRITY）与不兼容工具，避免 400 阻断
批量子账号探活	导入单个包含多个 Google 身份的 Cookie 后，自动递归探活子账号（u/0, u/1...）并分别建档
内置搜索与工具	支持 Google Search 联网搜索、Google Maps、代码执行沙箱等官方扩展能力
轻量 CDP 驱动	基于纯 Python 异步 WebSocket 直连 Chrome DevTools Protocol，无需 Node.js、Playwright 或 Selenium
Web 管理面板	提供 Web 管理控制台，支持账号管理（文本与 JSON 批量导入）、调用量监控、在线编辑与热重载 config.yaml
Android 伴侣端	配套 Android 原生应用（android/），采用 Jetpack Compose 构建，支持多 Profile 隔离登录、Bitwarden 自动填充与一键导出凭据包

Note

内存占用参考：纯 Python 后端服务常驻内存约 35 - 45 MB；拉起单实例受控 Chromium 后总物理内存 (PSS) 约 350 - 450 MB（宿主 Linux 下约 250 - 350 MB）。Android Termux 环境建议空闲 RAM ≥ 1 GB。

技术架构与文档

┌────────────────────────────────────────────────────────┐
│               Client (cURL / Python SDK)               │
└───────────────────────────┬────────────────────────────┘
                            │ /v1beta/models/...
┌───────────────────────────▼────────────────────────────┐
│              FastAPI HTTP Gateway (Port 8080)          │
├───────────────────────────┬────────────────────────────┤
│    Account Rotator        │    Chat & Wire Codec       │
│  (Sticky & 429 Isolation) │ (Protobuf-JSON & BotGuard) │
└───────────────────────────┼────────────────────────────┘
                            │ CDP WebSocket
┌───────────────────────────▼────────────────────────────┐
│      Controlled Chromium Instance (CloakBrowser)       │
│       In-Page XHR Replay (withCredentials=true)        │
└───────────────────────────┬────────────────────────────┘
                            │ HTTPS / RPC
┌───────────────────────────▼────────────────────────────┐
│         Google AI Studio (alkalimakersuite-pa)         │
└────────────────────────────────────────────────────────┘

详细的设计与协议分析文档：

• 系统架构设计 (ARCHITECTURE.md)：分层架构、请求生命周期、Wire Codec 编解码与并发控制模型。
• Wire 协议逆向技术规范 (WIRE_SPECIFICATION.md)：Protobuf-JSON 数组映射、字段索引、多模态 Part 结构与 Schema 编码。
• BotGuard 验证链路机制 (BOTGUARD_VERIFICATION_CHAIN.md)：WAA 挑战握手、Wasm 动态签名、内容哈希与服务端校验流程。
• 智能体与协作规范 (AGENT.md)：类型系统要求、代码质量检查与开发指南。

---

快速开始

Android (Termux)

Tip

下载提示：请务必从 F-Droid 或 GitHub Releases 安装 Termux。切勿使用 Google Play 商店版本（Play 商店版本已停止维护，更新环境会报错）。

打开 Termux，依次复制执行以下命令：

# 步骤 1：更新 Termux 基础环境并安装 git
pkg update -y && pkg install -y git

# 步骤 2：克隆代码仓库并进入目录
git clone https://github.com/DeconstructedCube/aistudio-api.git
cd aistudio-api

# 步骤 3：初始化依赖环境（自动配置手机专属加速源，无需本地编译）
bash scripts/setup-env.sh
uv sync

# 步骤 4：安装并配置受控浏览器（仅首次需要，耗时约 1~2 分钟）
bash scripts/setup-browser.sh

# 步骤 5：启动服务
uv run python main.py server --port 8080

启动成功后：

1. 打开手机自带浏览器，访问 http://localhost:8080 即可进入 Web 管理控制台；
2. 点击 “账号管理” 页面，粘贴你的 Google 账号 Cookie 或导入凭据包即可开始调用；
3. 后台保活提示：下拉手机通知栏，点击 Termux 通知项上的 Acquire Wakelock，并在手机系统设置中为 Termux 开启“无限制后台运行/电池优化白名单”，防止锁屏休眠被系统误杀。

---

Windows

前置要求：电脑已安装 Python 3.11+（安装时勾选 Add python.exe to PATH）。

打开 PowerShell 或终端，依次执行：

# 步骤 1：安装 uv 包管理工具
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 步骤 2：克隆代码仓库并进入目录
git clone https://github.com/DeconstructedCube/aistudio-api.git
cd aistudio-api

# 步骤 3：同步安装项目依赖
uv sync

# 步骤 4：安装 CloakBrowser 浏览器（仅首次需要）
scripts\install-browser.bat

# 步骤 5：启动服务
uv run python main.py server --port 8080

服务启动后，浏览器访问 http://localhost:8080 进入管理控制台。

---

Linux / macOS

打开终端，依次执行：

# 步骤 1：安装 uv 包管理工具
curl -LsSf https://astral.sh/uv/install.sh | sh

# 步骤 2：克隆代码仓库并进入目录
git clone https://github.com/DeconstructedCube/aistudio-api.git
cd aistudio-api

# 步骤 3：同步安装项目依赖
uv sync

# 步骤 4：安装 CloakBrowser 浏览器（仅首次需要）
bash scripts/setup-browser.sh

# 步骤 5：启动服务
uv run python3 main.py server --port 8080

服务启动后，浏览器访问 http://localhost:8080 进入管理控制台。

---

Docker 部署

镜像已内置 CloakBrowser 运行时，支持开箱即用：

docker run -d \
  --name aistudio-api \
  --restart unless-stopped \
  -p 8080:8080 \
  -v aistudio-api-data:/app/data \
  ghcr.io/deconstructedcube/aistudio-api:latest

使用 Docker Compose 启动：

docker compose up -d

启动后访问 http://localhost:8080（或服务器 IP 端口）进入管理控制台。

---

配置与环境变量

服务启动后可访问 http://localhost:8080 进入 Web 控制台完成可视化管理。

环境变量支持

变量名	类型	默认值	说明
AISTUDIO_PORT	int	8080	API 服务监听端口
AISTUDIO_WEB_PASSWORD	string	""	Web 控制台访问密码（亦可设置 AISTUDIO_ADMIN_PASSWORD）
AISTUDIO_PROXY	string	""	出口代理地址，支持 http://、https:// 或 socks5://
AISTUDIO_DATA_DIR	string	data/	主数据持久化根目录（Docker 下为 /app/data）
AISTUDIO_ACCOUNTS_DIR	string	data/accounts	账号持久化凭据目录
AISTUDIO_STATS_FILE	string	data/stats.json	模型调用与 Token 使用量统计持久化文件
AISTUDIO_ROTATOR_STATE_FILE	string	data/rotator_state.json	账号调度与 429 冷却状态持久化文件
AISTUDIO_CONFIG_FILE	string	config.yaml	模型规则与默认工具配置文件路径
AISTUDIO_PERSIST_STATS	bool	true	是否持久化模型调用与 Token 统计（1=开启，0=关闭）
AISTUDIO_PERSIST_ROTATOR	bool	true	是否持久化账号 429 冷却与调度状态（1=开启，0=关闭）
AISTUDIO_BROWSER_EXECUTABLE	string	自动探测	自定义 CloakBrowser 可执行文件路径（Docker 内为 /opt/cloakbrowser/chrome）
AISTUDIO_BROWSER_PORT	int	9222	Chromium 远程调试端口 (CDP)
AISTUDIO_BROWSER_HEADLESS	bool	true	是否以无头模式运行 Chromium
AISTUDIO_PROOT_NAME	string	aistudio-api	Termux 环境下专用的 proot-distro 容器名称
AISTUDIO_DEFAULT_TEXT_MODEL	string	gemini-3.7-flash	默认文本模型
AISTUDIO_DEFAULT_IMAGE_MODEL	string	gemini-3.1-flash-image-preview	默认图像生成模型
AISTUDIO_TIMEZONE	string	自动探测	受控浏览器指纹与 Wire 协议交互时区（默认 America/Los_Angeles）
AISTUDIO_LOCALE	string	en-US	受控浏览器区域语言
AISTUDIO_DUMP_REQUESTS	bool	false	是否在终端转储每次 API 交互报文详情（支持 DEBUG=1 触发）
AISTUDIO_DUMP_FILE	bool	false	是否将请求与响应报文详情落盘保存
AISTUDIO_DUMP_DIR	string	dumps/	报文转储保存目录

---

API 调用示例

支持以下鉴权方式：

• Query 参数：?key=YOUR_API_KEY
• 请求头：x-goog-api-key: YOUR_API_KEY、x-api-key: YOUR_API_KEY 或 Authorization: Bearer YOUR_API_KEY

cURL 调用

1. 查询模型列表

curl http://localhost:8080/v1beta/models \
  -H "x-goog-api-key: your-api-key"

2. 文本生成 (Non-streaming)

curl http://localhost:8080/v1beta/models/gemini-3.7-flash:generateContent \
  -H "x-goog-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "用简短的一句话介绍量子计算。"}]
      }
    ]
  }'

3. 流式生成 (Server-Sent Events)

curl http://localhost:8080/v1beta/models/gemini-3.7-flash:streamGenerateContent?alt=sse \
  -H "x-goog-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "介绍一下 Python 协程的工作原理。"}]
      }
    ]
  }'

---

Python SDK (google-genai)

使用 Google 官方 google-genai SDK 直连本代理服务：

from google import genai

client = genai.Client(
    api_key="your-api-key",
    http_options={
        "api_version": "v1beta",
        "base_url": "http://localhost:8080",
    },
)

# 1. 流式响应
response = client.models.generate_content_stream(
    model="gemini-3.7-flash",
    contents="解释一下什么是反应式编程？",
)
for chunk in response:
    print(chunk.text, end="", flush=True)

# 2. 非流式响应
result = client.models.generate_content(
    model="gemini-3.7-flash",
    contents="用 Python 写一个快速排序算法。",
)
print(result.text)

---

工具调用 (Function Calling)

from google import genai
from google.genai import types

client = genai.Client(
    api_key="your-api-key",
    http_options={
        "api_version": "v1beta",
        "base_url": "http://localhost:8080",
    },
)

# 定义工具声明
weather_tool = types.Tool(
    function_declarations=[
        types.FunctionDeclaration(
            name="get_current_weather",
            description="获取指定地点的实时天气状况",
            parameters=types.Schema(
                type="OBJECT",
                properties={
                    "location": types.Schema(
                        type="STRING",
                        description="城市或地区名称，例如 'Beijing' 或 'Tokyo'",
                    ),
                    "unit": types.Schema(
                        type="STRING",
                        enum=["celsius", "fahrenheit"],
                        description="温度单位",
                    ),
                },
                required=["location"],
            ),
        )
    ]
)

response = client.models.generate_content(
    model="gemini-3.7-flash",
    contents="今天杭州天气怎么样？",
    config=types.GenerateContentConfig(tools=[weather_tool]),
)

if response.function_calls:
    for call in response.function_calls:
        print(f"触发工具调用: {call.name}")
        print(f"调用参数: {call.args}")

---

Web 管理控制台

系统内置静态打包的 Web 前端管理控制台（访问 http://localhost:8080）：

• 仪表盘 (Dashboard)：实时展示服务健康状况、各模型请求量、成功率及 429 冷却指标。
• 账号管理 (Accounts)：支持 Cookie 单条与凭据包批量导入、自动探测多账号、手动切换当前活跃账号或重置冷却状态。
• 系统设置 (Settings)：在线编辑 config.yaml（支持配置 profiles 与 models 默认规则），保存后服务端即时热重载。
• 访问鉴权：设置环境变量 AISTUDIO_WEB_PASSWORD 后自动开启登录鉴权守卫。

---

开发与测试

前端源码位于 web/，采用 Vue 3 + TypeScript + Vite + Tailwind CSS：

# 启动前端开发调试服务
cd web
bun install
bun run dev          # 启动开发服务（localhost:3000，代理至 8080）
bun run type-check   # 执行 TypeScript 类型校验
bun run lint         # 执行 ESLint 代码规范检查
bun run build        # 生产构建，产物输出至 src/aistudio_api/static

Python 端质量检查与测试：

# 执行代码风格与 Lint 检查
uv run ruff check .
# 执行静态类型检查
bun x pyright

# 执行单元测试套件
uv run pytest

Android 伴侣端代码质量检查：

# 执行 Kotlin 代码规范检查 (已配置于 ~/.zshrc)
ktlint "android/app/src/main/java/**/*.kt"

---

开源协议

本项目基于 MIT License 许可协议开源。