Gemini Business2API: an OpenAI-compatible gateway for a Gemini Business account pool

The account-pool problem Gemini Business2API addresses

Gemini Business is a browser-facing product. Its interface is a web app at business.gemini.google, not an API with keys and rate headers. If you have several seats and want to call them from code, you have to solve three separate problems: speaking a protocol that existing clients understand, spreading load across accounts, and keeping credentials alive.

Gemini Business2API answers the first two directly. The README describes it as a gateway that converts Gemini Business into an OpenAI-compatible interface, and it lists multi-account scheduling with polling and availability-based switching as a core capability. That means a client that already speaks /v1/chat/completions can be pointed at this service without a code change.

The intended user is someone operating a small pool of business seats, not a single developer with one login. The admin panel exists for that operator: account import, export, editing, batch operations and status filtering are listed as panel features, alongside a dashboard, monitoring, logs and an image gallery. If your setup is one account and one script, the panel and the scheduling layer are overhead you do not need.

How the gateway, the account pool and the database fit together

The README includes a Mermaid flowchart that separates two planes. On one side, an OpenAI-compatible client hits the 2API gateway, which routes to runtime endpoints for models, chat, images and video. On the other, an administrator uses the frontend, whose modules (dashboard, accounts, settings, monitor, logs, gallery, docs) all call a backend admin API.

Both planes converge on a domain layer described as account pool, configuration center, scheduling, monitoring and logging. That layer persists to SQLite or PostgreSQL and writes to a data directory. The optional refresh-worker is drawn as a dotted edge, meaning it is not part of the main runtime path.

The deployment layout confirms this. docker-compose.yml defines two services. gemini-api runs the gateway and the admin panel, exposes port 7860 and mounts ./data into /app/data. refresh-worker sits behind the profile refresh, does not start by default, exposes no business API, reads the same ./data volume and has a health endpoint on port 8080 by default. The worker also waits on the gateway: depends_on uses condition: service_healthy.

That split is the most opinionated decision in the project. Since v0.3.0 the README says the main repository keeps only the 2API service, the admin panel and an optional refresh-worker, and that the registration tooling, the registration flow, the in-process refresh executor and browser-dependent legacy paths were removed or moved out. The consequence is honest and slightly awkward: token refresh is no longer a feature of the thing you install by default. It is a second container you opt into.

Installing Gemini Business2API with Docker Compose

The README recommends Docker Compose. Clone the repository, copy the example environment file, set at least ADMIN_KEY, then start the stack:

git clone https://github.com/yukkcat/gemini-business2api.git
cd gemini-business2api
cp .env.example .env
# at minimum, set ADMIN_KEY
docker compose up -d

After that, the admin panel should answer at http://localhost:7860/ and the health check at http://localhost:7860/health. The OpenAI-compatible endpoint is http://localhost:7860/v1/chat/completions. The port comes from the PORT variable, which docker-compose.yml maps as "${PORT:-7860}:7860", so changing PORT only moves the host side.

If you want the refresh worker running, start the same compose file with the refresh profile:

docker compose --profile refresh up -d

The README also documents an interactive installer that asks whether you want Docker or local Python mode, the service port, ADMIN_KEY, DATABASE_URL and whether to enable refresh-worker. The default invocation is:

curl -fsSL https://raw.githubusercontent.com/yukkcat/gemini-business2api/main/deploy/install.sh | sudo bash

To pin the installer to the release the README names as current, replace main with v0.3.3 in that URL. A --with-refresh flag only presets the refresh-worker answer to yes; the README states it is not a separate installation flow. Note the discrepancy you will hit immediately: the README banner says the current stable version is v0.3.3, while the releases list shows v0.3.0 as the most recent entry. Confirm which tag you are installing before you pin anything.

Model IDs, multimodal endpoints and what the .env actually controls

The README publishes a model table rather than leaving IDs to discovery. gemini-auto, gemini-2.5-pro, gemini-3.5-flash and gemini-3.1-pro-preview all support image recognition, native web access and file multimodality, with image generation listed as optional. gemini-imagen is the dedicated image model and gemini-veo is the dedicated video model. Both dedicated models also carry the recognition, web and file columns.

The HTTP surface is small and explicitly enumerated: GET /v1/models, POST /v1/chat/completions, POST /v1/images/generations, POST /v1/images/edits and GET /health. Anything outside that list is not claimed to exist, so clients that depend on assistants endpoints, embeddings or audio will not find them here.

Configuration is split by scope, and .env.example is unusually direct about which scope owns what. The admin panel under system settings holds shared service configuration, shared refresh configuration and default mail configuration. Account-level fields such as mail_provider, mail_address, mail_password, mail_client_id, mail_refresh_token, mail_base_url, mail_api_key, mail_jwt_token, mail_verify_ssl and mail_domain belong to account management. Worker environment variables are for machine-local overrides only. The example file also notes that FORCE_REFRESH_ENABLED, when set, takes priority over the panel setting.

Storage defaults to local SQLite at data/data.db. Setting DATABASE_URL switches to PostgreSQL, and the README recommends that when the worker runs outside the current compose or when you deploy across machines. requirements.txt keeps asyncpg commented out with a note to uncomment it and set DATABASE_URL, which means the default image does not carry the PostgreSQL driver.

Where Gemini Business2API is the wrong tool

The refresh split is the first limit. If your accounts expire and you do not run the worker, the gateway has no in-process path to renew them; that executor was deliberately removed from the main line. The worker itself is a separate image, pulled from REFRESH_WORKER_IMAGE, and the README points to an independent refresh-worker branch for it. So the reliability of your pool depends on a component that lives outside the repository you cloned.

The second limit is the upstream. Everything here is a translation layer in front of a product with its own terms. The gateway cannot make Gemini Business more available, faster or more permissive than the accounts behind it. If your seats are suspended or your region blocks the service, the OpenAI-compatible facade changes nothing.

The third is licence scope. The README states the project uses the Cooperative Non-Commercial License (CNC-1.0), while the repository metadata reports NOASSERTION and the LICENSE file is the only authoritative text. A non-commercial licence is a hard stop for products you sell or host for paying customers. Read LICENSE before you build on it.

The fourth is maintenance. The last push to the default branch was on 2026-05-21, and the repository is not archived. That is roughly four months before this writing, so treat the code as stable-but-quiet rather than actively developed, and check the release channel before assuming a fix is coming.

Gemini Business2API compared with a direct provider SDK

The obvious alternative is calling a provider's own API with its official SDK. That approach gives you a documented rate-limit contract, per-key quotas, a support channel and a licence you do not have to interpret. What it does not give you is reuse of Gemini Business seats you may already be paying for, and it does not give you an OpenAI-shaped request body unless the provider ships one.

The difference in mechanism matters more than the difference in features. A direct SDK authenticates with a key you were issued. Gemini Business2API authenticates by holding a pool of browser-session credentials, scheduling across them, and persisting them in SQLite or PostgreSQL. That is why the project needs an account import path at all. The README documents a Tampermonkey userscript at tools/tampermonkey/gemini-business-import.user.js that copies importable account JSON from the Gemini Business page, with Shift + Click to download a file instead. The exported expires_at defaults to the current time plus 12 hours.

That 12-hour default tells you what kind of system this is. Credentials are short-lived artifacts you re-import, and the refresh-worker exists to automate the churn. A provider API key does not work that way. If your workload is steady production traffic and you can buy keys directly, the direct SDK removes an entire credential-management tier. If your constraint is that you already hold Business seats, this project is the tier that makes them programmable.

Upgrade path, data volume and licence cost

Upgrades are image pulls. docker-compose.yml pins cooooookk/gemini-business2api:latest for the gateway and defaults the worker to cooooookk/gemini-refresh-worker:latest, both overridable through PORT and REFRESH_WORKER_IMAGE. There is no documented migration step, and the README does not describe rollback. Your state lives in ./data, which the compose file mounts into /app/data and which the Dockerfile declares as a VOLUME. That directory holds the SQLite database, runtime persistent data and locally generated files and caches. Back it up before you pull a new tag, and pin a version tag instead of latest if you need a predictable upgrade.

The operational cost is the second container. Running the refresh profile means another image to track, another health endpoint on port 8080, and worker-side variables such as SQLITE_PATH, HEALTH_PORT, REFRESH_INTERVAL_MINUTES, REFRESH_WINDOW_HOURS, BROWSER_HEADLESS and PROXY_FOR_AUTH. The README notes that when these are left empty the worker reads the shared values from the panel's system settings, which is the configuration path to prefer.

On licence, the README states CNC-1.0 and the repository metadata reports NOASSERTION. Those do not agree, and the practical reading is that the LICENSE file governs. A non-commercial licence limits commercial deployment, but it does not tell you whether you may modify and redistribute internally, so read the text rather than the badge. This is a description of what the files say, not legal advice.

Editorial conclusion

Adopt it if you already hold Gemini Business accounts and need an OpenAI-shaped endpoint in front of them, with a dashboard for the pool. Do not adopt it if you need a licence that permits commercial redistribution, or if you cannot run the separate refresh-worker when tokens expire. Verify first that your clients only call /v1/models, /v1/chat/completions, /v1/images/generations, /v1/images/edits and /health, and read the LICENSE file before you deploy, because the repository metadata reports NOASSERTION while the README states CNC-1.0.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. yukkcat/gemini-business2api on GitHub