AIstudioProxyAPI: an OpenAI-compatible proxy in front of Google AI Studio

What AIstudioProxyAPI actually solves

Google AI Studio is a web application. It has no public API that mirrors its chat interface, and the official Gemini API is a separate product with its own keys, quotas and terms. AIstudioProxyAPI exists for the gap between those two facts: a program that already speaks the OpenAI chat-completions dialect cannot call an AI Studio chat session directly. The project inserts a translation layer. Requests arrive in OpenAI format, get driven through a real browser session logged into AI Studio, and the answer comes back shaped like an OpenAI response.

The intended user is someone with an AI Studio account who wants to point an existing OpenAI-compatible client at it. The README's client example is Open WebUI: set the API base URL to http://127.0.0.1:2048/v1, and leave the key blank or fill any character if no API keys are configured on the proxy. That is the whole pitch. It is not a model host, it does not train anything, and it does not give you a Gemini API key. It gives you an endpoint that behaves like one.

How the browser automation bridge is wired

The architecture diagram in the README splits the system into a launcher, a FastAPI application under api_utils/, page control under browser_utils/, and a separate streaming proxy under stream/. The launcher, launch_camoufox.py, reads .env and starts Camoufox, the browser build the project depends on. Camoufox is pinned in pyproject.toml at version 0.4.11 with the geoip extra, and Playwright is a dependency alongside it. Requests do not go to a model endpoint; they go to Google AI Studio through that browser.

Two ports matter. PORT defaults to 2048 and carries the OpenAI-compatible surface, including /v1/chat/completions and /v1/models. STREAM_PORT defaults to 3120 and can be disabled by setting it to 0. The repository also ships stream/, so streaming is handled by a component separate from the main FastAPI app rather than by the same process. Authentication is not a single cookie file: the project describes auth profile rotation, periodic cookie refresh, and saving state on shutdown, with AUTO_ROTATE_AUTH_PROFILE defaulting to true. Function calling has three modes, auto, native and emulated, with failure fallback, and FUNCTION_CALLING_MODE defaults to auto.

Installing it and sending a first request

The README states Python >=3.9,<4.0 (3.10+ or 3.11+ recommended), Poetry, Node.js LTS for building the frontend, and at least 2GB of memory, 4GB recommended. pyproject.toml sets package-mode = false, so this is an application repository, not a library you install from PyPI. Clone it and let Poetry resolve the lockfile:

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

Poetry installs the pinned dependencies, including fastapi ==0.115.12, uvicorn ==0.29.0 and camoufox 0.4.11 with the geoip extra. Next, create the environment file and review the values the README flags:

cp .env.example .env

The README suggests confirming PORT, STREAM_PORT, UNIFIED_PROXY_CONFIG, LAUNCH_MODE and FUNCTION_CALLING_MODE before the first start. The first launch is interactive on purpose, because you need to log in once and save the auth state:

poetry run python launch_camoufox.py --debug

After the login is saved, the README recommends headless mode for daily use:

poetry run python launch_camoufox.py --headless

With the process running, three checks confirm it is alive. The health endpoint, the model list, and a chat completion:

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

No Authorization header appears in the README's chat example, because keys can be left blank or filled with any character when API keys are not configured. If you do configure keys, the client instructions say to supply a valid one. The built-in Web UI is served at http://127.0.0.1:2048/ and provides settings, status checks and logs.

The first run is interactive, and that is the point

Authentication is why the first launch is not headless. The README recommends running in debug mode once to complete login and save the auth state, then switching to headless for daily use. Three modes are documented: --headless for servers and routine use, --debug for first-time authentication and troubleshooting, and --virtual-display for Linux machines without a GUI. The virtual-display flag exists because Camoufox is a real browser and needs somewhere to draw unless you give it a headless or virtual surface.

That sequencing is a design decision, not an inconvenience to route around. A single saved profile is a single point of failure, which is why AUTO_ROTATE_AUTH_PROFILE defaults to true and why the project documents periodic cookie refresh and saving state on shutdown. If you skip the debug run and go straight to headless, there is no saved auth to rotate.

Where this design breaks down

Every request travels through a browser session driving a web page. That is the core constraint, and it has consequences the README does not paper over. If Google changes the AI Studio DOM, the operations in browser_utils/ can stop matching, and the failure looks like a broken chat completion rather than a clear error. The troubleshooting guide exists for exactly this class of problem, but no automation layer of this kind is immune to it.

There is also a maintenance signal worth reading plainly. The last push to the default branch was on 2026-04-22, and the most recent release is a nightly build from the same date, following v4.1.2_py on 2026-04-17. The repository is not archived, but the commit history is quiet over a period when the upstream web interface could have moved. Treat the project as something you pin and watch, not something that absorbs upstream churn for you.

Finally, the legal and account question is real and the README does not answer it. Automating a web UI can conflict with a service's terms, and the project cannot grant you permission it does not hold. If your use case requires a vendor-backed SLA or documented rate limits, this is the wrong tool; the official Gemini API is the right one.

How it differs from a direct API client

The obvious alternative is calling the official Gemini API through one of the existing OpenAI-compatibility shims. The difference is not cosmetic. A shim translates request and response shapes between two HTTP APIs; it needs an API key and it is bound by that API's quotas and pricing. AIstudioProxyAPI translates between an HTTP API and a browser session, which means the credential is a logged-in AI Studio profile rather than a key, and the quota is whatever the web interface enforces for that account.

That trade buys you access to the AI Studio chat experience through an OpenAI-shaped endpoint, and it costs you determinism. A shim fails with an HTTP status and a JSON error body. This project can fail because a button moved. The auth rotation and cookie refresh features exist to manage the second kind of failure, not to eliminate it.

Licence, upgrade cost and what to check before deploying

The project is AGPL-3.0. The practical implication for engineers, stated without legal advice: if you modify it and let other users interact with it over a network, the AGPL's source-availability obligations are generally understood to apply to your modified version. Running an unmodified copy for yourself is a different situation. If you plan to fork it into a hosted service, read the licence text rather than a summary.

Upgrading is not a version bump. Dependencies are pinned tightly in pyproject.toml, including fastapi ==0.115.12, uvicorn ==0.29.0, camoufox 0.4.11 with the geoip extra, and cryptography ==42.0.5. Camoufox is the pin most likely to matter, because browser fingerprinting and page behaviour are coupled to it. The repository also carries a scripts/multi-instance-manager with its own README if you need more than one instance, which is the honest answer to running this at any scale: you add processes, not throughput per process.

Before deploying, confirm the .env values you care about. PORT, STREAM_PORT, UNIFIED_PROXY_CONFIG, LAUNCH_MODE and FUNCTION_CALLING_MODE are the ones the README flags. UNIFIED_PROXY_CONFIG takes priority and sets HTTP_PROXY, HTTPS_PROXY and the internal browser proxy together, which matters because the browser, not just the Python process, needs to reach Google.

Editorial conclusion

Adopt it if you already have an AI Studio account you are allowed to automate and you need an OpenAI-shaped endpoint for a client such as Open WebUI; the README's own client instructions point at http://127.0.0.1:2048/v1. Do not adopt it if you need vendor-backed uptime, contractual rate limits, or a deployment where automating a web UI conflicts with the terms of service. Before committing, verify that the Google AI Studio interface still matches the page operations in browser_utils/, confirm your Python and Node versions satisfy the stated requirements, and read the AGPL-3.0 licence in full if you plan to expose a modified version to other users.

Frequently asked questions

Official sources

1. CJackHwang/AIstudioProxyAPI on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases