title: WebAI2API
emoji: ๐ค
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
license: mit
tags:
- web-automation
- openai-api
- playwright
- camoufox
- ai-api
- lm-arena
- gemini
short_description: Automated tool to convert web-based AI services to OpenAI-compatible APIs
WebAI2API
็ฎไฝไธญๆ | English
This English version is translated by Gemini 3 Flash.
๐ Table of Contents
- Space Deployment Guide
- Quick Deployment
- Quick Start
- Usage
- API Reference
- Hardware Configuration Reference
๐ Project Introduction
WebAI2API is a tool that converts web-based AI services into general APIs based on Camoufox (Playwright). It interacts with websites like LMArena and Gemini by simulating human operations, providing interfaces compatible with the OpenAI format, while supporting multi-window concurrency and multi-account management (browser instance data isolation).
โจ Key Features
- ๐ค Human-like Interaction: Simulates human typing and mouse trajectories, evading automation detection through feature camouflage.
- ๐ API Compatibility: Provides standard OpenAI format interfaces, supporting streaming responses and heartbeat persistence.
- ๐ Concurrency & Isolation: Supports multi-window concurrent execution with independent proxy configurations, achieving browser-level data isolation for multiple accounts.
- ๐ก๏ธ Stable Protection: Built-in task queue, load balancing, failover, error retry, and other essential functions.
- ๐จ Web Management: Provides a visual management interface supporting real-time log viewing, VNC connection, adapter management, etc.
๐ Supported Platforms
| Website | Text Gen | Image Gen | Video Gen |
|---|---|---|---|
| LMArena | โ | โ | ๐ซ |
| Gemini Enterprise Business | โ | โ | โ |
| Nano Banana Free | ๐ซ | โ | ๐ซ |
| zAI | โ | โ | ๐ซ |
| Google Gemini | โ | โ ๐ง | โ ๐ง |
| ZenMux | โ | โ | ๐ซ |
| ChatGPT | โ | โ | ๐ซ |
| DeepSeek | โ | ๐ซ | ๐ซ |
| Sora | ๐ซ | ๐ซ | โ ๐ง |
| Google Flow | ๐ซ | โ | โ |
| Doubao | โ | โ | โ |
| To be continued... | - | - | - |
Get full model list: Use the
GET /v1/modelsendpoint to view all available models and their details under the current configuration.โ Supported; โ Not currently supported, but may be in the future; ๐ซ Website does not support, future support depends on the website's status; ๐ง Results contain watermarks that cannot be removed.
๐ Space Deployment Guide
๐ Prerequisites
- Hugging Face account
- Created Space (Docker SDK)
- Space type set to Docker
๐ ๏ธ Deployment Steps
Clone or Upload Code to Space
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME cd YOUR_SPACE_NAME git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME git push origin mainConfigure Space Settings
- Ensure SDK is set to Docker in Space settings
- Ensure public/private settings meet your requirements
Configure Environment Variables (Optional) Add the following environment variables in Space settings (if customization is needed):
PORT: Service port (default 3000)AUTH_TOKEN: API authentication key (recommended to use a strong password)
Wait for Build to Complete
- Space will automatically build the Docker image
- Build time is approximately 5-10 minutes
- Service starts automatically after build completion
Access Service
- Space URL:
https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME - WebUI: Access Space URL directly
- API:
https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME/v1/...
- Space URL:
โ ๏ธ Space Limitations
- Resource Limits: Free tier Spaces have CPU and memory limitations
- Build Time: First build requires downloading browser, takes longer
- Persistent Storage: Data is lost after Space restart (recommend using Secrets for configuration)
- Network Access: Spaces can access external websites but may have rate limits
๐ก Usage Recommendations
- First Use: Access WebUI to complete account login initialization
- Authentication: Set
AUTH_TOKENenvironment variable in Space Settings - Monitor Logs: Check running status via Space's Logs page
- Performance: Upgrade Space to paid tier for better performance if needed
๐ Quick Deployment
This project supports both source code execution and Docker containerized deployment.
๐ Environment Requirements
- Node.js: v20.0.0+ (ABI 115+)
- OS: Windows / Linux / macOS
- Core Dependency: Camoufox (automatically downloaded during installation)
๐ ๏ธ Method 1: Manual Deployment
Installation & Configuration
# 1. Install NPM dependencies pnpm install # 2. Install precompiled dependencies like the browser # โ ๏ธ This script requires connecting to GitHub to download resources. Use a proxy if network access is limited. npm run init # Using a proxy # Use -proxy to interactively input proxy configuration npm run init -- -proxy=http://username:passwd@host:portStart Service
# Standard start npm start # Linux - Start with virtual display npm start -- -xvfb -vnc # Login mode (Temporarily forces disabling headless mode and automation) npm start -- -login (-xvfb -vnc)
๐ณ Method 2: Docker Deployment
Security Reminder:
- The Docker image enables the virtual display (Xvfb) and VNC service by default.
- Connection is possible via the virtual display section of the WebUI.
- WebUI transmission is unencrypted. Please use SSH tunneling or HTTPS in public network environments.
Start with Docker CLI
docker run -d --name webai-2api \
-p 3000:3000 \
-v "$(pwd)/data:/app/data" \
--shm-size=2gb \
foxhui/webai-2api:latest
Start with Docker Compose
docker-compose up -d
โก Quick Start
1. Adjust Configuration File
On first run, the program will copy the configuration file from config.example.yaml to data/config.yaml.
Changes to the configuration file require a program restart to take effect!
server:
# Listening port
port: 3000
# Authentication API Token (can be generated using npm run genkey)
# This configuration applies to both API endpoints and the WebUI
auth: sk-change-me-to-your-secure-key
Full Configuration Details: Please refer to the detailed comments in config.example.yaml, or visit the WebAI2API Documentation Center for a complete configuration guide.
2. Access Web Management Interface
After the service starts, open your browser and visit:
http://localhost:3000
Remote Access: Replace
localhostwith your server's IP address. API Token: The authentication key configured inauthof the configuration file. Security Suggestion: For public network environments, it is recommended to configure HTTPS using Nginx/Caddy or access via SSH tunnel.
3. Initial Account Login
The following initialization steps must be completed on first use:
Connect to Virtual Display:
- Linux/Docker: Connect in the "Virtual Display" section of the WebUI.
- Windows: Operate directly in the browser window that pops up.
Complete Account Login:
- Manually log in to the required AI website account (account requirements can be found in the WebUI's adapter management).
- Send any message in the input box to trigger and complete human-machine verification (if required).
- Agree to terms of service orๆฐๆ guides (if required).
- Ensure there are no more initial use related obstructions.
SSH Tunnel Connection Example (Recommended for public servers):
# Run in your local terminal to map the server's WebUI to local ssh -L 3000:127.0.0.1:3000 root@Server_IP # Then access locally # WebUI: http://localhost:3000
๐ Usage
Running Mode Description
Regarding Headful/Headless Mode:
- Headful Mode (Default): Displays the browser window, convenient for debugging and manual intervention.
- Headless Mode: Runs in the background, saves resources but interfaces cannot be viewed, and may be detected by websites.
Recommendation: To reduce risk, it is strongly recommended to run in non-headless mode for the long term (or use virtual display Xvfb).
๐ API Reference
Detailed Documentation: Please visit the WebAI2API Documentation Center for a more comprehensive configuration guide and interface description.
1. OpenAI Compatible API
Concurrency Limits and Streaming Keep-alive Recommendations
This project is implemented by simulating real browser operations, and processing time may vary. When the backlog of tasks exceeds the configured amount, non-streaming requests will be rejected directly.
๐ก Highly Recommended to enable Streaming Mode: The server will send keep-alive heartbeat packets, allowing for infinite queuing to avoid timeouts.
Text Chat
Endpoint: POST /v1/chat/completions
Request Example:
curl http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "gemini-3-pro",
"messages": [
{"role": "user", "content": "Hello, please introduce yourself"}
],
"stream": true
}'
Multimodal Requests (Text-to-Image / Image-to-Image)
Supported Image Formats:
- Formats: PNG, JPEG, GIF, WebP
- Quantity: Max 10 images (specific limits vary by website)
- Data Format: Must use Base64 Data URL format
- Auto Conversion: The server automatically converts all images to JPG to ensure compatibility.
Parameter Description
| Parameter | Type | Required | Description |
|---|---|---|---|
model |
string | โ | Model name, available list can be retrieved via /v1/models |
stream |
boolean | Rec. | Whether to enable streaming response, includes heartbeat keep-alive mechanism |
Regarding Streaming Keep-alive (Heartbeat)
To prevent long connection timeouts, the system provides two keep-alive modes (configurable):
- Comment Mode (Default/Recommended): Sends
:keepalivecomments, compliant with SSE standards, best compatibility.- Content Mode: Sends data packets with empty content, only for special clients that must receive JSON data to reset timeouts.
2. Get Model List
Endpoint: GET /v1/models
Request Example:
curl http://localhost:3000/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"
3. Get Cookies
Description: Utilize the project's automatic renewal feature to get the latest Cookies for use with other tools.
Endpoint: GET /v1/cookies
Parameters:
name(Optional): Browser instance name, defaults todefault.domain(Optional): Filter Cookies for a specific domain.
Request Example:
# Get cookies for a specific instance and domain
curl "http://localhost:3000/v1/cookies?name=browser_default&domain=lmarena.ai" \
-H "Authorization: Bearer YOUR_API_KEY"
๐ Hardware Configuration Reference
| Resource | Minimum | Recommended (Single Instance) | Recommended (Multi-Instance) |
|---|---|---|---|
| CPU | 1 Core | 2 Cores+ | 2 Cores+ |
| RAM | 1 GB | 2 GB+ | 4 GB+ |
| Disk | 2 GB available | 5 GB+ | 7 GB+ |
Measured Environment Performance (All with single browser instance):
- Oracle Free Tier (1C1G, Debian 12): Resource-intensive, quite laggy, only for trial or light use.
- Aliyun Lightweight Cloud (2C2G, Debian 11): Runs smoothly but instances may still lag; used for project development and testing.
๐ License and Disclaimer
This project is open-sourced under the MIT License.
Disclaimer
This project is for educational and exchange purposes only. The author and the project are not responsible for any consequences (including but not limited to account suspension) caused by using this project. Please comply with the Terms of Service (ToS) of the relevant websites and services, and ensure proper backup of relevant data.
๐ Changelog
View the full version history and update details at CHANGELOG.md.
๐ฐ๏ธ Historical Version Note
This project has migrated from Puppeteer to Camoufox to handle increasingly complex anti-bot detection mechanisms. Older code based on Puppeteer has been archived to the puppeteer-edition branch for reference only and is no longer updated or maintained.
๐ Acknowledgments
Thanks to sites like LMArena and Gemini for providing AI services! ๐
Thanks to Hugging Face for providing free Space hosting! ๐
๐ Contact
- Author: foxhui
- GitHub: https://github.com/foxhui
- Documentation: WebAI2API Documentation Center
- Issues: Submit Issue