AI Studio API

Self-hosted OpenAI-compatible API proxy for Google AI Studio. No API key needed — just a Google account.

中文

Features

• OpenAI-compatible — /v1/chat/completions, /v1/models, /v1/images/generations
• Gemini-native API — /v1beta/models/{model}:generateContent
• Streaming — SSE streaming for both API formats
• Multi-turn — proper user/model alternating conversation history
• Image input — base64 inline or HTTP URL, single or multiple images
• Google Search — real-time web search via googleSearchRetrieval
• Thinking — returns model thinking process (thinking field)
• Image generation — via Gemini image models
• Anti-detection — Camoufox (anti-fingerprint Firefox) to avoid bot detection
• BotGuard — auto-detects snapshot function via runtime feature matching (survives bundle updates)
• Multi-account — round-robin / LRU / least-rate-limited rotation

Quick Start

# Clone
git clone https://github.com/yourname/aistudio-api.git
cd aistudio-api

# Install dependencies
pip install -r requirements.txt

# Login to Google (opens browser, saves cookies)
python3 main.py login

# Start server
python3 main.py server --port 8080 --camoufox-port 9222

Docker

docker build -t aistudio-api .
docker run -p 8080:8080 -v ./data:/app/data aistudio-api

Usage

OpenAI-compatible API

# Chat (streaming)
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-4-31b-it",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

# Image understanding
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-flash-preview",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBOR..."}},
        {"type": "text", "text": "What is this?"}
      ]
    }]
  }'

# List models
curl http://localhost:8080/v1/models

Gemini-native API

# With Google Search
curl http://localhost:8080/v1beta/models/gemini-3-flash-preview:generateContent \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "What is the latest news?"}]}],
    "tools": [{"googleSearchRetrieval": {}}]
  }'

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="unused")

response = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)
for chunk in response:
    print(chunk.choices[0].delta.content or "", end="")

CLI Client

# Quick chat
python3 main.py client "What's the weather today?" --search

# With image
python3 main.py client "What is this?" -a photo.jpg

# Image generation
python3 main.py client "Draw a cat" --image --save cat.png

Supported Models

All models have thinking enabled by default (streaming thinking field). Gemma 4 26B A4B has Google Search enabled by default.

Configuration

Environment variables or .env file:

Architecture

Client (OpenAI SDK / curl)
    │
    ▼
┌─────────────────────┐
│   FastAPI Server     │  ← OpenAI + Gemini API routes
│   /v1/chat/...       │
│   /v1beta/...        │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│   Wire Codec         │  ← Converts API format → AI Studio gRPC body
│   + BotGuard         │     Auto-detects snapshot function via features
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│   Camoufox Browser   │  ← Anti-fingerprint Firefox, injects cookies
│   (headless)         │     Sends request via XHR hook
└─────────┬───────────┘
          │
          ▼
    Google AI Studio

How it works: 1. API request comes in, gets normalized into AI Studio's wire format 2. A BotGuard snapshot is generated (auto-detected function, cached) 3. The full gRPC body is constructed and injected into the browser via XHR hook 4. The browser sends the request to Google (with valid cookies + BotGuard) 5. Response is parsed and returned in the requested API format

Multi-account

Manage multiple Google accounts for higher throughput:

# Add accounts
python3 main.py account add --email user1@gmail.com
python3 main.py account add --email user2@gmail.com

# List
python3 main.py account list

# Auto-rotate on startup
AISTUDIO_ACCOUNT_ROTATION_MODE=round_robin python3 main.py server

Rotation modes: - round_robin — cycle through accounts - lru — least recently used - least_rl — least rate-limited

Development

# Run tests
python3 -m pytest tests/

# Extract snapshot (debug)
python3 main.py snapshot "test prompt"

How BotGuard Works

Google requires a BotGuard "snapshot" with every request — a cryptographic proof that the request came from a real browser. This project:

1. Hooks the frontend's snapshot function at runtime
2. Auto-detects it via feature matching (.snapshot({ + content + yield) — survives bundle updates
3. Generates valid snapshots for each request

The snapshot function name changes with every Google bundle update (Mv → Ov → Sv → ...), but the feature pattern stays the same.

License

MIT