Repository files navigation

This is a Python-based proxy server that converts Google AI Studio's web interface into an OpenAI-compatible API. Through Camoufox (anti-fingerprinting Firefox) and Playwright automation, it provides stable API access.

This fork is the primary English version of the original project.

This project is generously sponsored by ZMTO with server support. Visit their website:https://zmto.com/

The birth and development of this project cannot be separated from the generous support and wisdom contributions of the following individuals, organizations, and communities:

• Project initiation and main development: @CJackHwang (https://github.com/CJackHwang)
• Feature enhancement and page operation optimization ideas: @ayuayue (https://github.com/ayuayue)
• Real-time streaming functionality optimization and improvement: @luispater (https://github.com/luispater)
• 3400+ line main file project refactoring great contribution: @yattin (Holt) (https://github.com/yattin)
• High-quality project maintenance in later stages: @Louie (https://github.com/NikkeTryHard)
• English version maintainer: @MasuRii (https://github.com/MasuRii)
• Community support and inspiration: Special thanks to theLinux.do Community members for their enthusiastic discussions, valuable suggestions, and problem feedback - your participation is an important driving force for the project's progress.

At the same time, we sincerely thank every friend who has silently contributed to this project through submitting Issues, providing suggestions, sharing usage experiences, contributing code fixes, and other ways. It is your joint efforts that make this project better!

This is the currently maintained Python version.

• Python: >=3.9, <4.0 (recommend 3.10+ for best performance, Docker environment uses 3.10)
• Dependency Management:Poetry (modern Python dependency management tool, replacement for traditional requirements.txt)
• Type Checking:Pyright (optional, used for type checking and IDE support during development)
• Operating System: Windows, macOS, Linux (full cross-platform support, Docker deployment supports x86_64 and ARM64)
• Memory: Recommend 2GB+ available memory (browser automation required)
• Network: Stable internet connection to access Google AI Studio (proxy configuration supported)

• OpenAI Compatible API: Supports/v1/chat/completions endpoint, fully compatible with OpenAI clients and third-party tools
• Native Function Calling: Full OpenAI-compatibletools/tool_calls support via AI Studio's built-in function calling UI, with automatic fallback to text-based emulation 🆕
• Three-Layer Streaming Response Mechanism: Integrated streaming proxy → external Helper service → Playwright page interaction multiple guarantees
• Smart Model Switching: Dynamically switch models in AI Studio through themodel field in API requests
• Complete Parameter Control: Supports all major parameters liketemperature,max_output_tokens,top_p,stop,reasoning_effort
• Anti-Fingerprinting Detection: Uses Camoufox browser to reduce the risk of being detected as automated scripts
• Script Injection Feature v3.0: Uses Playwright native network interception, supports Tampermonkey script dynamic mounting, 100% reliable
• Modern Web UI: Built-in testing interface, supports real-time chat, status monitoring, hierarchical API key management
• Graphical Interface Launcher: Provides feature-rich GUI launcher, simplifying configuration and process management
• Flexible Authentication System: Supports optional API key authentication, fully compatible with OpenAI standard Bearer token format
• Modular Architecture: Clear modular separation design, api_utils/, browser_utils/, config/ and other independent modules
• Unified Configuration Management: Based on.env file unified configuration, supports environment variable overrides, Docker compatible
• Auth profile smart rotation: Automatically rotates authentication profiles to avoid rate limits and improve stability.
• Quota detection with graceful shutdown: The system can detect when a quota is reached and will gracefully shut down services to prevent errors.
• Modern Development Tools: Poetry dependency management + Pyright type checking, providing excellent development experience
• Integrated Frontend: A new React-based frontend for better user experience.

graph TD    subgraph "User End"        User["User"]        WebUI["Web UI (Browser)"]        API_Client["API Client"]    end    subgraph "Launch & Config"        GUI_Launch["gui_launcher.py (GUI Launcher)"]        CLI_Launch["launch_camoufox.py (Command Line Launch)"]        EnvConfig[".env (Unified Configuration)"]        KeyFile["auth_profiles/key.txt (API Keys)"]        ConfigDir["config/ (Configuration Module)"]    end    subgraph "Core Application"        FastAPI_App["api_utils/app.py (FastAPI Application)"]        Routes["api_utils/routers/* (Route Handling)"]        RequestProcessor["api_utils/request_processor.py (Request Processing)"]        AuthUtils["api_utils/auth_utils.py (Authentication Management)"]        PageController["browser_utils/page_controller.py (Page Control)"]        ScriptManager["browser_utils/script_manager.py (Script Injection)"]        ModelManager["browser_utils/model_management.py (Model Management)"]        StreamProxy["stream/ (Streaming Proxy Server)"]    end    subgraph "External Dependencies"        CamoufoxInstance["Camoufox Browser (Anti-Fingerprinting)"]        AI_Studio["Google AI Studio"]        UserScript["Tampermonkey Script (Optional)"]    end    User -- "Run" --> GUI_Launch    User -- "Run" --> CLI_Launch    User -- "Access" --> WebUI    GUI_Launch -- "Starts" --> CLI_Launch    CLI_Launch -- "Starts" --> FastAPI_App    CLI_Launch -- "Configures" --> StreamProxy    API_Client -- "API Request" --> FastAPI_App    WebUI -- "Chat Request" --> FastAPI_App    FastAPI_App -- "Reads Config" --> EnvConfig    FastAPI_App -- "Uses Routes" --> Routes    AuthUtils -- "Validates Key" --> KeyFile    ConfigDir -- "Provides Settings" --> EnvConfig    Routes -- "Processes Request" --> RequestProcessor    Routes -- "Auth Management" --> AuthUtils    RequestProcessor -- "Controls Browser" --> PageController    RequestProcessor -- "Uses Proxy" --> StreamProxy    PageController -- "Model Management" --> ModelManager    PageController -- "Script Injection" --> ScriptManager    ScriptManager -- "Loads Script" --> UserScript    ScriptManager -- "Enhances" --> CamoufoxInstance    PageController -- "Automates" --> CamoufoxInstance    CamoufoxInstance -- "Accesses" --> AI_Studio    StreamProxy -- "Forwards Request" --> AI_Studio    AI_Studio -- "Response" --> CamoufoxInstance    AI_Studio -- "Response" --> StreamProxy    CamoufoxInstance -- "Returns Data" --> PageController    StreamProxy -- "Returns Data" --> RequestProcessor    FastAPI_App -- "API Response" --> API_Client    FastAPI_App -- "UI Response" --> WebUI

New users are recommended to follow theQuick Start section below for deployment, which should take 15-30 minutes to complete.

# 1️⃣ Clone and installgit clone https://github.com/MasuRii/AIstudioProxyAPI.gitcd AIstudioProxyAPIpoetry install# Automatically creates virtual environment and installs dependencies# 2️⃣ Configure environmentcp .env.example .envnano .env# Edit configuration (optional, default configuration can be used). Set AUTO_SAVE_AUTH=true to save authentication.# 3️⃣ Initial authentication and startpoetry run python launch_camoufox.py --debug# Initial authentication (requires Google login)# After successful authentication, move auth_profiles/saved/*.json to auth_profiles/active/# Then run in headless mode:poetry run python launch_camoufox.py --headless

# Health checkcurl http://127.0.0.1:2048/health# Get model listcurl http://127.0.0.1:2048/v1/models# Test chat (non-streaming) - Gemini 3.1 Pro curl -X POST http://127.0.0.1:2048/v1/chat/completions \   -H"Content-Type: application/json" \   -d'{"model":"gemini-3.1-pro","messages":[{"role":"user","content":"Hello"}]}'# Test chat with thinking level (Gemini 3.x models support thinking levels) curl -X POST http://127.0.0.1:2048/v1/chat/completions \   -H"Content-Type: application/json" \   -d'{"model":"gemini-3.1-pro","messages":[{"role":"user","content":"Explain quantum computing"}],"thinking_level":"high"}'# Test streaming chatcurl -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":"Tell me a story"}],"stream":true}' --no-buffer# Alternative models (all valid)# - gemini-3.1-pro-preview# - gemini-3-pro-preview# - gemini-2.5-pro# - gemini-2.5-flash

Open your browser and navigate tohttp://127.0.0.1:2048/ to use the built-in web chat interface.

• Python 3.9+ (recommend 3.10 or 3.11)
• 2GB+ available memory
• Stable internet connection

macOS/Linux:

curl -sSL https://raw.githubusercontent.com/MasuRii/AIstudioProxyAPI/main/scripts/install.sh| bash

Windows (PowerShell):

iwr-useb https://raw.githubusercontent.com/MasuRii/AIstudioProxyAPI/main/scripts/install.ps1| iex

# macOS/Linuxcurl -sSL https://install.python-poetry.org| python3 -# Windows (PowerShell)(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content| py -

git clone https://github.com/MasuRii/AIstudioProxyAPI.gitcd AIstudioProxyAPI

poetry install

# Activate Poetry environmentpoetry shell# Install Playwright browserplaywright install firefox# Download Camoufox data filescamoufox fetch# Or use alternative methodpython fetch_camoufox_data.py

The project uses.env file for configuration management, with all configuration items centrally managed.

# 1. Copy configuration templatecp .env.example .env# 2. Edit configuration filenano .env# or use other editor

Note: Usethinking_level parameter with Gemini 3.x models to control reasoning depth. See.env.example for full configuration options.

Note: Detailed documentation is maintained within the codebase. Refer to the following resources:

• Configuration Reference:.env.example - Complete list of all configuration options with descriptions
• Code Comments: Inline documentation throughout the source code
• Docker Deployment: SeeDocker README andDocker Deployment Guide
• License:AGPLv3

This project supports deployment through Docker, usingPoetry for dependency management,fully supports.env configuration files!

# 1. Prepare configuration filecd dockercp .env.docker .envnano .env# Edit configuration# 2. Start using Docker Composedocker compose up -d# 3. View logsdocker compose logs -f# 4. Version update (in docker directory)bash update.sh

This project usesCamoufox to provide browser instances with enhanced anti-fingerprinting capabilities.

AI Studio Proxy API consists of multiple components working together:

1. FastAPI Main Server (server.py): Provides OpenAI-compatible REST API endpoints.
2. Camoufox Browser: Provides Firefox browser instance with anti-fingerprinting capabilities.
3. Playwright Automation Engine: Controls browser to perform automation operations.
4. Integrated Streaming Proxy Service (stream/): Provides low-latency streaming response proxy.
5. GUI Launcher (gui_launcher.py): Provides graphical startup and configuration interface.

TakingOpen WebUI as an example:

1. Open Open WebUI
2. Go to "Settings" -> "Connection"
3. In the "Model" section, click "Add Model"
4. Model Name: Enter the name you want, for exampleaistudio-gemini-py
5. API Base URL: Enterhttp://127.0.0.1:2048/v1
6. API Key: Leave empty or enter any characters
7. Save settings and start chatting

Welcome to submit Issues and Pull Requests!

AGPLv3

If you find this project helpful and wish to support the author's continuous development, welcome to donate through the following methods. Your support is our greatest encouragement!