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

What AIstudioProxyAPI actually replaces

Google AI Studio is a web application. It has no documented public API surface that an ordinary developer can point a client at, and the models exposed there are otherwise reachable only through other Google endpoints with their own keys and terms. AIstudioProxyAPI closes that gap by putting a local FastAPI server in front of the web page and translating requests and responses into the OpenAI chat completions shape. The README states it supports /v1/chat/completions and /v1/models, which means an existing OpenAI client library can talk to it after a base URL change and nothing else.

The audience is narrow and specific. It is for people who already have access to AI Studio through a browser session and want to use that access from tooling that speaks OpenAI: Open WebUI, a local script, an agent framework, a chat front end. The README's client example is Open WebUI, where the base URL is set to http://127.0.0.1:2048/v1 and the API key can be left empty or filled with any character if no keys are configured. If you have a supported official API for the models you need, this project is extra machinery. If you do not, it is one of the few ways to get that shape.

Camoufox, Playwright and the request path

The architecture is a chain, not a single process. The README's diagram shows a launcher reading .env, a FastAPI application under api_utils/, browser control under browser_utils/, and a separate streaming proxy under stream/. Requests arrive at FastAPI, are handed to the browser layer, and are executed against Google AI Studio through Camoufox, which is a Firefox-based browser built on Playwright. The response is then converted back into OpenAI format. The stream/ component exists because streaming a chat completion out of a browser page is a different problem from returning a JSON body, and the README gives it its own port, STREAM_PORT, defaulting to 3120, with 0 disabling it.

That design has consequences worth stating plainly. Every completion occupies a browser context, so throughput is bounded by browser automation rather than by an HTTP client pool. The dependency list pins the browser and the framework tightly: camoufox is fixed at 0.4.11 with the geoip extra, fastapi at 0.115.12, uvicorn at 0.29.0. Those pins make builds reproducible and make upgrades a deliberate act rather than a side effect of installing. The README also notes that some defaults live in code rather than in .env.example, and points at docs/configuration-reference.md for the exceptions. That is an honest disclosure and also a warning: reading only the sample environment file will not tell you every value in play.

Installing AIstudioProxyAPI and sending a first request

The README's quick start assumes Poetry for dependency management, Python between 3.9 and 4.0, and Node.js LTS if you intend to build the front end. Clone the repository and install with the dev group, which is what the README shows even for a first run.

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

Next, copy the environment template. The README recommends confirming PORT, STREAM_PORT, UNIFIED_PROXY_CONFIG, LAUNCH_MODE and FUNCTION_CALLING_MODE before you go further. The template itself sets PORT=2048 and STREAM_PORT=3120, and UNIFIED_PROXY_CONFIG to an HTTP proxy address, which is the setting that routes both the Python process and the internal browser.

cp .env.example .env

The first launch should be in debug mode, because authentication happens interactively in a visible browser and the session is saved afterwards. The README describes debug mode as the mode for first authentication and troubleshooting, and headless as the daily mode.

poetry run python launch_camoufox.py --debug

Once that has completed and the service is listening, the README's own smoke tests are three curl calls. The health endpoint and the model list confirm the server is up and the OpenAI surface is present.

curl http://127.0.0.1:2048/health
curl http://127.0.0.1:2048/v1/models

A chat request uses the standard OpenAI body. The README's example sends a single user message to gemini-2.5-pro and expects a chat completion object back.

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

For daily use, switch to headless. On a Linux machine without a graphical session, the README lists a third mode, --virtual-display, which runs the browser against a virtual display instead.

poetry run python launch_camoufox.py --headless

There is also a built-in Web UI at http://127.0.0.1:2048/ for settings, status checks and logs, so you do not have to edit .env for every change.

Function calling has three modes and a fallback

The feature most likely to decide adoption is how tools are handled. The README describes three function calling modes, auto, native and emulated, with failure fallback, selected through FUNCTION_CALLING_MODE, which defaults to auto. Native mode presumably maps to whatever structured tool support the underlying page offers; emulated mode means the proxy prompts the model and parses the result itself. The README does not explain the mechanics of either in the main file, and defers to docs/function-calling.md.

That is the honest state of things: the project gives you a knob and a dedicated document, not a guarantee. If your application depends on reliable tool calls, auto is a reasonable default but not a promise, and you should test your own schemas against it rather than trusting the mode name. Emulated parsing is inherently more fragile than a structured response, because it depends on the model producing text the parser recognises. Anyone whose pipeline breaks silently when a tool call is dropped should treat this as the first thing to validate.

Auth rotation, cookies and the operational cost

Because the upstream is a logged-in browser, session handling is a first-class concern rather than a detail. The README lists profile rotation with automatic switching, periodic refresh, and saving on shutdown, controlled by AUTO_ROTATE_AUTH_PROFILE, which defaults to true. There is a dedicated document, docs/auth-rotation-cookie-refresh.md, and an auth_profiles/ directory at the top level of the repository, which is where saved sessions live.

The practical cost follows from that. A headless deployment on a server still needs a valid session, and the README's own advice is to run debug mode first to complete login. Sessions expire; the rotation and refresh machinery exists to absorb that, but it is machinery you are now operating. The README does not document what happens when every profile in the pool is invalid, and it does not describe a rollback path for a bad configuration change. Treat the auth profiles directory as state you must back up and monitor, not as an implementation detail. The repository also ships a multi-instance Docker manager under scripts/multi-instance-manager/, which suggests running several instances side by side is an anticipated pattern rather than an afterthought.

Memory is the other constraint. The README's requirement table asks for at least 2GB and recommends 4GB or more. A browser plus a Python service plus a front end is not a small footprint, and that number is a floor, not a target.

Where AIstudioProxyAPI is the wrong tool

The clearest failure mode is upstream change. The entire request path depends on the layout and behaviour of a web page that Google can redesign without notice. When that happens, the fix is in browser_utils/, in selectors and page operations, and it arrives when a maintainer or you write it. A project that wraps a documented API has a contract; this one has a DOM. Release history reflects that reality: the most recent release is a nightly build dated 2026-04-22, with v4.1.2_py on 2026-04-17 before it. The last push to the repository was on 2026-04-22, which is several months before this writing, so treat the project as one whose update cadence you should check yourself rather than assume.

Second, this is not a path to unlimited or unattended scale. Browser automation serialises work in ways an HTTP client does not, and the streaming proxy is a separate service with its own port and its own failure modes. If you need high concurrency, per-request cost accounting, or an SLA, an official API is the correct choice and this project is not a substitute.

Third, the licence matters for how you can use it. AIstudioProxyAPI is AGPL-3.0. If you modify it and expose it to users over a network, the AGPL's source-availability terms are relevant to you in a way that permissive licences are not. That is a description of the licence, not legal advice; if your deployment is commercial, have someone qualified read the LICENSE file.

How it differs from an OpenAI-compatible gateway

The obvious alternative is a gateway such as LiteLLM, which also presents an OpenAI-shaped endpoint and also supports /v1/chat/completions and /v1/models. The difference is what sits behind that endpoint. A gateway translates between real HTTP APIs: it holds provider keys and maps request fields onto each provider's documented schema. AIstudioProxyAPI holds no provider key at all. It holds a browser session, and its translation target is a user interface. That means a gateway gives you predictable error codes, retries and rate-limit semantics inherited from the upstream API, while this project gives you whatever the page does, mediated by Playwright.

The trade-off is access versus stability. If the model you want is reachable through an official API, the gateway is the lower-risk choice and the one with a clearer upgrade story. If it is reachable only through AI Studio's interface, a gateway cannot help you and this project can. Choosing between them is really choosing whether you are willing to own browser automation as part of your stack.

Verifying a deployment before you depend on it

The repository carries a real test setup, which is a point in its favour. pyproject.toml configures pytest with coverage over api_utils, browser_utils, stream, config, models, launcher, logging_utils and server.py, and a 120 second per-test timeout. There is an integration marker for tests that use real components such as locks, queues and state rather than mocks, and the test environment sets LAUNCH_MODE=test and STREAM_PORT=0 so the streaming service stays out of the way.

poetry run ruff check .
poetry run pyright
poetry run pytest

Running those three commands tells you whether the checkout is healthy on your Python version before you point a client at it. What they cannot tell you is whether the live AI Studio page still matches the selectors, because that requires a real authenticated session. That gap is the thing to keep in mind: the test suite covers the Python side, and the browser side is verified by using it.

Editorial conclusion

Adopt it if you want an OpenAI-shaped endpoint backed by a Google AI Studio account and you can live with browser automation in the request path. Do not adopt it if you need a vendor-supported interface, per-token billing, or a guarantee that a page redesign will not break you. Before committing, verify the function calling mode against your own tool schema, confirm that your proxy settings let Camoufox reach AI Studio, and read docs/auth-rotation-cookie-refresh.md to see how cookie persistence is handled on your platform.

Frequently asked questions

Official sources

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