README.md

metadata

title: AI Studio API
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 8889
pinned: false

aistudio-api

Google AI Studio 反向代理服务。提供原生 Gemini API 接口。

English

特性

• 兼容原生 Gemini API 协议
• 动态获取可用模型列表
• 多账号 Cookie 轮询
• 支持官方工具调用，包含 Google Search、Google Maps、代码执行沙箱
• 支持 Function Calling
• 支持图像生成
• 基于 CDP 协议的轻量化无头浏览器环境

💡 内存占用参考（实测）：纯 Python 服务部分约 3085 MB；启用内置 CloakBrowser (Chromium) 后整体常驻约 500650 MB。在 Termux 上请确保设备剩余可用 RAM ≥ 1 GB。

安装部署

前置依赖

• Python 3.10 以上版本
• Chromium 浏览器及其运行库

Linux macOS Windows 环境

所有平台统一使用 uv 作为依赖与虚拟环境管理器（与本仓库的 uv.lock / pyproject.toml 一致）。安装 uv 后，从源码同步即可获得受版本锁保护的可运行虚拟环境：

git clone https://github.com/DeconstructedCube/aistudio-api.git
cd aistudio-api
uv sync
uv run python3 main.py server --port 8080

请务必使用 uv sync 安装依赖，不要使用 pip install -r requirements.txt，否则会导致 aarch64 预编译包版本不匹配。

Android Termux 环境

在 Termux 上运行需要借助 proot-distro 提供必要的 Linux 运行环境。请按顺序执行以下命令进行完整安装与启动：

pkg update
pkg install -y python git uv proot-distro
git clone https://github.com/DeconstructedCube/aistudio-api.git
cd aistudio-api
uv sync
bash scripts/install_termux_prereqs.sh --project-root "$PWD"
uv run python3 main.py server --port 8080

首次运行 install_termux_prereqs.sh 时会自动配置一个名为 aistudio-api 的专属容器并下载浏览器，过程视网络情况可能需要几分钟。 常见问题排查（如端口冲突、容器报错等）请查阅项目 Issues 或讨论区。

Docker 环境

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

通过 docker compose 启动：

docker compose up -d

配置管理

服务启动后访问 http://localhost:8080 进入 Web 控制面板管理账号 Cookie 与轮询策略。

主要环境变量：

• AISTUDIO_PORT: 服务监听端口，默认 8080
• AISTUDIO_API_KEYS: 鉴权密钥，多个密钥用逗号分隔
• AISTUDIO_PROXY: HTTP 或 SOCKS5 代理地址
• AISTUDIO_BROWSER_EXECUTABLE: Chromium 可执行文件绝对路径
• AISTUDIO_ACCOUNT_ROTATION_MODE: 轮询模式，支持 round_robin、lru、least_rl

模型默认行为由根目录 config.yaml 控制。

接口调用

支持的鉴权方式：

• URL 参数 ?key=YOUR_API_KEY
• 请求头 x-goog-api-key: YOUR_API_KEY
• 请求头 x-api-key: YOUR_API_KEY
• 请求头 Authorization: Bearer YOUR_API_KEY

基础路由

获取模型列表：

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

文本生成：

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

流式输出需添加 ?alt=sse 参数并调用 streamGenerateContent 路由。

Python SDK

安装依赖：

pip install google-genai

调用示例：

from google import genai

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

response = client.models.generate_content(
    model="gemini-3.7-flash",
    contents="Hello"
)
print(response.text)

许可证

MIT License