Gemini Business2API: an OpenAI-compatible gateway for Gemini Business accounts

What Gemini Business2API actually replaces

Gemini Business is a browser-facing product, not an API surface. The README positions this project as the bridge: it converts Gemini Business into an OpenAI-compatible gateway, so an existing OpenAI SDK or middleware layer can point at it without code changes. The audience is narrow and specific. You need Gemini Business accounts already, and you need a client that speaks /v1/chat/completions rather than Google's own protocol. The README does not describe how to obtain Business accounts, and it does not claim the gateway works without them. That boundary matters more than the feature list, because everything downstream depends on credentials the project itself does not supply.

The scope was deliberately narrowed. Since v0.3.0 the mainline repository keeps only the 2API service, the admin panel, and an optional refresh-worker. The registration tooling, the registration flow, the in-service refresh executor and the old browser-dependent path were removed or moved out. If you are looking for an account-creation tool, this repository is not it anymore, and the README says so in a notice rather than leaving it implicit.

How the gateway, account pool and database fit together

The architecture diagram in the README splits the system into two entry paths. An OpenAI-compatible client hits the 2API gateway; an administrator hits the frontend, which talks to admin APIs. Both converge on a domain layer that holds the account pool, the configuration centre, scheduling, monitoring and logs. That layer persists to SQLite or PostgreSQL and to a data directory on disk.

The scheduling piece is where the multi-account claim lives. The README lists polling and availability-based switching as the dispatch modes, plus batch account management through the panel. What it does not document is the failure policy: there is no published description of what happens when every account in the pool is exhausted, or how a request is retried across accounts. Treat the balancing as a routing convenience, not a guarantee, until you have read the code path yourself.

Storage defaults to local SQLite, which the README calls the recommended option. PostgreSQL is available by setting DATABASE_URL, and the .env.example frames it as useful for multi-machine deployments or when the refresh-worker runs outside the current compose. The Dockerfile declares /app/data as a volume, and compose mounts ./data into it. SQLite database, runtime persistence, generated files and caches all land there, so that directory is your backup unit.

Installing with Docker Compose and making a first request

The README recommends Docker Compose. Clone the repository, copy the environment template, set at least ADMIN_KEY, and bring the stack up. The compose file maps port 7860 by default and mounts ./data into the container.

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 the container starts, the README gives three addresses to check. The admin panel is at http://localhost:7860/, the OpenAI-compatible endpoint is at http://localhost:7860/v1/chat/completions, and the health check is at http://localhost:7860/health. The compose healthcheck curls that same health endpoint every 30 seconds with a 10 second timeout and three retries, so a container that stays up is already answering it.

The minimum environment file is short. ADMIN_KEY is required; the rest are commented out in the example.

ADMIN_KEY=your-admin-login-key
# PORT=7860
# DATABASE_URL=postgresql://user:password@host:5432/dbname?sslmode=require
# REFRESH_WORKER_IMAGE=cooooookk/gemini-refresh-worker:latest
# REFRESH_HEALTH_PORT=8080

Once the panel is up you import accounts through the account management view. The README points to a Tampermonkey userscript at tools/tampermonkey/gemini-business-import.user.js for copying an importable account JSON from the Gemini Business page. It requires Tampermonkey configuration mode set to advanced and script cookie access set to All, and the README notes that the exported expires_at defaults to the current time plus 12 hours. If the script cannot detect cookie permission it shows a dialog rather than failing silently.

With accounts loaded, the client-side call is an ordinary OpenAI-shaped request against the local endpoint, using the model IDs from the README's capability table. gemini-auto, gemini-2.5-pro, gemini-3.5-flash and gemini-3.1-pro-preview handle text, image recognition, native web access and file multimodality, with image generation listed as optional. gemini-imagen is the dedicated image model and gemini-veo the dedicated video model. The README also documents /v1/images/generations and /v1/images/edits for image work.

The refresh-worker split and what it costs you

Since v0.3.0, refresh capability is not inside the main service. It lives in a separate worker image, started through a compose profile and disabled by default. The command is docker compose --profile refresh up -d, and the worker reads the same ./data volume as the main service. It exposes no business API, only a health port that defaults to 8080.

This is the most consequential design decision in the repository, and it cuts both ways. On the plus side, the main service no longer depends on a browser display environment, and a crash in the refresh path cannot take down request serving. On the minus side, the README states that the worker image comes from a separate branch, REFRESH_WORKER_IMAGE defaults to cooooookk/gemini-refresh-worker:latest, and the mainline repository does not contain that code. You are running an image whose source is not in the repository you cloned. For anyone doing dependency review, that is the first thing to resolve.

The worker's environment block in docker-compose.yml is where the interesting knobs sit: SQLITE_PATH defaults to /app/data/data.db, HEALTH_PORT to 8080, and FORCE_REFRESH_ENABLED, REFRESH_INTERVAL_MINUTES, REFRESH_WINDOW_HOURS, BROWSER_HEADLESS and PROXY_FOR_AUTH are all passed through from .env. FORCE_REFRESH_ENABLED is documented as taking priority over the panel setting. The .env.example notes that when these are left empty, the worker reads the shared values from the admin panel's system settings instead. Two configuration surfaces for the same behaviour is a real source of confusion, and the README does not spell out the precedence order beyond that one line.

Where Gemini Business2API is the wrong tool

Three cases should send you elsewhere. First, if you need a permissively licensed dependency. The project uses the Cooperative Non-Commercial License (CNC-1.0), and the repository's LICENSE file is the only authoritative text. A non-commercial licence is a hard blocker for many commercial products, and no amount of technical fit changes that. Read the licence yourself; this article is not legal advice.

Second, if you need a supported service. The last push to the main branch was on 2026-05-21, and the most recent release listed is v0.3.0 from 2026-04-24, while the README banner announces v0.3.3 as the current stable version. Those two statements do not line up, and the README does not explain the gap. Version drift between the README banner, the releases list and the VERSION file is exactly the kind of thing to check before you pin a tag.

Third, if you need a gateway that is not tied to a specific upstream product's credential lifecycle. The whole model depends on valid Gemini Business accounts, and the import helper's 12 hour expires_at default tells you how short that lifecycle can be. If your workload cannot tolerate account rotation and periodic re-authentication, the architecture is working against you.

How it differs from a generic Gemini-to-OpenAI proxy

The obvious alternative is a thin translation proxy: something that takes OpenAI-shaped requests, calls a Gemini API key, and returns OpenAI-shaped responses. That approach has one credential, no account pool, no admin panel, and no refresh worker, because an API key does not expire every few hours. It is simpler in every dimension, and if you have a standard Gemini API key it is almost certainly the better choice.

Gemini Business2API solves a different problem. It exists because Business access is seat-based and browser-oriented, so the unit of capacity is an account, not a key. Everything distinctive about the project follows from that: the account pool, the polling and availability switching, the import/export and batch operations in the panel, and the refresh worker that keeps seats alive. If you do not have Business seats, none of that machinery does anything for you.

The second difference is the multimodal surface. The README's model table separates image recognition, native web access, file multimodality, image generation and video generation per model ID, and exposes dedicated image and video endpoints. A minimal translation proxy typically covers chat completions only. Whether that breadth is worth the account-management overhead depends entirely on whether you need generated images or video from the same endpoint.

Maintenance, versioning and licence reality

Upgrades run through the published image: the compose file pins cooooookk/gemini-business2api:latest, so a restart picks up whatever latest points to. If you want reproducibility, pin a digest or a tag rather than tracking latest, because the README's own version reporting is inconsistent. The interactive installer offers a way to pin: the README shows a variant that fetches deploy/install.sh from the v0.3.3 tag instead of main, and a --with-refresh flag that only presets the refresh-worker prompt to enabled. It does not create a second install flow, and the README says so explicitly.

Data migration is the part to plan. Everything persistent lives under ./data, which holds the SQLite database, runtime state, generated files and caches. Moving from SQLite to PostgreSQL means setting DATABASE_URL and, per the .env.example, uncommenting asyncpg in requirements.txt for a source install. The README does not document a migration path between the two backends, so treat that as an open question and test it on a copy of the data directory first.

On licensing, the CNC-1.0 identifier is what the README badge and licence section state, and the repository-level licence field is NOASSERTION. That mismatch means automated licence scanners will not classify this project cleanly. If your build pipeline gates on licence detection, expect a manual review step.

Editorial conclusion

Adopt Gemini Business2API if you already hold Gemini Business seats and need a single OpenAI-shaped endpoint in front of them, and you are willing to run the account refresh path yourself. Do not adopt it if you need a permissively licensed component, a vendor-supported SLA, or a gateway that works without valid Business credentials. Before committing, verify three things in your own environment: that the admin panel loads at http://localhost:7860/ after docker compose up -d, that /v1/models returns the model IDs your client expects, and that your licence counsel accepts CNC-1.0 for your deployment.

Frequently asked questions

Official sources

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