your Gemini subscription,
as an API you can call

1Why this exists

You already pay for a Gemini plan, and the web app will happily generate images and answer prompts all day. But the moment a cron job, a Cloudflare Worker, or a Telegram bot wants the same thing, you are back to buying metered API credits for capability you already own.

This service sits in between: a headless browser stays logged in, and your callers speak plain HTTP. One login, many consumers, no per-image billing. Output images get their visible watermark removed automatically, and the full-resolution file is pulled from the download button rather than the scaled-down page render.

2What you get

3Install

Use uv or pipx — a plain pip install gives Playwright no isolated environment and the browser download fails.

uv tool install gemini-web
gemini-web install          # downloads the Chromium build Playwright drives
gemini-web login            # opens a real browser; sign in to Google, press Enter

The login step needs a desktop session (or X forwarding over SSH) because you type the password yourself. Session state lands in ~/.gemini-web/profiles/ and is reused from then on. Adding a second account is gemini-web login -w 1, a third is -w 2, and so on.

gemini-web serve --host 0.0.0.0 --port 8070

There is a systemd unit in scripts/install-service.sh for the always-on case.

4Use

# chat
curl -X POST http://localhost:8070/api/chat \
  -H 'Content-Type: application/json' \
  -H 'x-goog-api-key: gmw_<your-key>' \
  -d '{"prompt": "explain quantum mechanics"}'

# text to image
curl -X POST http://localhost:8070/api/generate \
  -H 'Content-Type: application/json' \
  -H 'x-goog-api-key: gmw_<your-key>' \
  -d '{"prompt": "a poster of Taipei 101"}'

# image to image (reference photo in, edited image out)
curl -X POST http://localhost:8070/api/edit \
  -H 'Content-Type: application/json' \
  -H 'x-goog-api-key: gmw_<your-key>' \
  -d '{"prompt": "redraw as a 3x3 sticker sheet", "reference_image": "data:image/png;base64,..."}'

Or keep your existing SDK code and repoint it:

from google import genai

client = genai.Client(
    api_key="gmw_<your-key>",
    http_options={"api_version": "v1beta", "base_url": "http://localhost:8070"},
)
print(client.models.generate_content(model="gemini-2.5-flash", contents="Hello").text)

Once you have issued a single key, every endpoint above requires x-goog-api-key. Before that first key exists the service stays open, so local development is not blocked — but anything reachable from the internet should have a key from day one. The browser path spends the subscription quota of whichever account is logged in, and there is no per-key rate limit to save you.

5Multi-account worker pool

Set WORKER_COUNT=N and the service starts N browsers, each on its own profile directory and therefore its own Google account. Every worker handles one request at a time, so N is both your concurrency and the number of quotas you are spreading load across. Measured cost is roughly 0.6–0.7 GB of RAM per worker.

The mode is a dropdown in the admin Overview, stored in the database and kept across restarts.

One thing worth knowing before you scale up: the same Gemini web app looks different to different accounts. Menu entries vary, an account using upload for the first time gets an extra consent dialog, and finished images arrive either as a blob or behind a download button. So "one worker is broken while the rest are fine" is normal, and login is usually not the culprit. The per-worker 24 h success rate in the admin exists precisely so that this is visible at a glance instead of hiding behind a fallback.

6What is in the admin

/admin, behind a password and an HMAC session cookie:

• Overview — requests, succeeded, failed, queued plus running, uptime, and a table of workers with account, alive, logged-in, busy and 24 h success rate. Dispatch mode switches here.
• API Keys — issue gmw_<token> keys per caller, disable or delete them. The raw value is shown once; the server keeps a sha256 hash. Keys from API_KEYS in the environment still work and are listed read-only.
• Test — run generate, edit or chat by hand, reference image upload included, so you can reproduce a caller's failure without touching their code.
• History — the last 500 requests with the key, the worker, the duration, links to output images, and when those images get swept. Prompt and error show their first 90 characters inline, so a page of failures is readable without opening every row.

7Optional paid fallback

The browser path is single-threaded per account, takes 30–120 s, and breaks whenever Gemini reshuffles its UI. If that is too fragile for a given caller, set GEMINI_OFFICIAL_API_KEY and the service can hand the request to the official Gemini Developer API instead: about 10 s, and metered.

• GEMINI_OFFICIAL_MODE=off — never.
• fallback (default) — only after the browser path fails.
• primary — always, skipping the browser entirely.
• ?official=1 forces it for a single call.

The paid path always requires a valid key, so an open endpoint can never be used to run up your bill. Do watch the flip side: in fallback mode a broken worker is invisible from outside — callers still get their image, just off the metered API. That is what the success-rate column in the admin is for.