gpt-web-gateway

OpenAI-compatible API gateway backed by the ChatGPT.com web UI. A headless Real Google Chrome (patchright — a patched Playwright fork) drives a real ChatGPT session and exposes it as familiar REST endpoints: chat completions (with thinking modes), image generation and image editing.

Read the Disclaimer before using this project. Automating the ChatGPT web UI violates OpenAI's Terms of Use and can get the account banned. Use a dedicated account with its own Plus/Pro subscription.

Why this instead of chat2api-style projects

Most "ChatGPT as API" projects reverse-engineer the private backend-api endpoints. That approach is fast but brittle: every token-format or endpoint change breaks it. This project takes the other trade-off — it runs the real browser UI with real Google Chrome driven by patchright:

• Survives redesigns better — it clicks what a human clicks; selectors are written with multiple fallbacks (EN + RU UI strings) and a capabilities probe reports what the current UI actually supports.
• Images — generation and editing (multipart uploads, reference images, batches up to 10, aspect ratios) through the same UI a Plus user sees.
• Thinking modes — instant / standard / extended mapped onto the ChatGPT "intelligence" picker, with an applied echo block so clients can verify what was really activated.
• Operational hardening — request queue with Retry-After, typed errors (error_kind / should_retry / verbatim model_message), Prometheus metrics, liveness endpoint with stuck-detection and self-healing browser resets, adaptive timeouts that only extend while the page shows live progress.

Quickstart

Never expose this gateway without authentication. With API_KEY unset the gateway is open, and /login is not a login form — it is a remote-control surface for the browser: screenshots out, clicks, keystrokes and "save session" in. Anyone who can reach that path can drive a browser that is already signed in to your ChatGPT account, read your conversations and take the session cookies with them. Set API_KEY, put auth on your reverse proxy, or bind the port to localhost — and note that /, /images/*, /health and /metrics stay outside API_KEY by design, so a public deployment needs the proxy.

1. Docker run

docker build -t gpt-web-gateway .
docker run -d --name gpt-web-gateway \
  -p 3000:3000 \
  -v "$PWD/auth:/app/auth" \
  -v "$PWD/images:/app/public/images" \
  -e HEADLESS=false \
  -e API_KEY=change-me \
  gpt-web-gateway

2. docker-compose

cp .env.example .env   # set API_KEY and (optionally) auto-login credentials
docker compose up -d

3. Log in once

Open http://localhost:3000/login — a remote-login UI streams browser screenshots so you can complete the ChatGPT login (including SSO/2FA) on a headless server. The session is persisted to the auth/ volume.

Alternatively, set CHATGPT_EMAIL, CHATGPT_PASSWORD and (for 2FA) CHATGPT_TOTP_SECRET — the gateway logs in automatically and re-logs-in when the session expires.

4. Use it

# Chat completion
curl -u "api:$API_KEY" -X POST http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Answer with one word: OK"}],"thinking_mode":"instant"}'

# Image generation
curl -u "api:$API_KEY" -X POST http://localhost:3000/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a red sports car on a mountain road, photorealistic","aspect_ratio":"16:9"}'

Works with the OpenAI SDK too:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:3000/v1", api_key="change-me")
result = client.images.generate(prompt="a cat in space", n=1)
print(result.data[0].url)

Endpoints

* the web UI at / and generated images under /images/ are not covered by API_KEY — protect them at your reverse proxy if the gateway is exposed publicly. Generated images are served to anyone who knows (or guesses) the id, and they are never expired: give the volume a retention policy of your own if the prompts that produced them are sensitive.

All responses include an applied echo block (what was really activated in the UI, e.g. applied.thinking_verified) next to requested, so clients can detect silent degradation when the ChatGPT UI changes.

Automatic tier downgrade (Pro → Extra High)

The Pro tier has its own quota and it runs out. When a thinking_mode=pro request cannot actually get Pro, the gateway serves it on the next tier down rather than running at whatever level the composer happened to show:

"applied":   { "thinking_mode": "extra_high",   // what really ran
               "thinking_verified": true,       // ...and the UI confirmed it
               "requested_verified": false,     // but it is NOT what was asked for
               "thinking_fallback": { "from": "pro", "to": "extra_high",
                                      "reason": "quota", "verified": true } },
"requested": { "thinking_mode": "pro" }         // unchanged: what the caller asked

thinking_verified refers to applied.thinking_mode. After a downgrade it is true because Extra High really is active — read requested_verified (or the presence of thinking_fallback) to know whether the requested tier was applied.

reason is one of quota / disabled / not-offered / click-not-applied / cooldown:<earlier reason>, or empty_turn when the answer came from the instant resend of an empty turn (to: "instant"). Only strong evidence memoizes the tier as gone (TIER_UNAVAILABLE_COOLDOWN_SEC): an explicitly disabled item or the post-submit limit notice immediately, a missing menu item after two consecutive sightings, a single unverified click never. A memo never overrides reality — if the pill already shows Pro, Pro is used and the memo is dropped.

Two limits worth knowing:

• The downgrade is decided before the prompt is sent. If ChatGPT only reveals the exhausted quota after submission (a limit notice instead of an answer), that request fails with error_kind: tier_limit (HTTP 503, `should_retry: true`) — the prompt is already submitted, and re-sending it silently is how you get duplicate generations. The tier is memoized at that moment, so a retry and every request after it are downgraded automatically. On an image turn the same notice is told apart from the image-creation limit, so it raises tier_limit rather than the global-cooldown rate_limit.
• A batch (n > 1) can straddle the boundary. thinking_verified and requested_verified are true only if every image confirmed it, and applied.thinking_mode_mixed marks a batch whose images did not all run on the same tier (applied.thinking_mode then describes the first one).
• tier_limit is deliberately not rate_limit: that kind arms a global cooldown that blocks every endpoint for 30 minutes, while this affects one tier.

Set TIER_FALLBACK_PRO=off to disable the downgrade entirely.

Multi-turn conversations (conversation_id)

Text responses from /v1/chat/completions and /v1/responses always include a top-level conversation_id (the ChatGPT conversation UUID, or null when it could not be determined). Pass it back in the next request to continue the same conversation instead of starting a new chat:

curl -s localhost:3000/v1/chat/completions -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"My name is Ada. Remember it."}]}'
# → { ..., "conversation_id": "1f0e4b2a-...", ... }

curl -s localhost:3000/v1/chat/completions -H 'Content-Type: application/json' \
  -d '{"conversation_id":"1f0e4b2a-...","messages":[{"role":"user","content":"What is my name?"}]}'

Notes:

• Backward compatible: omit conversation_id and every request is a fresh chat (previous behavior, unchanged).
• The id must be a UUID exactly as returned earlier — anything else is rejected with 400 (invalid_request).
• Conversations live inside the logged-in ChatGPT account: ids from another account (or deleted chats) fail with page_load_failed. Treat the id as valid only for the lifetime of that account session.
• When continuing a conversation, send only the NEW user message — the history already lives in the ChatGPT chat itself.

Streaming (stream: true)

POST /v1/chat/completions accepts OpenAI-style stream: true and answers with text/event-stream of chat.completion.chunk events (delta.content pieces, then a finish_reason: "stop" chunk carrying conversation_id, then data: [DONE]). Errors after the stream started are sent as a terminal data: {"error": ...} event.

Streaming requires backend-api reading (READ_VIA_BACKEND_API, on by default) — the intercepted backend-api SSE deltas are the streaming source. If the server was started with READ_VIA_BACKEND_API=0, stream: true is rejected with 400 instead of faking a stream. /v1/responses does not support streaming.

Advanced features

These automate unofficial ChatGPT internals (/backend-api/*); endpoints may drift with ChatGPT updates, so each one degrades gracefully (logs + fallback to the default path) when it fails. All of them were verified against the live ChatGPT UI on 2026-07-18 (answer source, multi-turn context carry-over, SSE chunks, trim route rewrite, memory PATCH, image generation with interception active, and the DOM-only fallback path).

Error format

Every endpoint returns a uniform error shape:

{
  "ok": false,
  "error_kind": "refused",
  "should_retry": false,
  "model_message": "verbatim refusal/banner text from the ChatGPT UI",
  "error": { "message": "...", "type": "server_error" }
}

Environment variables

Deployment notes

• Volumes: auth/ holds the ChatGPT session cookies — treat it like a password and keep the volume private. It also holds auth/diag/, the rotated auto-login failure reports (see below), which is why they survive a restart. public/images/ holds generated images served at /images/<id>.png.
• Kubernetes: an example Helm chart lives in helm/ (ingress with Basic auth, PVCs for session+images, liveness probe on /health/live). Values are generic placeholders — set your own registry and host.
• Memory: the chart requests 1 Gi and limits 3 Gi. Chromium alone peaked at ~1.7 GiB over 48 h of light production traffic, so a 2 Gi limit leaves very little headroom for a long batch.
• Prometheus: metrics are emitted under the gpt_web_gateway_* prefix (kept stable for dashboard compatibility).

Monitoring: is the gateway actually logged in?

/health and /health/live deliberately do not depend on the ChatGPT session (a dead session must not remove the only replica from the Service, and a restart does not fix an expired cookie anyway). So a pod can be Running, both probes 200, and every real request still failing — that exact combination hid a 34 h outage on 2026-07-25.

The session state is exported instead:

Recommended alert: gpt_web_gateway_session_valid == 0 for ~10 min (critical — nothing will work until the session is restored), optionally paired with gpt_web_gateway_session_check_age_seconds > 1800 (we have not been able to tell for half an hour).

The value is refreshed by every request and, independently of traffic, by a watchdog every SESSION_WATCHDOG_INTERVAL_SEC. The watchdog is read-only: it issues the same GET /api/auth/session the app already makes, from the page that is already open — it never navigates, clicks, clears cookies or logs in. It skips a tick while the pool is not empty (a job is running or waiting) or a manual login holds the browser, so it cannot interleave with a request.

When it fires, check the pod log for [auto-login] BLOCKED by <blocker> and the artifacts in auth/diag/: each failed login writes login-fail-<timestamp>-<step>.json (URL, on-page banners, visible buttons, which inputs were present) plus a screenshot with form fields and any plaintext occurrence of the configured e-mail masked. Credentials, e-mail addresses and auth tokens are redacted from every field. The same class is returned to the caller as login_blocker / login_step in the error body. A session that cannot be re-established headlessly (captcha, device verification) needs a manual pass through the /login UI.

What happens on a session the gateway cannot verify (e.g. /api/auth/session unreachable): the page is rebuilt and re-probed once before the verdict is accepted at all. A page that has been sitting idle gets its in-page XHRs challenged while a freshly navigated one does not, so an inconclusive answer is usually a stale page rather than a dead session — re-navigating turns it back into a definitive one.

If it is still inconclusive, the request fails closed with a retryable login_failed and the cookies are left untouched. After SESSION_UNKNOWN_ESCALATE inconclusive checks in a row the browser context is rebuilt from session.json — non-destructive, the cookies survive — so a permanently unverifiable session cannot wedge the gateway forever. Only a confirmed logout ever re-logs in, because that is the only state that justifies clearSession(); escalating on inconclusiveness used to wipe a live session and then fail to log back in, since a clean login is what Turnstile blocks.

Limitations

• A few tabs, not a farm. Up to MAX_CONCURRENT_JOBS jobs run at once (1..5, default 3), each on its own browser tab, in FIFO order. Further jobs wait, and MAX_QUEUE_SIZE caps that waiting list. Each tab keeps its own MIN_JOB_GAP_SEC after a turn finishes. A shared cooldown still stops every tab when ChatGPT rate-limits the account. MIN_TURN_STAGGER_SEC spaces the moments tabs start a turn. It is a personal/team gateway, not a high-throughput proxy.
• Streaming needs backend-api reading. stream: true works only while READ_VIA_BACKEND_API is enabled (the default; see "Advanced features"); images do not stream.
• Multi-turn is chat-only. conversation_id continues text conversations; image requests are a fresh chat each time (batch image requests share one chat for consistency).
• UI coupling. OpenAI redesigns the ChatGPT UI regularly; selectors have fallbacks and the capabilities probe reports drift, but breakage is possible at any time.
• Your account's limits apply. This does not bypass OpenAI rate limits or paywalls — you need your own Plus/Pro subscription, and the gateway applies cooldowns when ChatGPT rate-limits the account.
• Model choice is not exposed; the model field is accepted and ignored.

Disclaimer

This project automates the ChatGPT web interface, which violates OpenAI's Terms of Use (automated access outside the official API). Using it may get the ChatGPT account suspended or banned without warning.

• Use a dedicated account, never your main one.
• You need your own paid subscription (Plus/Pro); this is not a way to avoid paying OpenAI.
• The session cookies stored in auth/ grant full access to the account — keep that volume private and never commit it.
• Provided as-is, for educational purposes, with no warranty of any kind. You are solely responsible for how you use it.

See SECURITY.md for security notes and reporting.

Development

# Install deps once (tests import modules that require playwright-extra,
# but never launch a browser — skip the browser download)
docker run --rm -v "$PWD":/app -w /app -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 node:24-slim npm ci --omit=dev

# Run tests (pure node:assert scripts, no browser needed)
docker run --rm -v "$PWD":/app -w /app node:24-slim npm test

License

MIT

Local Docker file ownership

Run Compose as the owner of the working copy. Before the first launch:

export APP_UID="$(id -u)" APP_GID="$(id -g)"
mkdir -p auth public/images
docker compose up -d

The default UID/GID is 1002:1002 (deploy on onyx). Bind sources must exist; Compose will fail instead of creating missing directories as root. Prepare the project’s .env and other required configuration before starting the service.

Edit on GitHub · 2026-10-30