AIstudioProxyAPI is a self-hosted Python middleware that turns the Google AI Studio web interface into an OpenAI-compatible API endpoint, for developers who want to call Gemini models through standard OpenAI clients without an official API key.

What it is

AIstudioProxyAPI is a FastAPI application that sits between ordinary OpenAI-format clients and Google AI Studio. It receives requests on standard OpenAI routes, drives a Camoufox browser session via Playwright to submit those requests to the Google AI Studio chat page, and then returns the results in the same OpenAI response format. The project ships with a built-in debugging Web UI, a CLI launcher, a desktop GUI launcher, and a streaming proxy layer, and it is written in Python under the AGPL-3.0 licence.

The concrete problem it solves is access: it gives applications that only know how to speak the OpenAI API a way to reach Google AI Studio's models when no direct API integration exists. Instead of each client reimplementing browser automation and session handling, the project centralises it behind /v1/chat/completions and /v1/models, so any OpenAI-compatible tool can point at a single base URL. It also manages the operational side of that arrangement — authentication profiles, cookie refresh, and function-call translation — which would otherwise have to be handled ad hoc.

Key capabilities

• Exposes OpenAI-compatible endpoints /v1/chat/completions and /v1/models on the main API port (PORT, default 2048), returning responses in OpenAI format.
• Supports three function-calling modes — auto, native, and emulated — with fallback behaviour when a mode fails, controlled by FUNCTION_CALLING_MODE.
• Rotates authentication profiles and refreshes cookies automatically, with periodic refresh and saving on shutdown, governed by AUTO_ROTATE_AUTH_PROFILE.
• Offers a complete launch chain: the launch_camoufox.py CLI launcher with --headless, --debug, and --virtual-display modes, a built-in Web UI, and a desktop GUI launcher.
• Runs a separate streaming proxy on STREAM_PORT (default 3120, set to 0 to disable) for real-time responses.
• Centralises configuration in a single .env file, including PORT, STREAM_PORT, UNIFIED_PROXY_CONFIG for HTTP/HTTPS proxying, and LAUNCH_MODE.
• Provides a built-in Web UI with a settings page, status checks, and log viewing, plus CI/CD workflows covering PR checks, releases, and upstream sync.

Who uses it and how

• Developers wiring up OpenAI-compatible front ends: the README's worked example points Open WebUI's settings at http://127.0.0.1:2048/v1, leaving the API key blank when none is configured.
• Operators running it on a server in --headless mode for daily use, or with --virtual-display on Linux hosts without a GUI, with a minimum of 2GB RAM and 4GB recommended.
• People performing first-time authentication interactively with launch_camoufox.py --debug, completing the Google login and saving auth before switching to headless operation.
• Teams running several instances side by side through the multi-instance Docker manager in scripts/multi-instance-manager/.
• Contributors running the documented checks — poetry run ruff check ., poetry run pyright, and poetry run pytest — plus a frontend build in static/frontend.

Getting started

Clone the repository, run poetry install --with dev, copy .env.example to .env, and then start with poetry run python launch_camoufox.py --debug to authenticate before switching to --headless for daily use.

How it compares

Among the tools named in its own documentation it stands alone in this registry: FastAPI, Playwright, and Camoufox are the pieces it is built from rather than alternatives to it, and Open WebUI appears only as an example client that connects to it. Its role is specifically as a gateway in front of Google AI Studio for OpenAI-format consumers.

When to use it — and when not to

A self-hoster must operate a running Camoufox browser session, maintain valid Google AI Studio login cookies, and manage an .env configuration file on a machine meeting the 2GB RAM floor. It is a poor fit for anyone needing a formally supported API contract, since the project relays requests through a web interface that Google can change at any time, and the browser automation layer is inherently exposed to that breakage. The licence is AGPL-3.0, which obliges distributed modifications to be released, and with 24 open issues the surface of known unresolved problems is worth checking before committing to it.

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

cp .env.example .env

# 首次建议 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":"你好"}]}'

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

cp .env.example .env

poetry run ruff check .
poetry run pyright
poetry run pytest

cd static/frontend
npm ci
npm run build