English | 简体中文

OpenAI-compatible and Google-compatible HTTP adapter for Gemini Web, deployable on Cloudflare Workers or as a Docker service.Zero cost, cross-platform, single file.

TypeScript lives under src/, local quality gates live under scripts/, dist/worker.js is generated by pnpm build for Wrangler deployment, and scripts/docker-server.mjs provides the Docker HTTP adapter.

• web2gem
  • Contents
  • Overview
  • Core Features
  • API Surface
    • Health
    • OpenAI Chat Completions
    • OpenAI Responses
    • Google Gemini API
  • Models
  • Quick Start
    • Option 1: Deploy the release single-file Worker
    • Option 2: Deploy with Docker
  • Configuration
  • Authentication
  • Development
  • Testing
  • Project Structure
  • Security Notice
  • Acknowledgements
  • License

web2gem translates common OpenAI and Google Gemini API shapes into Gemini Web requests. It can run as a Cloudflare Worker or as a Docker-hosted Node service. On Workers it can use cloudflare:sockets for upstream HTTP transport when regular fetch paths are rate-limited; Docker deployments use standard fetch transport by default.

The main compatibility targets are:

curl https://your-web2gem.example/

Returns service status, version, and the model IDs currently exposed by the adapter.

curl https://your-web2gem.example/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [
      { "role": "user", "content": "Write a concise project summary." }
    ]
  }'

Set "stream": true to receive Server-Sent Events.

curl https://your-web2gem.example/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Explain what this worker does in one paragraph."
  }'

curl https://your-web2gem.example/v1beta/models/gemini-3.5-flash:generateContent \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "Return a short deployment checklist." }]
      }
    ]
  }'

For streaming, call :streamGenerateContent on the same model path.

web2gem exposes a fixed model map in src/models/index.ts.

You can override thinking depth per request by appending @think=N to a known model ID, for example gemini-3.5-flash@think=0. Supported override values are 0, 1, 2, 3, and 4.

Both deployment modes can run without secrets. Configure optional secrets only when you need authentication or cookie-backed Gemini Web features.

Download the release build artifact worker.js from the Releases page, open your Cloudflare Worker in the dashboard, and replace the Worker source with the contents of that file. In the Worker dashboard settings, add the nodejs_compat compatibility flag.

Each release publishes these assets:

Secrets are optional. In the Worker dashboard, open the Worker settings and add variables/secrets only for the features you need. Set API_KEYS when you want to protect shared access, and set GEMINI_COOKIE when Pro routing or large-context text attachments are needed.

If you build from source instead of using a release artifact, pnpm deploy builds dist/worker.js and deploys it through the checked-in wrangler.toml.

Use .env.example as the environment template and compose.yaml as the Compose service definition:

cp .env.example .env
docker compose up -d

The provided compose.yaml pulls ghcr.io/guardinary/web2gem:latest by default, maps ${PORT:-52389}:${PORT:-52389}, and forwards the runtime variables from .env. Set API_KEYS in .env for shared deployments, and set GEMINI_COOKIE when Pro routing or large-context text attachments are needed. To pin a specific image tag, set WEB2GEM_IMAGE=ghcr.io/guardinary/web2gem:<tag> in .env.

After the container starts, verify the local health route:

curl http://127.0.0.1:52389/

If you changed PORT in .env, use that host port instead. Docker deployments default UPSTREAM_SOCKET to false in .env.example because cloudflare:sockets is only available in the Cloudflare Workers runtime. Other runtime variables are the same as the configuration variables listed below.

For one-off local testing without Compose, you can still build and run the image directly:

docker build -t web2gem .
docker run --rm -p 52389:52389 --env-file .env web2gem

Release pages also provide prebuilt Docker image archives. Download the archive matching your platform, load it, and run the tagged image:

gzip -dc web2gem_<tag>_docker_linux_amd64.tar.gz | docker load
docker run --rm -p 52389:52389 --env-file .env web2gem:<tag>

If the upstream Gemini Web path starts returning empty output, first check whether GEMINI_BL needs to be refreshed from the current Gemini Web frontend. If Cloudflare egress is rate-limited, set GEMINI_ORIGIN to your own forwarding service or proxy endpoint.

Configuration defaults live in src/config/index.ts. Cloudflare Worker environment variables / secrets and Docker environment variables override those defaults at runtime.

When managing a Worker through the Wrangler CLI, optional secrets can be set with:

• Set API_KEYS for shared deployments. If it is empty, auth is disabled.
• Set GEMINI_COOKIE when Pro routing or large-context text attachments are needed.

wrangler secret put API_KEYS
wrangler secret put GEMINI_COOKIE

When GEMINI_COOKIE contains __Secure-1PSID, the Worker keeps an in-memory active cookie for the current isolate and lazily calls Google's RotateCookies endpoint when the cookie is stale or an authenticated upstream request fails. Refreshed cookies are kept in memory only; the Worker does not use a database for them or write them back to Worker secrets. A cold start initializes again from GEMINI_COOKIE.

For single-cookie deployments, use the shortest practical cookie form: __Secure-1PSID, __Secure-1PSIDTS, and optional SAPISID. A fresh private-browser Gemini login that is closed after extracting these values tends to be more stable than copying a full everyday-browser cookie header. If a cold start falls back to an expired __Secure-1PSIDTS, the first authenticated request will try to rotate it. If Google rejects that rotation or returns no updated cookie, update the GEMINI_COOKIE secret manually.

Short JSON cookie form:

{
  "secure_1psid": "YOUR_SECURE_1PSID",
  "secure_1psidts": "YOUR_SECURE_1PSIDTS",
  "sapisid": "OPTIONAL_SAPISID"
}

For local development, use Wrangler environment support or pass bindings through the local Worker environment.

When API_KEYS is empty, every route except Cloudflare/Wrangler infrastructure is publicly callable. For any shared deployment, set at least one API key.

web2gem accepts:

• Authorization: Bearer <key>
• x-api-key: <key>
• x-goog-api-key: <key>

The health route GET / remains unauthenticated so deployment probes can work without secrets.

Authored source lives under src/. Do not hand-edit generated files under dist/.

pnpm install
pnpm typecheck
pnpm check:arch
pnpm unit
pnpm smoke

The build script emits two bundles:

Coverage builds write sourcemapped test bundles to dist-coverage/ so normal dist/ builds and coverage runs do not share generated artifacts. Vitest discovers tests/unit/*.test.mjs wrappers for pnpm unit; shared case lists live in tests/unit/*.cases.mjs, use Vitest-backed assertions, and coverage uses Vitest's V8 provider against the isolated test bundle. pnpm coverage and pnpm coverage:ci use a Node runner so environment variables are handled consistently across Windows and Unix shells. pnpm coverage:ci also reads coverage/coverage-summary.json through scripts/check-coverage.mjs to catch regressions in key source directories and selected high-risk branch paths.

Recommended pre-commit gate:

pnpm typecheck
pnpm check:arch
pnpm unit
pnpm coverage:ci
pnpm smoke
# Optional when Docker is available:
pnpm docker:smoke

.
├── scripts/                 # Build, architecture, unit, and smoke scripts
├── src/
│   ├── completion/          # Provider-neutral completion runtime
│   ├── config/              # Runtime configuration parsing
│   ├── gemini/              # Gemini Web client, transport, uploads, provider adapter
│   ├── http/                # HTTP boundary, OpenAI and Google protocol adapters
│   ├── models/              # Exposed model map and model resolution
│   ├── promptcompat/        # API request shapes to Gemini prompt text
│   ├── shared/              # Provider-neutral utilities
│   ├── toolcall/            # Tool-call prompt, policy, parser, formatter
│   └── toolstream/          # Streamed tool-call detection state
├── tests/unit/              # Local unit checks
├── wrangler.toml            # Cloudflare Worker deployment config
└── package.json             # Node scripts and dev dependencies

This project adapts Gemini Web behavior and depends on upstream web protocol details that can change without notice. Use it for personal, research, or internal validation scenarios, and review the terms and risk profile of the upstream service before deploying it for shared use.

Never commit Gemini cookies or API keys. Store secrets in Cloudflare Worker secrets, Docker environment management, or another deployment-secret mechanism.

MIT