Files
universal-web-api/README.en.md
T
2026-11-02 22:54:14 +08:00

16 KiB

Universal Web API logo

Universal Web API

Universal  ·  Simple  ·  Local

English   /   简体中文


Current release: 3.0.1 (see VERSION; release notes in CHANGELOG-3.0.1.md)

Universal Web API is a local API bridge & debugging tool designed for developers. It converts AI web services (e.g., ChatGPT, DeepSeek, Claude, Gemini) logged in your local browser into local standard OpenAI/Anthropic-compatible APIs.

This project is dedicated to helping developers perform workflow orchestration, client integration testing, and personal office automation locally, ensuring data privacy and security without exposing API keys to third parties.

⚠️ Compliance & Security Statement: This tool runs entirely on the user's local system as a bridge helper. It does not provide any functionality to bypass authentication (login), crack security defenses (such as captcha solvers), or reverse-engineer encrypted APIs. Users must log into their own valid accounts in the controlled browser. Do not use this tool for high-frequency automated requests or commercial purposes.


📐 Project Architecture (Mermaid)

graph TD
    User([Client/User]) -->|OpenAI/Anthropic/Codex API| Route[1. API & Routing Layer app/api]
    Route -->|Session Dispatch/Concurrency| TabPool[2. Tab Pool & Lifecycle app/core/tab_pool]
    Route -->|Parse Tool Request| ToolCall[5. Tool Calling Adapter app/services/tool_calling]
    TabPool -->|Browser Control/Anti-detection| Browser[3. Automation & Workflow Engine app/core/workflow]
    Browser -->|Monitor Stream| Stream[4. Stream Monitor & Parsers app/core/parsers]
    Browser -->|Trigger Command Hook| CmdEng[6. Command Engine app/services/command_engine]
    
    subgraph Core Utilities
        Config[7. Config & Presets app/services/config]
        Utils[8. Shared Utilities app/utils & app/models]
    end
    
    Browser -.->|Depends| Config
    CmdEng -.->|Read/Write| Config
    Stream -.->|Helpers| Utils

🌟 Highlights

  • ⚡ Zero-config Standard Compatibility: Fully compatible with OpenAI standard API (including /v1/chat/completions and /v1/models) with experimental compatibility support for third-party developer tools (such as /v1/messages connectivity testing for Claude Code and /v1/responses endpoint for Codex plugins).
  • 🛠️ Local Controlled Browser Drive: Lightweight automation of Chromium-based browsers (Chrome / Edge, etc.) using DrissionPage. All data stays local for end-to-end privacy.
  • 🛡️ Human-like Interaction: Built-in keyboard keypress simulations, focus emulation, and mouse path movements to minimize account detection.
  • 📦 Intelligent Tab Pooling: Multi-tab concurrency with default, domain, fixed-tab, exact-URL, and URL-bound preset routes, plus first-idle, round-robin, and random allocation modes.
  • 📡 Dual-channel Stream Parsing: Combined CDP network interception and DOM mutation monitoring to stream increments in real-time, regardless of the site's rendering technique.
  • 📎 Multimodal & Attachment Self-healing:
    • Extract and download text, images, audio, and video content locally from web sessions.
    • Oversized prompts are automatically staged as local temporary files for upload (for sites that handle file-style inputs better).
  • 🧩 Robust Tool Calling: Injects schema verification feedback loops into web sessions. If a web model produces invalid arguments, it automatically triggers local correction prompts, boosting tool-calling reliability.

🚀 Quick Start

Prerequisites

  1. OS: Windows (Fully supported) / macOS or Linux (Core features supported)
  2. Requirements: Python 3.10+ and a Chromium-based browser (Chrome, Edge, or Brave) installed.

Setup Steps

  1. Download & Extract: Download the latest release from Releases and extract it to a path without non-ASCII (e.g. Chinese) characters.
  2. Start the Service:
    • Windows: Double-click start.bat.
    • macOS / Linux: Run python3 start.py in your terminal.
  3. Initialization: Once dependencies are validated and installed, a controlled browser window will pop up automatically, and the console will open in a normal browser at http://127.0.0.1:8199. Keep AI websites in the controlled browser, and use your normal browser for the dashboard and tutorial.
  4. Log In: In the controlled browser, log in to your own AI web accounts (e.g., chatgpt.com, claude.ai), then keep the target site on a real chat-ready page.
  5. Configure Clients: In any client, set the API configurations:
    • Base URL: http://127.0.0.1:8199/v1
    • API Key: If service API auth is disabled (AUTH_ENABLED=false), use any value (e.g., sk-local). If enabled, use AUTH_TOKEN. The dashboard uses the separate DASHBOARD_AUTH_TOKEN; do not share it with API users.

Verify the first request

Run these checks from a terminal after at least one controlled-browser tab is logged in:

# Service and model discovery
curl http://127.0.0.1:8199/v1/models

# Non-streaming smoke test
curl http://127.0.0.1:8199/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"web-api","messages":[{"role":"user","content":"Reply with OK"}],"stream":false}'

For Windows PowerShell, use Invoke-RestMethod or keep the JSON in a file to avoid shell quoting issues. A real chat request is a better connectivity test than a client's short “test API” request, because some sites reject very short prompts.

Supported API surfaces

Endpoint Compatibility Notes
POST /v1/chat/completions OpenAI Chat Completions Streaming SSE, multimodal message parts, tool-calling repair
POST /v1/responses OpenAI Responses (experimental) input, instructions, tools, and previous_response_id are translated to the browser workflow
POST /v1/messages Anthropic Messages (experimental) Accepts Authorization or x-api-key; includes count_tokens compatibility
GET /v1/models OpenAI model listing Returns generic models plus models discovered from active tabs

All endpoints are local by default. Route a request to a specific site or tab with /url/{domain}/v1, /tab/{index}/v1, or /tab-url/{token}/v1; see the routing guide for precedence and examples.


🎯 Supported Sites

Built-in automation rules are available for several mainstream AI websites. For unlisted sites, you can use the built-in AI assistant to analyze page DOM structures and generate adaptations. See Add a New Site Guide.

Site Name URL Notes
ChatGPT chatgpt.com Supports extremely long prompts via file uploads
DeepSeek chat.deepseek.com Adapted for reasoning/thinking stream output extraction
Gemini gemini.google.com Excellent for testing local multimodal workflows
Claude claude.ai Comprehensive page interaction and attachment handling
Kimi www.kimi.com Excellent long-context file-paste support
Qwen chat.qwen.ai DOM rules adapted for domestic LLM web automation
Grok grok.com Decodes native websocket/HTTP stream response data
Doubao www.doubao.com Fully adapted for the latest page structures
AI Studio aistudio.google.com High-throughput developers testing environment
Arena AI arena.ai Comparative debugging (sensitive to IP quality)

📖 Documentation

Detailed HTML guides are hosted locally and can be accessed via the dashboard after launch:

Section Description
📖 Full Tutorial Installation, platform differences, and UI dashboard guides
🔗 Connect API Request parameters, routing modes (Default, Domain, Fixed Tab, Exact URL, URL-bound Preset), and code examples
🧩 Function Calling Validation repair strategy and multi-turn prompt engineering explanations
🔄 Tab Pool and Presets Configuring concurrency, route methods, allocation modes, and custom task presets
📊 Request Monitor Inspect request history, failure details, per-site success rates, and debug stuck tasks
🧾 API Endpoint Reference Health, model, provider, OpenAI, Responses, and Anthropic endpoint quick reference
🛠️ Core Selector Configuration CSS selector mapping, visual workflows, and streaming options
🛡️ Stealth & Advanced Options Anti-detection settings, browser fingerprint overrides, and low-interference modes
❓ Limitations & FAQ Timeout troubleshooting, captcha handling, and OS differences
🔐 Security Boundary Local binding, authentication, CORS, DevTools, and sensitive-data handling

The tutorial is bundled as static HTML, so it also works without an internet connection. Open static/tutorial/index.html directly, or use the dashboard's Tutorial entry after startup.

⚙️ Configuration Essentials

Copy .env.example to .env only when you need to override defaults. Values are read at process start; restart start.bat / start.py after changing environment settings.

Variable Recommended local value Purpose
APP_HOST 127.0.0.1 Bind to localhost. Use 0.0.0.0 only behind a trusted firewall/reverse proxy. A non-loopback bind without both API and dashboard auth refuses to start (override: ALLOW_INSECURE_PUBLIC_BIND=true).
APP_PORT 8199 Dashboard and API port.
APP_DEBUG false Enable /docs, /redoc, and detailed errors only for local debugging.
AUTH_ENABLED false Require a Bearer token or X-API-Key for API calls.
AUTH_TOKEN a long random token API credential when authentication is enabled.
DASHBOARD_AUTH_ENABLED false Protect the dashboard independently from the API.
DASHBOARD_AUTH_TOKEN a separate token Dashboard credential; never reuse it for client integrations.
CORS_ENABLED false Keep disabled for same-origin local clients; enable only when a browser client needs cross-origin access.
CORS_ORIGINS empty Empty = no cross-origin web page may call the service (the dashboard is same-origin). Browser requests from origins not listed here are rejected with 403. List explicit trusted origins instead of *.
BROWSER_PORT 9222 Chromium remote-debugging port used by the controlled browser.
PROXY_ENABLED false Send controlled-browser traffic through PROXY_ADDRESS.
PROXY_ADDRESS http://127.0.0.1:7890 HTTP or SOCKS5 proxy URL.
HELPER_API_KEY empty Optional key for AI-assisted site analysis.

Never commit .env, chrome_profile/, logs, or exported site configurations containing cookies or tokens. If the service is reachable from another machine, enable both API and dashboard authentication and restrict access at the network layer.

🧭 Routing and Presets at a Glance

The request body model is primarily a display/routing hint; the actual model is the one available in the selected web session. Presets control selectors, workflow, stream parsing, file handling, and media extraction for a site.

Default pool       /v1/chat/completions
Domain route       /url/gemini.google.com/v1/chat/completions
Fixed tab          /tab/1/v1/chat/completions
Exact URL token    /tab-url/{token}/v1/chat/completions
Domain + preset    /url/gemini.google.com/pro/v1/chat/completions

When several tabs match, allocation follows the configured first_idle, round_robin, or random mode. A request-level preset_name overrides the tab's default for that request only.

🧰 Troubleshooting Checklist

  1. The dashboard does not open: confirm Python 3.10+, the Chromium browser, and that port 8199 (and debugging port 9222) are free. Read the terminal output and logs/ before restarting.
  2. The tab is missing from the pool: wait for the page to finish loading, close chrome://newtab and unrelated tabs, then use “Refresh tabs” in the dashboard.
  3. Input or send fails: the site likely changed its DOM. Test input_box, send_btn, and result_container separately in the selector workbench, then save the preset.
  4. The response is empty or times out: keep the controlled browser visible, avoid interacting with it during a request, check for captcha/rate-limit pages, and try DOM stream mode if network interception has no matching traffic.
  5. Requests queue forever: inspect Request Monitor for acquire_timeout or a stuck tab; cancel the request or use the force-release debug action only as a last resort.
  6. Authentication returns 401/403: send Authorization: Bearer <AUTH_TOKEN> (or X-API-Key) and verify AUTH_ENABLED is a boolean string (true/false), not a placeholder such as your-secret-here.

Do not attempt to bypass a site's login or human verification. Complete challenges manually in the controlled browser and lower request frequency when a site applies rate limits.

🧪 Development and Tests

python -m venv venv
# Windows: .\\venv\\Scripts\\Activate.ps1
# macOS/Linux: source venv/bin/activate
pip install -r requirements.txt
pytest -q

Most tests are browser-independent regression tests under tests/. A live browser session is required for end-to-end site adaptation tests. Keep generated profiles and logs outside commits.

🔄 Upgrading Safely

Before upgrading, back up config/, chrome_profile/, .env, and any custom scripts. The updater preserves user data listed in UPDATE_PRESERVE and supports a configurable update whitelist in the dashboard. After upgrading, review the latest CHANGELOG-<version>.md (currently CHANGELOG-3.0.1.md), rerun the DrissionPage patch when prompted, and send one real smoke-test request before resuming normal traffic.


🤝 Feedback & Discussion

  • If you run into issues, join the QQ Group 1073037753.
  • You can also open issues or suggest features in the GitHub Issues tracker.

⚖️ Disclaimer

  1. Purpose: This project is intended solely for personal technical research, educational demonstration, and testing. Do not deploy it in production environments or use it for commercial profit-making activities.
  2. Compliance: Before using this software, read and comply with the target sites' Terms of Service. Users are solely responsible for account limitations, suspensions, or disputes arising from using this automation tool.
  3. No Hacking: This software does not engage in network intrusion, cracking, reverse engineering of APIs, or bypassing payment walls. All interactions are achieved by automating actions in a legitimate browser owned and logged in by the user.
  4. Liability: The maintainers assume no liability for any direct or indirect damage or loss (including account bans, business losses, or data loss) resulting from using this software.

📄 License

This project is licensed under the AGPL-3.0.