Skip to content

About

Zero-dependency native Gemini HTTP/2 gateway & in-process Pi extension (pi-gemini-app) connecting Gemini subscriptions to OpenAI-compatible coding agents (Cursor, Cline, Codex, Pi) with multi-account pooling.

Topics

Resources

Contributing

Security policy

Stars

87 stars

Watchers

0 watching

Forks

Repository files navigation

Gemini App2API

Your coding agents. Your Gemini subscriptions. Zero-dependency native HTTP/2.

Use your eligible Google Gemini accounts in Pi, OpenClaw, Cursor, Cline, Roo Code, Codex CLI, and OpenAI SDKs—via standalone in-process plugins (no server needed) or a self-hosted Node.js gateway with multi-account pooling.

CI pi-gemini-app on npm openclaw-gemini-app on npm Node.js >= 22 Zero Runtime Dependencies Docker Ready License: MIT

English · 繁體中文 · Quick Start · Connect Client · Models & Quota · API Reference · Operations

Important

Unofficial interoperability research project. Not affiliated with or endorsed by Google. Sign in personally with your own eligible Google accounts—no credentials, tokens, or Google binaries are distributed. Read DISCLAIMER.md.


Quick Start

Path A — Standalone Native Plugins (No Server Required)

gemini-app2api — Zero-Dependency Native Extensions for Pi & OpenClaw

Host Install Sign In & Quota Guide
Pi / GooeyPi pi install npm:pi-gemini-app /login gemini-app · /gemini-quota extensions/pi/README.md
OpenClaw openclaw plugins install npm:openclaw-gemini-app (or ClawHub) openclaw models auth login --provider gemini-app · /usage extensions/openclaw/README.md

Both plugins run in-process over direct HTTP/2 (15s PING keepalives, HTTPS_PROXY support, 256 tools, parallel multimodal image uploads, automatic Free-tier gemini-auto filtering).

Path B — Self-Hosted OpenAI-Compatible Gateway

Requires Node.js >= 22 (macOS / Linux / WSL2) or Docker Compose, plus a Google account with Gemini access (AI Studio API keys are a different service).

Node.js:

git clone https://github.com/ShawTim/gemini-app2api.git && cd gemini-app2api
npm ci --omit=dev --ignore-scripts
npm start

Docker Compose:

git clone https://github.com/ShawTim/gemini-app2api.git && cd gemini-app2api
read -r -s -p 'Admin password (>= 12 chars): ' GATEWAY_ADMIN_PASSWORD; echo
export GATEWAY_ADMIN_PASSWORD && docker compose up -d --build
Or run pre-built GHCR image directly (linux/amd64 & linux/arm64)
read -r -s -p 'Admin password (>= 12 chars): ' GATEWAY_ADMIN_PASSWORD; echo
docker run -d --name gemini-app2api --init --restart unless-stopped \
  -p 127.0.0.1:18989:18989 -p 127.0.0.1:18765:18765 \
  -v gemini-gateway-state:/data \
  --read-only --cap-drop ALL --security-opt no-new-privileges \
  --tmpfs /tmp:rw,noexec,nosuid,size=16m \
  -e GATEWAY_HOST=0.0.0.0 -e GATEWAY_CALLBACK_HOST=0.0.0.0 -e GATEWAY_ALLOW_REMOTE=1 \
  -e GATEWAY_PUBLIC_ORIGIN=http://127.0.0.1:18989 -e GATEWAY_ADMIN_PASSWORD \
  ghcr.io/shawtim/gemini-app2api:latest

See Operations Guide for custom ports, TLS reverse proxies, and SSH tunneling.

Finish setup in browser: Open http://127.0.0.1:18989/admin/ → Accounts → + Google sign-in → click Test to verify entitlement → API keys → Create key.


Connect Your Client

Setting Value
Base URL http://127.0.0.1:18989/v1 (or http://gateway:18989/v1 inside Compose / your HTTPS proxy URL)
API Key Client key from API keys
Models gemini-neon (flagship Pro; gemini-argon aliases here), gemini-hydrogen (fast), gemini-flash-lite
Endpoints GET /v1/models · POST /v1/chat/completions · POST /v1/responses (full contract)
curl -fsS http://127.0.0.1:18989/v1/chat/completions \
  -H "Authorization: Bearer $GEMINI_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-neon","messages":[{"role":"user","content":"Hello!"}]}'
Client Recipes — Codex CLI, Cursor, Cline / Roo Code, Cherry Studio, OpenAI SDKs
  • OpenAI Codex CLI (~/.codex/config.toml) — native /v1/responses + namespace tools:
    model = "gemini-hydrogen" # or "gemini-neon"
    model_provider = "gemini_app2api"
    model_reasoning_summary = "none"
    web_search = "disabled"
    
    [model_providers.gemini_app2api]
    name = "Gemini App2API"
    base_url = "http://127.0.0.1:18989/v1"
    env_key = "GEMINI_GATEWAY_KEY"
    wire_api = "responses"
  • Cline / Roo Code: API Provider OpenAI Compatible, Base URL http://127.0.0.1:18989/v1, Model gemini-hydrogen or gemini-neon.
  • Cursor: Settings → Models → add gemini-neon / gemini-hydrogen → Override OpenAI Base URL (HTTPS tunnel required if Cursor's cloud relay is active).
  • Cherry Studio / Open WebUI / SDKs: OpenAI provider with http://127.0.0.1:18989/v1; see examples/client.mjs and examples/client.py.

Models & Quota

Model Role Native Mode Advisory context_window
gemini-neon Gemini 4 Neon flagship Pro reasoning & coding (gemini-argon aliases here) PRO (3) 512,000
gemini-hydrogen Gemini 4 Hydrogen low-latency reasoning (~1.7–2.6× faster, lighter quota) FAST (1) 512,000
gemini-flash-lite High-throughput lightweight tasks 6 —

Empirical GetUsageInfo observations on Gemini AI Pro accounts (neon_pro_policy; not official Google SLA figures):

Workload gemini-hydrogen gemini-neon Neon Multiple
Massive code review + rewrite (thinking=2) ~0.12% weekly (~76s) ~0.25% weekly (~198s) ~2.0×
Multi-tool agent tool_call step (thinking=2) ~0.024% weekly (~8s) ~0.037% weekly (~14s) ~1.56×
Standard ~14 KB plan (thinking=0) ~0.017% weekly (~28s) ~0.086% weekly (~36s) ~5.1×
Est. 5-hour single-account capacity ~40 rewrites / ~210 tool steps ~20 rewrites / ~135 tool steps —

Why Gemini App2API?

MGGA — GigaChad Gemini Model vs Derpy Consumer App Harness
MGGA — Make Gemini Great Again: Free frontier Gemini models from a consumer chat harness into real engineering tools.

Dimension Gemini App2API Web / Cookie Scrapers Desktop Injection / MITM
Transport Pure Node.js native HTTP/2 (ProcessQuery) + parallel image uploads Fragile DOM / browser cookies Binary hooks / local MITM
Auth & Pool Standard Google OAuth (0600 local state), multi-account failover & quota bars Frequent cookie expiry / CAPTCHA Single active desktop GUI
Agent Safety Schema-validated tools (256 declarations), hallucinated tool-result suppression, incomplete: true contract Unvalidated regex / broken loops Consumer UI limits
Footprint Node.js >= 22, 0 production npm dependencies Playwright / Python stacks OS & binary version locked

Highlights:

  • Resilient HTTP/2 & Proxy Support: 15s HTTP/2 PING + TCP keepalives, zero-dependency HTTPS_PROXY / HTTP_PROXY / NO_PROXY CONNECT tunneling, retryable 503 SERVER_SHUTDOWN restarts, and bounded automatic recovery.
  • Built for Long E2E & Agent Loops: Up to 256 caller tool declarations (512 KiB / 16,384 nodes), structured outputs (json_schema / json_object), opt-in native_search citations, and parallel HTTP/2 multimodal image uploads (256 images / 20 MiB per image safety bounds + per-account in-memory blobId caching).
  • Zero-Dependency Security & Bilingual Console: 0700/0600 private state, scrypt admin auth, SHA-256 key vault, CSRF/Origin guards, and live per-account × per-model telemetry (English / 繁體中文, zero prompt logging).

Gemini App2API Operations Console — Dark Theme (synthetic demo data)

More Console Screenshots (Light Theme & Mobile 繁體中文)
Light Theme — Account Inspector Mobile — Traditional Chinese (繁體中文)
Light theme Mobile console

Documentation

Document Contents
Pi Extension (extensions/pi/README.md) Standalone pi-gemini-app plugin for Pi Coding Agent & GooeyPi
OpenClaw Plugin (extensions/openclaw/README.md) Standalone openclaw-gemini-app provider plugin for OpenClaw & ClawHub
API Support (docs/API_SUPPORT.md) Endpoints, tools, structured outputs, images, native_search, error codes
Operations (docs/OPERATIONS.md) .env config, Docker Compose, TLS reverse proxy, launchd, troubleshooting
Completion Contract (docs/COMPLETION_CONTRACT.md) Partial-output preservation, zero-output GENERATION_FAILED, agent loop safety
Account Lifecycle (docs/ACCOUNT_LIFECYCLE.md) · Limits (docs/LOCKS_AND_LIMITS.md) OAuth, ToS consent, quota telemetry, concurrency & payload bounds
Testing (docs/CURRENT_CONTRACT_TESTS.md) · Security (SECURITY.md) · Changelog (CHANGELOG.md) Offline E2E suites, security model, release history

MIT License · Disclaimer · Security Policy · Contributing

Unofficial self-hosted interoperability software. No Google binaries, credentials, tokens, accounts, or quota are distributed.

About

Zero-dependency native Gemini HTTP/2 gateway & in-process Pi extension (pi-gemini-app) connecting Gemini subscriptions to OpenAI-compatible coding agents (Cursor, Cline, Codex, Pi) with multi-account pooling.

Topics

Resources

Contributing

Security policy

Stars

87 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages