lumingya/universal-web-api

Universal Web API – Bridge AI web‑UIs to OpenAI/Anthropic‑compatible local APIs

What it is

• A locally‑run service that controls a Chromium browser, logs into AI chat sites (ChatGPT, Gemini, Claude, etc.) and re‑exposes the web UI as standard OpenAI‑compatible (/v1/chat/completions, /v1/models) and Anthropic‑compatible (/v1/messages) endpoints.
• Acts as a debug/bridge layer: your own client can call the familiar OpenAI/Anthropic HTTP API, while the service forwards the request to the real web page, parses the DOM or network traffic, and returns JSON or Server‑Sent Events.

Key features

• OpenAI & Anthropic compatibility – supports chat completions, model listing, token‑count, streaming SSE, tool calls, multimodal inputs, and experimental /v1/responses.
• Multi‑site support – pre‑configured for ChatGPT, DeepSeek, Gemini, Claude, Kimi, Qwen, Grok, Doubao, AI Studio, Arena AI, with a UI to add new sites via DOM rule generation.
• Routing flexibility – automatic model‑based routing, explicit site‑based URLs, tab‑index routing, URL‑token routing, and group routing.
• Tab‑pool management – a pool of browser tabs is kept alive, each can be assigned to a request, with lifecycle, health, and log monitoring.
• Local control panel – web dashboard (http://127.0.0.1:8199/) shows browser status, request history, logs, and lets you edit sites.json or presets on the fly.
• Security options – optional bearer‑token / API‑key auth, CORS control, optional public bind with hardened token requirements, and clear guidance on firewall / TLS when exposing the service.
• Extensible configuration – environment variables (.env), JSON site rules, proxy support, scheduled restarts, profile cleaning, etc.

How it works (high‑level flow)

1. Client → FastAPI endpoint (app/api).
2. FastAPI asks the tab‑pool (app/core/tab_pool) for a free browser tab.
3. The tab is driven by DrissionPage (a Chromium driver) (app/core/workflow).
4. Site‑specific parsers (app/core/parsers) read network responses or DOM to extract the AI model’s reply.
5. The service formats the reply as JSON or SSE and returns it to the client.

Quick start

# 1. Download a release, unzip to a folder with an English‑only path.
# 2. Windows: double‑click start.bat
#    macOS/Linux: python3 start.py   # or python main.py (no auto‑checks)
# 3. The script installs the Python deps, launches a controlled Chromium profile, and opens the dashboard at http://127.0.0.1:8199/
# 4. Log into the target AI site in the controlled browser.
# 5. Point your own client to http://127.0.0.1:8199/v1 and pick a model from GET /v1/models.

Example API call (OpenAI style)

curl http://127.0.0.1:8199/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}],"stream":false}'

• Add -H "Authorization: Bearer <TOKEN>" or -H "X-API-Key: <TOKEN>" if auth is enabled.
• Set "stream": true for SSE output.

Configuration highlights

Variable	Default	Purpose
APP_HOST	127.0.0.1	Bind address (use 0.0.0.0 only with auth & firewall).
APP_PORT	8199	Port for API, dashboard, and tutorial.
AUTH_ENABLED / AUTH_TOKEN	false / empty	Toggle bearer‑token / API‑key protection.
CORS_ENABLED / CORS_ORIGINS	true / empty	Control cross‑origin access.
BROWSER_PATH	auto‑detect	Path to Chrome/Edge/Brave binary.
BROWSER_PROFILE_DIR	project folder	Separate Chromium profile for isolation.
SITES_CONFIG_FILE	config/sites.json	JSON file defining site rules, presets, and routing groups.

Typical use‑cases

• Local development of an OpenAI‑compatible client when you only have access to a web‑only AI service.
• Testing tool‑call integration against Claude, Gemini, or other web‑based models without needing official API keys.
• Debugging multi‑modal interactions (image upload, file paste) by inspecting the underlying DOM.

Limitations / cautions

• Designed for single‑machine debugging, not for multi‑tenant production gateways.
• Must keep the controlled browser logged in; any login‑challenge, CAPTCHA, or account lock will break the bridge.
• Exposing the service publicly requires strong auth, CORS restrictions, firewall rules, and preferably a reverse‑proxy with TLS.
• The tool may violate the terms of the target AI website; users assume all risk.

License

• AGPL‑3.0 (see LICENSE).

Support

• Open issues on GitHub, or join the QQ group 1073037753 for community help.

---

All details above are taken directly from the repository’s README; no additional features have been inferred.