Skip to content

Commit 3183f7b

Browse files
foxhuifoxhui
committed
docs: Add English version of README
1 parent aae1851 commit 3183f7b

2 files changed

Lines changed: 314 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# WebAI2API
22

3+
简体中文 | [English](README_EN.md)
4+
35
<p align="center">
46
<img src="https://github.com/user-attachments/assets/296a518e-c42b-4e39-8ff6-9b4381ed4f6e" width="49%" />
57
<img src="https://github.com/user-attachments/assets/bfa30ece-6947-4f18-b2c9-ccc8087b7e89" width="49%" />

‎README_EN.md‎

Lines changed: 312 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,312 @@
1+
# WebAI2API
2+
3+
[简体中文](README.md) | English
4+
5+
> [!NOTE]
6+
> This English version is translated by **Gemini 3 Flash**.
7+
8+
<p align="center">
9+
<img src="https://github.com/user-attachments/assets/296a518e-c42b-4e39-8ff6-9b4381ed4f6e" width="49%" />
10+
<img src="https://github.com/user-attachments/assets/bfa30ece-6947-4f18-b2c9-ccc8087b7e89" width="49%" />
11+
</p>
12+
<p align="center">
13+
<img src="https://github.com/user-attachments/assets/5b15ebd2-7593-4f0e-8561-83d6ba5d88ab" width="49%" />
14+
<img src="https://github.com/user-attachments/assets/53deea29-4071-4a07-8a61-211761c5f2f7" width="49%" />
15+
</p>
16+
17+
## 📑 Table of Contents
18+
19+
- [Quick Deployment](#-quick-deployment)
20+
- [Quick Start](#-quick-start)
21+
- [Usage](#-usage)
22+
- [API Reference](#-api-reference)
23+
- [Hardware Configuration Reference](#-hardware-configuration-reference)
24+
25+
---
26+
27+
## 📝 Project Introduction
28+
29+
**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).
30+
31+
### ✨ Key Features
32+
33+
- 🤖 **Human-like Interaction**: Simulates human typing and mouse trajectories, evading automation detection through feature camouflage.
34+
- 🔄 **API Compatibility**: Provides standard OpenAI format interfaces, supporting streaming responses and heartbeat persistence.
35+
- 🚀 **Concurrency & Isolation**: Supports multi-window concurrent execution with independent proxy configurations, achieving browser-level data isolation for multiple accounts.
36+
- 🛡️ **Stable Protection**: Built-in task queue, load balancing, failover, error retry, and other essential functions.
37+
- 🎨 **Web Management**: Provides a visual management interface supporting real-time log viewing, VNC connection, adapter management, etc.
38+
39+
### 📋 Supported Platforms
40+
41+
| Website | Text Gen | Image Gen | Video Gen |
42+
| :--- | :---: | :---: | :---: |
43+
| [**LMArena**](https://lmarena.ai/) | ✅ | ✅ | 🚫 |
44+
| [**Gemini Enterprise Business**](https://business.gemini.google/) | ✅ | ✅ | ✅ |
45+
| [**Nano Banana Free**](https://nanobananafree.ai/) | 🚫 | ✅ | 🚫 |
46+
| [**zAI**](https://zai.is/) | ✅ | ✅ | 🚫 |
47+
| [**Google Gemini**](https://gemini.google.com/) | ✅ | ✅ | ✅ |
48+
| [**ZenMux**](https://zenmux.ai/) | ✅ | ❌ | 🚫 |
49+
| [**ChatGPT**](https://chatgpt.com/) | ✅ | ✅ | 🚫 |
50+
| [**DeepSeek**](https://chat.deepseek.com/) | ✅ | 🚫 | 🚫 |
51+
| [**Sora**](https://sora.chatgpt.com/) | 🚫 | 🚫 | ✅ |
52+
| [**Google Flow**](https://labs.google/fx/zh/tools/flow) | 🚫 | ✅ | ❌ |
53+
| [**Doubao**](https://www.doubao.com/) | ✅ | ✅ | ❌ |
54+
| To be continued... | - | - | - |
55+
56+
> [!NOTE]
57+
> **Get full model list**: Use the `GET /v1/models` endpoint to view all available models and their details under the current configuration.
58+
>
59+
> ✅ Supported; ❌ Not currently supported, but may be in the future; 🚫 Website does not support, future support depends on the website's status;
60+
61+
---
62+
63+
## 🚀 Quick Deployment
64+
65+
This project supports both **source code execution** and **Docker containerized deployment**.
66+
67+
### 📋 Environment Requirements
68+
69+
- **Node.js**: v20.0.0+ (ABI 115+)
70+
- **OS**: Windows / Linux / macOS
71+
- **Core Dependency**: Camoufox (automatically downloaded during installation)
72+
73+
### 🛠️ Method 1: Manual Deployment
74+
75+
1. **Installation & Configuration**
76+
```bash
77+
# 1. Install NPM dependencies
78+
pnpm install
79+
# 2. Install precompiled dependencies like the browser
80+
# ⚠️ This script requires connecting to GitHub to download resources. Use a proxy if network access is limited.
81+
npm run init
82+
# Using a proxy
83+
# Use -proxy to interactively input proxy configuration
84+
npm run init -- -proxy=http://username:passwd@host:port
85+
```
86+
87+
2. **Start Service**
88+
```bash
89+
# Standard start
90+
npm start
91+
92+
# Linux - Start with virtual display
93+
npm start -- -xvfb -vnc
94+
95+
# Login mode (Temporarily forces disabling headless mode and automation)
96+
npm start -- -login (-xvfb -vnc)
97+
```
98+
99+
### 🐳 Method 2: Docker Deployment
100+
101+
> [!WARNING]
102+
> **Security Reminder**:
103+
> - The Docker image enables the virtual display (Xvfb) and VNC service by default.
104+
> - Connection is possible via the virtual display section of the WebUI.
105+
> - **WebUI transmission is unencrypted. Please use SSH tunneling or HTTPS in public network environments.**
106+
107+
**Start with Docker CLI**
108+
```bash
109+
docker run -d --name webai-2api \
110+
-p 3000:3000 \
111+
-v "$(pwd)/data:/app/data" \
112+
--shm-size=2gb \
113+
foxhui/webai-2api:latest
114+
```
115+
116+
**Start with Docker Compose**
117+
```bash
118+
docker-compose up -d
119+
```
120+
121+
---
122+
123+
## ⚡ Quick Start
124+
125+
### 1. Adjust Configuration File
126+
127+
On first run, the program will copy the configuration file from `config.example.yaml` to `data/config.yaml`.
128+
129+
**Changes to the configuration file require a program restart to take effect!**
130+
131+
```yaml
132+
server:
133+
# Listening port
134+
port: 3000
135+
# Authentication API Token (can be generated using npm run genkey)
136+
# This configuration applies to both API endpoints and the WebUI
137+
auth: sk-change-me-to-your-secure-key
138+
```
139+
140+
> [!TIP]
141+
> **Full Configuration Details**: Please refer to the detailed comments in [config.example.yaml](config.example.yaml), or visit the [WebAI2API Documentation Center](https://foxhui.github.io/WebAI2API/en/) for a complete configuration guide.
142+
143+
### 2. Access Web Management Interface
144+
145+
After the service starts, open your browser and visit:
146+
```
147+
http://localhost:3000
148+
```
149+
150+
> [!TIP]
151+
> **Remote Access**: Replace `localhost` with your server's IP address.
152+
> **API Token**: The authentication key configured in `auth` of the configuration file.
153+
> **Security Suggestion**: For public network environments, it is recommended to configure HTTPS using Nginx/Caddy or access via SSH tunnel.
154+
155+
### 3. Initial Account Login
156+
157+
> [!IMPORTANT]
158+
> **The following initialization steps must be completed on first use**:
159+
160+
1. **Connect to Virtual Display**:
161+
- Linux/Docker: Connect in the "Virtual Display" section of the WebUI.
162+
- Windows: Operate directly in the browser window that pops up.
163+
164+
2. **Complete Account Login**:
165+
- Manually log in to the required AI website account (account requirements can be found in the WebUI's adapter management).
166+
- Send any message in the input box to trigger and complete human-machine verification (if required).
167+
- Agree to terms of service or新手 guides (if required).
168+
- Ensure there are no more initial use related obstructions.
169+
170+
3. **SSH Tunnel Connection Example** (Recommended for public servers):
171+
```bash
172+
# Run in your local terminal to map the server's WebUI to local
173+
ssh -L 3000:127.0.0.1:3000 root@Server_IP
174+
175+
# Then access locally
176+
# WebUI: http://localhost:3000
177+
```
178+
179+
---
180+
181+
## 📖 Usage
182+
183+
### Running Mode Description
184+
185+
> [!NOTE]
186+
> **Regarding Headful/Headless Mode**:
187+
> - **Headful Mode** (Default): Displays the browser window, convenient for debugging and manual intervention.
188+
> - **Headless Mode**: Runs in the background, saves resources but interfaces cannot be viewed, and may be detected by websites.
189+
>
190+
> **Recommendation**: To reduce risk, **it is strongly recommended to run in non-headless mode for the long term** (or use virtual display Xvfb).
191+
192+
---
193+
194+
## 🔌 API Reference
195+
196+
> [!TIP]
197+
> **Detailed Documentation**: Please visit the [WebAI2API Documentation Center](https://foxhui.github.io/WebAI2API/en/) for a more comprehensive configuration guide and interface description.
198+
199+
### 1. OpenAI Compatible API
200+
201+
> [!WARNING]
202+
> **Concurrency Limits and Streaming Keep-alive Recommendations**
203+
>
204+
> 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.
205+
>
206+
> **💡 Highly Recommended to enable Streaming Mode**: The server will send keep-alive heartbeat packets, allowing for infinite queuing to avoid timeouts.
207+
208+
#### Text Chat
209+
210+
**Endpoint**: `POST /v1/chat/completions`
211+
212+
**Request Example**:
213+
```bash
214+
curl http://localhost:3000/v1/chat/completions \
215+
-H "Content-Type: application/json" \
216+
-H "Authorization: Bearer YOUR_API_KEY" \
217+
-d '{
218+
"model": "gemini-3-pro",
219+
"messages": [
220+
{"role": "user", "content": "Hello, please introduce yourself"}
221+
],
222+
"stream": true
223+
}'
224+
```
225+
226+
#### Multimodal Requests (Text-to-Image / Image-to-Image)
227+
228+
**Supported Image Formats**:
229+
- **Formats**: PNG, JPEG, GIF, WebP
230+
- **Quantity**: Max 10 images (specific limits vary by website)
231+
- **Data Format**: Must use Base64 Data URL format
232+
- **Auto Conversion**: The server automatically converts all images to JPG to ensure compatibility.
233+
234+
#### Parameter Description
235+
236+
| Parameter | Type | Required | Description |
237+
| :--- | :--- | :---: | :--- |
238+
| `model` | string | ✅ | Model name, available list can be retrieved via `/v1/models` |
239+
| `stream` | boolean | Rec. | Whether to enable streaming response, includes heartbeat keep-alive mechanism |
240+
241+
> [!NOTE]
242+
> **Regarding Streaming Keep-alive (Heartbeat)**
243+
>
244+
> To prevent long connection timeouts, the system provides two keep-alive modes (configurable):
245+
> 1. **Comment Mode (Default/Recommended)**: Sends `:keepalive` comments, compliant with SSE standards, best compatibility.
246+
> 2. **Content Mode**: Sends data packets with empty content, only for special clients that must receive JSON data to reset timeouts.
247+
248+
### 2. Get Model List
249+
250+
**Endpoint**: `GET /v1/models`
251+
252+
**Request Example**:
253+
```bash
254+
curl http://localhost:3000/v1/models \
255+
-H "Authorization: Bearer YOUR_API_KEY"
256+
```
257+
258+
### 3. Get Cookies
259+
260+
**Description**: Utilize the project's automatic renewal feature to get the latest Cookies for use with other tools.
261+
262+
**Endpoint**: `GET /v1/cookies`
263+
264+
**Parameters**:
265+
- `name` (Optional): Browser instance name, defaults to `default`.
266+
- `domain` (Optional): Filter Cookies for a specific domain.
267+
268+
**Request Example**:
269+
```bash
270+
# Get cookies for a specific instance and domain
271+
curl "http://localhost:3000/v1/cookies?name=browser_default&domain=lmarena.ai" \
272+
-H "Authorization: Bearer YOUR_API_KEY"
273+
```
274+
275+
---
276+
277+
## 📊 Hardware Configuration Reference
278+
279+
| Resource | Minimum | Recommended (Single Instance) | Recommended (Multi-Instance) |
280+
| :--- | :--- | :--- | :--- |
281+
| **CPU** | 1 Core | 2 Cores+ | 2 Cores+ |
282+
| **RAM** | 1 GB | 2 GB+ | 4 GB+ |
283+
| **Disk** | 2 GB available | 5 GB+ | 7 GB+ |
284+
285+
**Measured Environment Performance** (All with single browser instance):
286+
- **Oracle Free Tier** (1C1G, Debian 12): Resource-intensive, quite laggy, only for trial or light use.
287+
- **Aliyun Lightweight Cloud** (2C2G, Debian 11): Runs smoothly but instances may still lag; used for project development and testing.
288+
289+
---
290+
291+
## 📄 License and Disclaimer
292+
293+
This project is open-sourced under the [MIT License](LICENSE).
294+
295+
> [!CAUTION]
296+
> **Disclaimer**
297+
>
298+
> 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.
299+
300+
---
301+
302+
## 📋 Changelog
303+
304+
View the full version history and update details at [CHANGELOG.md](CHANGELOG.md).
305+
306+
### 🕰️ Historical Version Note
307+
308+
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**.
309+
310+
---
311+
312+
**Thanks to sites like LMArena and Gemini for providing AI services!** 🎉

0 commit comments

Comments
 (0)