DOCSEARCHbyAlgolia
Submit Docs

WebAI2API Documentation

repository·main·Indexed 22 days ago

https://github.com/foxhui/webai2api

A tool that converts web-based AI services (such as LMArena, Gemini, and ChatGPT) into standard, OpenAI-compatible API services. It utilizes Camoufox (Playwright) to simulate human-like browser interactions and bypass automation detection. Features include a Pool architecture for managing browser instances, an Adapter Registry for plug-and-play AI website support, and endpoints for chat completions and cookie retrieval.

Tokens
10.6K
Snippets
32
Records
45
Agent score
77%

What's inside WebAI2API

  1. Important Migration Note: Puppeteer to Camoufox

    main

    The project has migrated its core browser automation engine from Puppeteer to Camoufox to better handle complex anti-bot detection mechanisms.

    Warning: Any code or documentation based on the older Puppeteer implementation is located in the puppeteer-edition branch. That branch is archived for reference only and is no longer updated or maintained. For all current development and usage, use the main branch which utilizes Camoufox.

  2. Deploy WebAI2API using Docker

    main

    You can deploy WebAI2API using Docker or Docker Compose.

    Note: Docker images enable Xvfb (virtual display) and VNC by default. For public environments, use an SSH tunnel or HTTPS because the WebUI transmission is unencrypted.

    Docker CLI:

    docker run -d --name webai-2api \
  -p 3000:3000 \
  -v "$(pwd)/data:/app/data" \
  --shm-size=2gb \
  foxhui/webai-2api:latest

    Docker Compose:

    docker-compose up -d
    docker run -d --name webai-2api \
  -p 3000:3000 \
  -v "$(pwd)/data:/app/data" \
  --shm-size=2gb \
  foxhui/webai-2api:latest

  3. Install and deploy WebAI2API manually

    main

    To run WebAI2API from source, ensure you have Node.js v20.0.0+ installed. Follow these steps:

    1. Install NPM dependencies:

      pnpm install

    2. Install browser and precompiled dependencies (requires GitHub access):

      npm run init

      If you are behind a proxy, use the -proxy flag:

      npm run init -- -proxy=http://username:passwd@host:port

    3. Install Linux dependencies (for Debian/Ubuntu-based systems):

      apt install -y xvfb x11vnc libgtk-3-0 libx11-xcb1 libasound2

    4. Start the service:

      • Standard start: npm start
      • Linux (with virtual display and VNC): npm start -- -xvfb -vnc
      • Login mode (disables headless/automation for manual login): npm start -- -login (-xvfb -vnc)
    pnpm install
npm run init
apt install -y xvfb x11vnc libgtk-3-0 libx11-xcb1 libasound2
npm start -- -xvfb -vnc

  4. Initialize accounts and complete login

    main

    Before using the API, you must perform a one-time manual initialization to log into the target AI websites:

    1. Connect to the virtual display:
      • On Linux/Docker: Use the "Virtual Display" section in the WebUI.
      • On Windows: A browser window will pop up automatically.
    2. Perform manual login:
      • Log in to the required AI service (check the Adapter Management in WebUI for specific requirements).
      • Send a test message to trigger and complete any CAPTCHAs or human verification.
      • Accept any Terms of Service or onboarding guides.
    3. Secure remote access (Recommended for public servers): Use an SSH tunnel to map the server's WebUI to your local machine:
      ssh -L 3000:127.0.0.1:3000 root@SERVER_IP
      Then access http://localhost:3000 locally.
    ssh -L 3000:127.0.0.1:3000 root@SERVER_IP

  6. Perform initial account login

    main

    Before using the API, you must complete the initial account login for the target AI websites via the WebUI:

    1. Connect to Virtual Display:
      • On Linux/Docker: Use the "Virtual Display" section in the WebUI.
      • On Windows: Use the browser window that pops up.
    2. Complete Account Login: Manually log in to the AI service (e.g., Gemini, ChatGPT) within the virtual browser. Trigger human-machine verification by sending a message if required, and agree to any Terms of Service.
    3. Verify: Ensure no initial obstructions (like login prompts or guides) remain.

  7. Configure WebAI2API settings

    main

    On the first run, the program copies config.example.yaml to data/config.yaml. You must restart the program for changes to take effect.

    Key configuration parameters:

    • server.port: The port the server listens on (default 3000).
    • server.auth: The API Token used for authentication for both the API and the WebUI. You can generate a key using npm run genkey.

    Example data/config.yaml snippet:

    server:
  port: 3000
  auth: sk-change-me-to-your-secure-key
    server:
  port: 3000
  auth: sk-change-me-to-your-secure-key

  8. How routing and API modes work

    main

    The global router uses path-based dispatching to handle different functional areas of the application:

    1. Static Files (WebUI): Any GET request that does not start with /v1 or /admin is treated as a request for static assets from the webui/dist directory. It supports Single Page Application (SPA) fallback by serving index.html if the requested file is not found.
    2. Admin API (/admin): Requests starting with /admin are routed to the Admin handler. This requires successful authentication.
    3. OpenAI API (/v1): Requests starting with /v1 are routed to the OpenAI-compatible handler. This route is subject to two restrictions:
      • Login Mode: If context.loginMode is true, the /v1 route is disabled and returns a 503 error.
      • Safe Mode: If context.getSafeMode() returns an object where enabled is true, the /v1 route is disabled and returns a 503 error with a reason provided by the safe mode object.

    All API routes (/admin and /v1) are protected by an authentication middleware initialized with the provided authToken.

  9. Define an Adapter Manifest

    main

    To create a new adapter, you must export a manifest object from a JavaScript file in the adapter/ directory. The registry performs strict validation on this object.

    Required Fields:

    • id: A unique string identifier for the adapter.
    • generate: A function used to generate content/requests.
    • models: An array of model objects.

    Model Object Requirements: Each model in the models array must include:

    • id: A unique string identifier for the model.
    • imagePolicy: Must be one of the values in IMAGE_POLICY (optional, required, or forbidden).

    Optional Fields for Advanced Logic:

    • targetUrl or getTargetUrl(config, workerConfig): Defines the website URL the adapter interacts with.
    • navigationHandlers: An array of functions for handling site navigation.
    • waitInput: A function to validate if the input field is ready for interaction.
    • resolveModelId(modelKey): A function to map a model key to a specific internal ID.

  10. How the Pool architecture manages browser instances

    main

    WebAI2API uses a Pool architecture to unify the management of multiple browser instances. Instead of interacting with individual browsers directly, consumers interact with a single PoolManager through the getBackend() interface.

    Key lifecycle steps:

    1. Access Interface: Call getBackend() to get the unified API object.
    2. Initialization: Call initBrowser(cfg) to instantiate the PoolManager and run initAll(). This step sets up the necessary browser environments.
    3. Execution: Use the returned context (ctx) to perform tasks like generate(). The PoolManager handles the distribution of tasks across the managed browser instances.

  11. How the Adapter Registry works

    main

    The AdapterRegistry is a central management system that automatically scans the adapter/ directory to load AI website adapters. It provides a unified interface for querying models, navigation handlers, and target URLs.

    Key Design Principles:

    • Plug-and-Play: To add a new adapter, simply add a .js file to the adapter/ directory. No framework code changes are required.
    • Manifest-Driven: Each adapter must export a manifest object that defines its identity, capabilities, and supported models.
    • Unified Interface: The registry aggregates disparate adapter logic into standard formats (e.g., OpenAI-compatible model lists).

  12. Deploy WebAI2API using Docker Compose

    main

    You can deploy WebAI2API using Docker Compose. The service exposes both the API and the WebUI on port 3000. Data and configuration are persisted in a local ./data directory, where config.yaml is automatically generated. Note that the container requires a shared memory size (shm_size) of at least 2gb to function correctly.

    services:
  webai-2api:
    image: foxhui/webai-2api:latest
    container_name: webai-2api
    restart: unless-stopped
    ports:
      - "3000:3000"  # API + WebUI
    volumes:
      - ./data:/app/data  # 数据和配置持久化，config.yaml 会自动生成到此目录
    shm_size: '2gb'
    init: true