diff --git a/.vitepress/config.js b/.vitepress/config.js index 7f4a56a..0a2674c 100644 --- a/.vitepress/config.js +++ b/.vitepress/config.js @@ -17,61 +17,111 @@ export default defineConfig({ /^http:\/\/localhost/ ], - themeConfig: { - nav: [ - { text: '首页', link: '/' }, - { text: '入门指南', link: '/guide/requirements' }, - { text: 'API 参考', link: '/api/overview' } - ], - - sidebar: [ - { - text: '入门指南', - items: [ - { text: '项目介绍', link: '/guide/introduction' }, - { text: '环境要求', link: '/guide/requirements' }, - { text: '快速部署', link: '/guide/deployment' }, - { text: '首次使用', link: '/guide/first-use' } - ] - }, - { - text: '配置说明', - items: [ - { text: '配置概览', link: '/config/overview' }, - { text: '实例配置', link: '/config/instances' }, - { text: '代理设置', link: '/config/proxy' } - ] - }, - { - text: 'API 参考', - items: [ - { text: '接口概览', link: '/api/overview' }, - { text: 'Chat Completions', link: '/api/chat' }, - { text: 'Models', link: '/api/models' }, - { text: 'Cookies', link: '/api/cookies' } - ] - }, - { - text: '运维管理', - items: [ - { text: 'Web 管理界面', link: '/admin/webui' }, - { text: 'Linux 部署', link: '/admin/linux' }, - { text: '故障排查', link: '/admin/troubleshooting' } - ] + locales: { + root: { + label: '简体中文', + lang: 'zh-CN', + themeConfig: { + nav: [ + { text: '首页', link: '/' }, + { text: '入门指南', link: '/guide/requirements' }, + { text: 'API 参考', link: '/api/overview' } + ], + sidebar: [ + { + text: '入门指南', + items: [ + { text: '项目介绍', link: '/guide/introduction' }, + { text: '环境要求', link: '/guide/requirements' }, + { text: '快速部署', link: '/guide/deployment' }, + { text: '首次使用', link: '/guide/first-use' } + ] + }, + { + text: '配置说明', + items: [ + { text: '配置概览', link: '/config/overview' }, + { text: '实例配置', link: '/config/instances' }, + { text: '代理设置', link: '/config/proxy' } + ] + }, + { + text: 'API 参考', + items: [ + { text: '接口概览', link: '/api/overview' }, + { text: 'Chat Completions', link: '/api/chat' }, + { text: 'Models', link: '/api/models' }, + { text: 'Cookies', link: '/api/cookies' } + ] + }, + { + text: '运维管理', + items: [ + { text: 'Web 管理界面', link: '/admin/webui' }, + { text: 'Linux 部署', link: '/admin/linux' }, + { text: '故障排查', link: '/admin/troubleshooting' } + ] + } + ], + outline: { label: '页面导航' }, + docFooter: { prev: '上一页', next: '下一页' } } - ], + }, + en: { + label: 'English', + lang: 'en-US', + link: '/en/', + themeConfig: { + nav: [ + { text: 'Home', link: '/en/' }, + { text: 'Guide', link: '/en/guide/requirements' }, + { text: 'API Reference', link: '/en/api/overview' } + ], + sidebar: [ + { + text: 'Guide', + items: [ + { text: 'Introduction', link: '/en/guide/introduction' }, + { text: 'Requirements', link: '/en/guide/requirements' }, + { text: 'Deployment', link: '/en/guide/deployment' }, + { text: 'First Use', link: '/en/guide/first-use' } + ] + }, + { + text: 'Configuration', + items: [ + { text: 'Overview', link: '/en/config/overview' }, + { text: 'Instances', link: '/en/config/instances' }, + { text: 'Proxy Settings', link: '/en/config/proxy' } + ] + }, + { + text: 'API Reference', + items: [ + { text: 'API Overview', link: '/en/api/overview' }, + { text: 'Chat Completions', link: '/en/api/chat' }, + { text: 'Models', link: '/en/api/models' }, + { text: 'Cookies', link: '/en/api/cookies' } + ] + }, + { + text: 'Operation', + items: [ + { text: 'Web UI', link: '/en/admin/webui' }, + { text: 'Linux Deployment', link: '/en/admin/linux' }, + { text: 'Troubleshooting', link: '/en/admin/troubleshooting' } + ] + } + ], + outline: { label: 'On this page' }, + docFooter: { prev: 'Previous page', next: 'Next page' } + } + } + }, + themeConfig: { socialLinks: [ { icon: 'github', link: 'https://github.com/foxhui/WebAI2API' } - ], - - outline: { - label: '页面导航' - }, - - docFooter: { - prev: '上一页', - next: '下一页' - } + ] } }) diff --git a/docs/en/admin/linux.md b/docs/en/admin/linux.md new file mode 100644 index 0000000..bce81f5 --- /dev/null +++ b/docs/en/admin/linux.md @@ -0,0 +1,88 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# Linux Deployment + +[Docker users can ignore this] Special configuration instructions for running WebAI2API on Linux servers. + +## 1. Install Necessary Dependencies + +Essential dependencies for Linux command-line mode that allow you to run graphical applications in a Linux environment without a desktop environment. + +### Ubuntu/Debian + +```bash +sudo apt-get update +sudo apt-get install xvfb x11vnc +``` + +### CentOS/RHEL + +```bash +sudo yum install xorg-x11-server-Xvfb x11vnc +``` + +### Arch Linux + +```bash +sudo pacman -S xorg-server-xvfb x11vnc +``` + +## 2. Run the Program + +Run the program using a virtual display and view it remotely via VNC. (The program will handle all the setup for you.) + +```bash +npm start -- -xvfb -vnc +``` + +This will automatically: +- Start the Xvfb virtual display. +- Start the x11vnc server. +- Allow you to view the VNC screen directly through the WebUI. + +## 3. Connecting to the Program + +### Via WebUI (Recommended) + +Once the service is started, visit the "VNC Display" page in the WebUI to view it directly. + +### Via SSH Tunnel + +::: tip Tip +The port might not always be 5900; the program will automatically search for an available VNC port in the range 5900-5999. +::: + +```bash +# In your local terminal +ssh -L 5900:127.0.0.1:5900 root@Server_IP +``` + +Then use a VNC client to connect to `127.0.0.1:5900`. + +## Alternative Method: Terminal X11 Forwarding + +This method is not recommended unless you prefer to configure your own environment. + +1. Install an X Server locally (e.g., VcXsrv, Xming). +2. Use a terminal that supports X11 forwarding (e.g., WindTerm). +3. Enable X11 forwarding in your SSH session. + +```bash +ssh -X user@server +``` + +## FAQ + +### Port Already Occupied + +If port 5900 is already in use, the VNC server will automatically look for an available port in the 5901-5999 range. + +### Display Number Conflict + +Xvfb will automatically search for an available display number starting from 50 to avoid conflicts with existing X servers. + +### Unable to Connect to VNC + +Please check if the dependencies were installed successfully. diff --git a/docs/en/admin/troubleshooting.md b/docs/en/admin/troubleshooting.md new file mode 100644 index 0000000..a858556 --- /dev/null +++ b/docs/en/admin/troubleshooting.md @@ -0,0 +1,148 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# Troubleshooting + +Diagnosis and solutions for common problems. + +## Operational Issues + +### Window Forcing Itself to Foreground + +**Problem**: The browser window actively brings itself to the foreground during a task. + +**Solution**: +- On Windows and macOS, you can use a separate virtual desktop (Win + Tab) specifically for the program. +- On Linux, use Xvfb mode. + +## Request Issues + +### Request Rejected (429 Too Many Requests) + +**Problem**: Too many concurrent requests; the queue is full. + +**Solution**: +- Enable streaming mode (`stream: true`), which allows for unlimited queuing. +- Reduce the number of concurrent requests. +- Increase the `queue.queueBuffer` value in your configuration. + +### Request Timeout + +**Problem**: The task did not complete within 120 seconds. + +**Solution**: +- Enable streaming mode and use the heartbeat mechanism to keep the connection alive. +- Check if your network connection is stable. +- Some complex prompts may simply require more time. + +## Verification Issues + +### reCAPTCHA Failure + +**Problem**: Returns `recaptcha validation failed`. + +**Solution**: +- Reduce the frequency of requests. +- Enter Login Mode to complete the verification manually. +- Use a stable and clean IP address. +- Check IP cleanliness using tools like [ping0.cc](https://ping0.cc). + +### Cloudflare Challenge + +**Problem**: The browser is stuck on the Cloudflare verification page. + +**Solution**: +- Use VNC to complete the verification manually. +- Change your IP address. +- Avoid using datacenter IPs. + +## Login Issues + +### Login State Lost + +**Problem**: You are asked to log in again after a service restart. + +**Solution**: +- Ensure the `data` directory is persistent. +- Verify that the `userDataMark` configuration is correct. +- Avoid deleting browser data directories. + +### OAuth Login Failure + +**Problem**: Login redirects via Google or other OAuth providers fail. + +**Solution**: +- Ensure `accounts.google.com` is accessible. +- Check if your proxy configuration is correct. +- Try changing your IP address. + +## Browser Issues + +### Browser Fails to Start + +**Problem**: Camoufox cannot start. + +**Solution**: +```bash +# Re-initialize Camoufox +npm run init +``` + +### Out of Memory + +**Problem**: The browser crashes due to insufficient memory. + +**Solution**: +- Increase server RAM (2GB+ recommended). +- Reduce the number of simultaneously running browser instances. +- Ensure `--shm-size=2gb` is set in Docker environments. + +## Network Issues + +### Proxy Connection Failed + +**Problem**: Unable to connect to the proxy server. + +**Solution**: +- Check the proxy server address and port. +- Verify proxy authentication credentials. +- Test if the proxy server is working correctly. + +### Target Website Inaccessible + +**Problem**: Unable to access sites like LMArena or Gemini. + +**Solution**: +- Check your network connectivity. +- Try using a proxy. +- Confirm the target website is not blocked. + +## Log Diagnosis + +### View Detailed Logs + +Set the log level in `config.yaml`: + +```yaml +logLevel: debug +``` + +### Common Log Messages + +| Log Content | Description | +| --- | --- | +| `Worker pool initialization failed` | Check configuration and network. | +| `Worker does not support model` | Verify if the model name is correct. | +| `Verification timeout` | Manual verification is required. | +| `Page closed` | The browser may have crashed. | + +## Getting Help + +If the above methods do not resolve your issue: + +1. Check [GitHub Issues](https://github.com/foxhui/WebAI2API/issues). +2. Submit an Issue including: + - Log output (with `logLevel: debug`). + - Your configuration file (hide sensitive information). + - Your OS and Node.js version. diff --git a/docs/en/admin/webui.md b/docs/en/admin/webui.md new file mode 100644 index 0000000..f6682dc --- /dev/null +++ b/docs/en/admin/webui.md @@ -0,0 +1,87 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# Web Management Interface + +WebAI2API provides a built-in Web Management Interface (WebUI) for monitoring and managing the service. + +::: warning Note +The WebUI and management interfaces only use the API Token for authentication during the handshake phase. Transmissions are not encrypted. If you are using this on a public network, please use a professional web server like Caddy or Nginx to provide HTTPS encryption! +::: + +## Access URL + +``` +http://localhost:3000 +``` + +On your first visit, you will need to enter the API Token set in your configuration file (`auth` field) for authentication. + +## Functional Modules + +### Dashboard + +The dashboard displays the system's operational status: + +- **System Status**: Version, uptime, and running mode. +- **Business Statistics**: Number of windows and instances. +- **Queue Status**: Lists of tasks currently being processed or waiting in the queue. + +### System Management + +The system management page provides: + +- **Service Control** + - Normal Restart + - Restart in Login Mode + - Specific Worker Login + - Stop Service + - Adapter Settings (descriptions, model management, feature toggles) + +- **Cache Management** + - View temporary files. + - Clear cache. + +- **Data Management** + - View browser data directories. + - Delete unused data directories. + +### VNC Display + +When starting with `-xvfb -vnc` in a Linux environment, you can view and operate the virtual display directly through the WebUI: + +- Connect/Disconnect VNC. +- Full-screen mode. +- View VNC status information. + +::: tip Note +The VNC display feature requires the service to be running in Xvfb + VNC mode. +::: + +### Configuration Management + +- **Server Configuration**: Port, authentication, and heartbeat settings. +- **Adapter Configuration**: Exclusive settings for each backend. +- **Browser Settings**: Path, headless mode, and proxy settings. + +### Instance Management + +Manage browser instance and Worker configurations (requires a restart to take effect). + +## Quick Actions + +### Restarting in Login Mode + +1. Go to the "Cache & Restart" page. +2. Click the dropdown arrow next to the "Restart" button. +3. Select the restart mode: + - **Normal Restart**: Restarts in standard mode. + - **Login Mode Restart**: Restarts with the `-login` parameter. + - **Specific Worker Login**: Select a specific Worker to enter login mode. + +### Clearing Cache + +1. Go to the "Cache & Restart" page. +2. Find the "Cache Management" area. +3. Click the "Clear Cache" button. diff --git a/docs/en/api/chat.md b/docs/en/api/chat.md new file mode 100644 index 0000000..d7e470f --- /dev/null +++ b/docs/en/api/chat.md @@ -0,0 +1,175 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# Chat Completions + +The chat generation interface, compatible with the OpenAI Chat Completions API. + +## Endpoint + +``` +POST /v1/chat/completions +``` + +## Request Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `model` | string | ✅ | Model name | +| `messages` | array | ✅ | List of messages | +| `stream` | boolean | ❌ | Whether to enable streaming responses (recommended) | + +### messages Format + +```json +{ + "messages": [ + { + "role": "user", + "content": "Generate a cute cat" + } + ] +} +``` + +### Multi-modal Requests (Image-to-Image / Image-to-Text) + +```json +{ + "messages": [ + { + "role": "user", + "content": [ + { + "type": "text", + "text": "Make this image more vibrant" + }, + { + "type": "image_url", + "image_url": { + "url": "data:image/jpeg;base64,/9j/4AAQ..." + } + } + ] + } + ] +} +``` + +## Image Limitations + +| Item | Description | +| --- | --- | +| Supported Formats | PNG, JPEG, GIF, WebP | +| Quantity Limit | Default 5, Maximum 10 | +| Data Format | Base64 Data URL (`data:image/jpeg;base64,...`) | +| Auto-transformation | The server automatically converts images to JPG format | + +## Non-streaming Response + +### Request Example + +```bash +curl -X POST http://localhost:3000/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer sk-your-key" \ + -d '{ + "model": "gemini-3-pro-image-preview", + "messages": [ + { + "role": "user", + "content": "generate a cat" + } + ] + }' +``` + +### Response Example + +```json +{ + "id": "chatcmpl-1732374740123", + "object": "chat.completion", + "created": 1732374740, + "model": "gemini-3-pro-image-preview", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "![generated](data:image/jpeg;base64,/9j/4AAQ...)" + }, + "finish_reason": "stop" + } + ] +} +``` + +## Streaming Response + +::: tip Recommendation +Streaming mode includes a heartbeat mechanism to keep the connection alive, preventing timeouts during long generations. +::: + +### Request Example + +```bash +curl -X POST http://localhost:3000/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer sk-your-key" \ + -d '{ + "model": "gemini-3-pro-image-preview", + "stream": true, + "messages": [ + { + "role": "user", + "content": "generate a cat" + } + ] + }' +``` + +### Response Example + +``` +data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1732374740,"model":"gemini-3-pro-image-preview","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]} + +: keep-alive + +: keep-alive + +data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1732374740,"model":"gemini-3-pro-image-preview","choices":[{"index":0,"delta":{"content":"![generated](data:image/jpeg;base64,/9j/4AAQ...)"},"finish_reason":"stop"}]} + +data: [DONE] +``` + +## Error Handling + +### Queue Full (429) + +```json +{ + "error": { + "message": "Queue is full", + "type": "rate_limit_exceeded", + "code": "QUEUE_FULL" + } +} +``` + +::: tip Solution +Enabling streaming mode (`stream: true`) allows for unlimited queuing, avoiding 429 errors. +::: + +### Model Not Supported (400) + +```json +{ + "error": { + "message": "No Worker supports model: invalid-model", + "type": "invalid_request_error", + "code": "MODEL_NOT_FOUND" + } +} +``` diff --git a/docs/en/api/cookies.md b/docs/en/api/cookies.md new file mode 100644 index 0000000..c6cdd8c --- /dev/null +++ b/docs/en/api/cookies.md @@ -0,0 +1,74 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# Cookies API + +Retrieve cookies from browser instances, which can be used by other tools. + +## Endpoint + +``` +GET /v1/cookies +``` + +## Query Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `name` | string | ❌ | Browser instance name | +| `domain` | string | ❌ | Filter cookies by a specific domain | + +## Request Example + +### Get All Cookies + +```bash +curl -X GET http://localhost:3000/v1/cookies \ + -H "Authorization: Bearer sk-your-key" +``` + +### Specify Instance and Domain + +```bash +curl -X GET "http://localhost:3000/v1/cookies?name=browser_default&domain=lmarena.ai" \ + -H "Authorization: Bearer sk-your-key" +``` + +## Response Format + +```json +{ + "instance": "browser_default", + "cookies": [ + { + "name": "_GRECAPTCHA", + "value": "09ADxxxxxx", + "domain": "www.google.com", + "path": "/recaptcha", + "expires": 1780000000, + "httpOnly": true, + "secure": true, + "sameSite": "None" + }, + { + "name": "OTZ", + "value": "8888888_24_24__24_", + "domain": "accounts.google.com", + "path": "/", + "expires": 1760000000, + "httpOnly": false, + "secure": true, + "sameSite": "None" + } + ] +} +``` + +## Usage Scenarios + +::: tip Application Scenarios +- Export cookies for use in other automation tools. +- Leverage this project's automatic session renewal to keep cookies fresh. +- Debug login state issues. +::: diff --git a/docs/en/api/models.md b/docs/en/api/models.md new file mode 100644 index 0000000..86e9886 --- /dev/null +++ b/docs/en/api/models.md @@ -0,0 +1,82 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# Models API + +Retrieve the list of currently available models. + +## Endpoint + +``` +GET /v1/models +``` + +## Request Example + +```bash +curl -X GET http://localhost:3000/v1/models \ + -H "Authorization: Bearer sk-your-key" +``` + +## Response Format + +```json +{ + "object": "list", + "data": [ + { + "id": "gemini-3-pro-image-preview", + "object": "model", + "created": 1732456789, + "owned_by": "internal_server" + }, + { + "id": "lmarena/gemini-3-pro-image-preview", + "object": "model", + "created": 1732456789, + "owned_by": "lmarena" + }, + { + "id": "seedream-4-high-res-fal", + "object": "model", + "created": 1732456789, + "owned_by": "internal_server" + } + ] +} +``` + +## Model Naming Conventions + +### Short Form + +Use the Model ID directly: + +``` +gemini-3-pro-image-preview +``` + +The system will automatically match a Worker that supports this model. + +### Explicit Backend Form + +Use the `backend/model` format: + +``` +lmarena/gemini-3-pro-image-preview +gemini_biz/gemini-3-pro-image-preview +``` + +This forces the request to be handled by a specific backend. + +## Model Types + +| Type | Description | +| --- | --- | +| `image` | Image generation models | +| `text` | Text generation models | + +::: info Note +The list of returned models depends on the currently configured Workers and their adapter types. +::: diff --git a/docs/en/api/overview.md b/docs/en/api/overview.md new file mode 100644 index 0000000..4fad784 --- /dev/null +++ b/docs/en/api/overview.md @@ -0,0 +1,78 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# API Overview + +WebAI2API provides a RESTful API compatible with the OpenAI format. + +## Basic Information + +- **Base URL**: `http://localhost:3000` +- **Authentication**: Bearer Token + +### Request Headers + +```http +Authorization: Bearer sk-your-secret-key +Content-Type: application/json +``` + +## API Endpoints List + +### OpenAI Compatible Interfaces + +| Method | Endpoint | Description | +| --- | --- | --- | +| POST | `/v1/chat/completions` | Chat Generation | +| GET | `/v1/models` | Retrieve Model List | +| GET | `/v1/cookies` | Retrieve Cookies | + +## Error Responses + +All API errors return a consistent format: + +```json +{ + "error": { + "message": "Error description", + "type": "error_type", + "code": "ERROR_CODE" + } +} +``` + +### Common Error Codes + +| HTTP Status | Error Type | Description | +| --- | --- | --- | +| 401 | `unauthorized` | Authentication failed | +| 400 | `invalid_request` | Invalid request parameters | +| 404 | `not_found` | Resource not found | +| 429 | `rate_limit` | Too many requests | +| 500 | `internal_error` | Internal server error | +| 503 | `service_unavailable` | Service unavailable | + +## Streaming Responses + +For requests with `stream: true`, the response uses the Server-Sent Events (SSE) format: + +``` +data: {"id":"...","object":"chat.completion.chunk",...} + +: keep-alive + +data: {"id":"...","object":"chat.completion.chunk",...} + +data: [DONE] +``` + +::: tip Heartbeat/Keep-alive +Streaming requests automatically send heartbeat packets to prevent connection timeouts. The format depends on the configured `keepalive.mode`. +::: + +## Related Documents + +- [Chat Completions](/en/api/chat) - Detailed documentation for the chat generation interface. +- [Models](/en/api/models) - Model list interface. +- [Cookies](/en/api/cookies) - Cookie retrieval interface. diff --git a/docs/en/config/instances.md b/docs/en/config/instances.md new file mode 100644 index 0000000..d3580a3 --- /dev/null +++ b/docs/en/config/instances.md @@ -0,0 +1,195 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# Instance Configuration + +Instance and Worker are the core configuration concepts of WebAI2API. + +## Concepts + +### Instance (Browser Instance) + +An Instance represents an independent browser process with: +- Dedicated user data directory. +- Independent Cookies and login sessions. +- Optional exclusive proxy configuration. + +### Worker + +A Worker is a single tab within an Instance responsible for interacting with a specific platform. Multiple Workers under the same Instance: +- Share browser data and login states. +- Share proxy configuration. +- Can be of different adapter types. + +## Configuration Structure + +```yaml +backend: + pool: + instances: + - name: "browser_default" # Instance ID + userDataMark: "01" # Data directory identifier (Optional) + proxy: # Instance-level proxy (Optional) + enable: true + type: socks5 + host: 127.0.0.1 + port: 1080 + workers: # List of Workers + - name: "worker1" + type: lmarena + - name: "worker2" + type: zai_is +``` + +## Instance Settings + +| Setting | Type | Required | Description | +| --- | --- | --- | --- | +| `name` | string | ✅ | Unique identifier for the instance, used in logs and Cookie retrieval. | +| `userDataMark` | string | ❌ | Data directory identifier. Leave empty to use the default directory. | +| `proxy` | object | ❌ | Instance-level proxy configuration. See [Proxy Settings](/en/config/proxy). | +| `workers` | array | ✅ | List of Worker configurations. | + +### Data Directory + +- Default Location: `data/camoufoxUserData` +- With `userDataMark`: `data/camoufoxUserData_{mark}` + +## Worker Settings + +| Setting | Type | Required | Description | +| --- | --- | --- | --- | +| `name` | string | ✅ | Unique identifier for the Worker (must be globally unique). | +| `type` | string | ✅ | Adapter type. | +| `mergeTypes` | array | ❌ | List of adapter types for aggregation mode (required if type=merge). | +| `mergeMonitor` | string | ❌ | Backend to monitor while idle (Optional). | + +### Adapter Types + +| Type | Description | +| --- | --- | +| `lmarena` | LMArena Image Generation | +| `lmarena_text` | LMArena Text Generation | +| `gemini_biz` | Gemini Business Image Generation | +| `gemini_biz_text` | Gemini Business Text Generation | +| `gemini` | Google Gemini | +| `zai_is` | zAI Image Generation | +| `nanobananafree_ai` | Nano Banana Free | +| `merge` | Aggregation Mode (Multiple backends in a single tab) | + +## Model Filter + +Each adapter can be configured with its own model allowlist/blocklist to control the available models for that specific adapter. + +### Configuration + +The Model Filter is configured under `backend.adapter.`: + +```yaml +backend: + adapter: + lmarena: + returnUrl: false + modelFilter: + mode: whitelist # whitelist or blacklist + list: # List of models to enable or disable + - gemini-3-pro-image-preview + - gemini-3-pro-image-preview-2k + - gemini-2.5-flash-image-preview +``` + +### Settings + +| Item | Type | Required | Description | +| --- | --- | --- | --- | +| `mode` | string | ✅ | Filter mode: `whitelist` or `blacklist`. | +| `list` | array | ✅ | List of Model IDs. | + +### Filter Modes + +- **whitelist**: Only models specified in the list are allowed; others will be filtered out. +- **blacklist**: Models specified in the list are disabled; others remain usable. + +### Recommendations + +::: tip Use WebUI for Configuration +We recommend using the Adapter Settings interface in the WebUI to configure model filters; visual operation is more convenient. +::: + +::: warning Notes +- Model IDs must exactly match the IDs actually supported by the adapter. +- In whitelist mode, if the list is empty or there are no matching models, the adapter will be unusable. +- Model filter configurations for each adapter are independent. +::: + +## Aggregation Mode (Merge) + +Aggregation mode allows a single tab to support multiple backends, enabling failover: + +```yaml +workers: + - name: "merged_worker" + type: merge + mergeTypes: [gemini_biz, lmarena, zai_is] + mergeMonitor: gemini_biz # Backend to monitor while idle +``` + +::: tip Advantages of Aggregation Mode +- Saves browser resources. +- Automatic failover. +- Unified login state. +::: + +## Configuration Examples + +### Single Instance, Single Worker + +```yaml +instances: + - name: "default" + workers: + - name: "worker1" + type: lmarena +``` + +### Multi-Instance Isolation + +```yaml +instances: + # Instance 1: US Proxy + - name: "browser_us" + userDataMark: "us" + proxy: + enable: true + type: socks5 + host: us-proxy.example.com + port: 1080 + workers: + - name: "us_worker" + type: lmarena + + # Instance 2: Japan Proxy + - name: "browser_jp" + userDataMark: "jp" + proxy: + enable: true + type: socks5 + host: jp-proxy.example.com + port: 1080 + workers: + - name: "jp_worker" + type: lmarena +``` + +### Aggregation Mode Example + +```yaml +instances: + - name: "browser_merged" + workers: + - name: "all_in_one" + type: merge + mergeTypes: [gemini_biz, lmarena, zai_is] + mergeMonitor: gemini_biz +``` diff --git a/docs/en/config/overview.md b/docs/en/config/overview.md new file mode 100644 index 0000000..92cff0c --- /dev/null +++ b/docs/en/config/overview.md @@ -0,0 +1,124 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# Configuration Overview + +WebAI2API uses a YAML format configuration file `config.yaml`. + +::: warning Note +The project configuration can now be fully managed via the WebUI. If you are not familiar with YAML files, please skip this section and use the WebUI to modify settings! +::: + +## Configuration Structure + +```yaml +# Log Level +logLevel: info + +# Server Configuration +server: + port: 3000 + auth: sk-your-key + keepalive: + mode: "comment" + +# Backend Configuration +backend: + pool: + strategy: least_busy + failover: + enabled: true + maxRetries: 2 + instances: + - name: "browser_default" + workers: + - name: "default" + type: lmarena + adapter: + gemini_biz: + entryUrl: "" + +# Queue Configuration +queue: + queueBuffer: 2 + imageLimit: 5 + +# Browser Configuration +browser: + path: "" + headless: false + proxy: + enable: false +``` + +## Configuration Items + +### Logging + +| Item | Type | Default | Description | +| --- | --- | --- | --- | +| `logLevel` | string | `info` | Log visibility levels: `debug`, `info`, `warn`, `error` | + +### Server (server) + +| Item | Type | Default | Description | +| --- | --- | --- | --- | +| `port` | number | `3000` | HTTP service listening port | +| `auth` | string | - | API Authentication Token (Bearer Token) | +| `keepalive.mode` | string | `comment` | Keep-alive mode: `comment` or `content` | + +::: tip Keep-alive Mode +- **comment**: Sends a `:keepalive` comment. Does not pollute the data stream (recommended). +- **content**: Sends an empty delta. Useful for clients that reset timeouts only upon receiving valid JSON. +::: + +### Queue (queue) + +| Item | Type | Default | Description | +| --- | --- | --- | --- | +| `queueBuffer` | number | `2` | Extra queuing slots for non-streaming requests. 0 means unlimited. | +| `imageLimit` | number | `5` | Maximum number of images per request (Max 10). | + +### Browser (browser) + +| Item | Type | Default | Description | +| --- | --- | --- | --- | +| `path` | string | `""` | Path to Camoufox executable. Leave empty to use default. | +| `headless` | boolean | `false` | Whether to enable headless mode. | +| `proxy` | object | - | Global proxy configuration. | + +### Adapter Configuration (backend.adapter) + +Each adapter can be configured with its own model allowlist/blocklist to control the available models for that specific adapter. + +| Item | Type | Default | Description | +| --- | --- | --- | --- | +| `modelFilter.mode` | string | - | Filter mode: `whitelist` or `blacklist`. | +| `modelFilter.list` | array | - | List of models (to be enabled or disabled based on `mode`). | + +::: tip Model Filtering +- **whitelist (Allowlist)**: Only models in the list are permitted. +- **blacklist (Blocklist)**: Models in the list are disabled; others are available. +- Using the WebUI for configuration is recommended. +::: + +Configuration Example: + +```yaml +backend: + adapter: + lmarena: + returnUrl: false + modelFilter: + mode: whitelist # Allowlist mode + list: # Only enable the following models + - gemini-3-pro-image-preview + - gemini-3-pro-image-preview-2k + - gemini-2.5-flash-image-preview +``` + +## Related Documents + +- [Instances Configuration](/en/config/instances) - Detailed browser instance and Worker configuration. +- [Proxy Settings](/en/config/proxy) - Detailed proxy setup. diff --git a/docs/en/config/proxy.md b/docs/en/config/proxy.md new file mode 100644 index 0000000..a25442c --- /dev/null +++ b/docs/en/config/proxy.md @@ -0,0 +1,89 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# Proxy Settings + +WebAI2API supports global proxy and instance-level proxy configurations. + +## Proxy Priority + +1. **Instance-level Proxy**: If an Instance is configured with its own proxy, that proxy is used. +2. **Global Proxy**: If the instance is not configured, the global proxy is used. +3. **Direct Connection**: If neither is configured, a direct connection is established. + +## Global Proxy Configuration + +Configure the global proxy in `browser.proxy`: + +```yaml +browser: + proxy: + enable: true + type: http # http or socks5 + host: 127.0.0.1 + port: 7890 + # Optional authentication + user: username + passwd: password +``` + +## Instance-level Proxy Configuration + +Configure a dedicated proxy for a specific Instance: + +```yaml +backend: + pool: + instances: + - name: "browser_us" + proxy: + enable: true + type: socks5 + host: us-proxy.example.com + port: 1080 + user: myuser + passwd: mypassword + workers: + - name: "us_worker" + type: lmarena +``` + +## Settings + +| Item | Type | Required | Description | +| --- | --- | --- | --- | +| `enable` | boolean | ✅ | Whether to enable the proxy. | +| `type` | string | ✅ | Proxy type: `http` or `socks5`. | +| `host` | string | ✅ | Proxy server address. | +| `port` | number | ✅ | Proxy server port. | +| `user` | string | ❌ | Proxy authentication username. | +| `passwd` | string | ❌ | Proxy authentication password. | + +## Forced Direct Connection + +If you need a specific instance to force a direct connection even when a global proxy is configured: + +```yaml +instances: + - name: "browser_direct" + proxy: + enable: false # Explicitly disable proxy + workers: + - name: "direct_worker" + type: lmarena +``` + +## Proxy Selection Recommendations + +::: tip Recommended Configuration +- **Type**: SOCKS5 proxies are generally more versatile than HTTP proxies. +- **Stability**: Choose stable and reliable proxy service providers. +- **IP Quality**: Use tools like [ping0.cc](https://ping0.cc) to check the quality of your IP. +::: + +::: warning Notes +- Proxy quality directly affects the frequency of CAPTCHA challenges. +- Frequent IP changes may lead to account risk management. +- We recommend using residential IPs or static datacenter IPs. +::: diff --git a/docs/en/guide/deployment.md b/docs/en/guide/deployment.md new file mode 100644 index 0000000..b882c8a --- /dev/null +++ b/docs/en/guide/deployment.md @@ -0,0 +1,94 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# Quick Deployment + +This project supports **Manual Deployment (Recommended)** and **Docker Containerization Deployment**. + +## Manual Deployment + +### 1. Clone the Project + +```bash +git clone https://github.com/foxhui/WebAI2API.git +cd WebAI2API +``` + +### 2. Install Dependencies + +```bash +# 1. Install NPM dependencies +pnpm install +# 2. Install browser and other pre-compiled dependencies +npm run init +# Use a proxy +# Use -proxy to interactively input proxy configuration +npm run init -- -proxy=http://username:passwd@host:port +``` + +::: warning Note +`npm run init` needs to download files from GitHub. Please ensure your network is connected. +::: + +### 3. Start the Service + +```bash +# Standard Start +npm start +# Linux System - Start with Virtual Display +npm start -- -xvfb -vnc +# Login Mode (Temporarily disables headless mode and automation) +npm start -- -login (-xvfb -vnc) +``` + +## Docker Deployment + +::: warning **Security Alert** +- Docker images have Virtual Display (Xvfb) and VNC service enabled by default. +- You can connect through the Virtual Display section of the WebUI. +- **WebUI transmissions are not encrypted. For public network environments, please use SSH tunneling or HTTPS.** +::: + +### Docker CLI + +```bash +docker run -d --name webai-2api \ + -p 3000:3000 \ + -v "$(pwd)/data:/app/data" \ + --shm-size=2gb \ + foxhui/webai-2api:latest +``` + +### Docker Compose + +```yaml +services: + webai-2api: + image: foxhui/webai-2api:latest + container_name: webai-2api + restart: unless-stopped + ports: + - "3000:3000" + volumes: + - ./data:/app/data + shm_size: '2gb' + init: true +``` + +Start the service: + +```bash +docker compose up -d +``` + +## Verify Installation + +After the service starts, visit the following URLs for verification: + +- **Web Management Interface**: http://localhost:3000 +- **API Interface Test**: http://localhost:3000/v1/chat/completions + +## Next Steps + +Once deployment is complete, please read [First Use](/en/guide/first-use) to complete login initialization. diff --git a/docs/en/guide/first-use.md b/docs/en/guide/first-use.md new file mode 100644 index 0000000..4a6a34b --- /dev/null +++ b/docs/en/guide/first-use.md @@ -0,0 +1,109 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# First Use + +When using WebAI2API for the first time, you need to complete the login initialization to use it normally. + +## 1. Adjust Configuration File + +The program will copy the configuration file from `config.example.yaml` to `data/config.yaml` upon its first run. + +::: tip Tip +**Restarts are required for configuration changes to take effect!** +::: + +```yaml +server: + # Listening port + port: 3000 + # Authentication API Token (Generate with: npm run genkey) + # This setting affects both API endpoints and the WebUI + auth: sk-change-me-to-your-secure-key +``` + +## 2. Access Web Management Interface + +Once the service is started, open your browser and visit: +``` +http://localhost:3000 +``` + +::: tip Tip +**Remote Access**: Replace `localhost` with your server's IP address. +**API Token**: The `auth` key configured in the configuration file. +**Security Suggestion**: For public environments, use Nginx/Caddy with HTTPS or access via SSH tunnel. +::: + +## 3. Initialize Account Login + +> [!IMPORTANT] +> **The following initialization steps must be completed for first-time use**: + +1. **Connect to Virtual Display**: + - Linux/Docker: Connect via the "Virtual Display" section in the WebUI. + - Windows: Operable directly in the popup browser window. + +2. **Complete Account Login**: + - Manually log in to the required AI website accounts (check account requirements in the WebUI Adapter Management). + - Send an arbitrary message in the input box to trigger and complete human verification (if necessary). + - Agree to terms of service or新手 (onboarding) guides (if necessary). + - Ensure you are no longer blocked by any "first-time use" content. + +3. **SSH Tunneling Example** (Recommended for public servers): + ```bash + # Run in your local terminal to map the server's WebUI locally + ssh -L 3000:127.0.0.1:3000 root@Server_IP + + # Then access locally + # WebUI: http://localhost:3000 + ``` + +::: tip Running Suggestions +To reduce the risk of being flagged, **we strongly recommend keeping non-headless mode enabled long-term** (or using Virtual Display Xvfb). + +**Regarding Headful/Headless Mode**: +- **Headful Mode** (Default): Shows the browser window, useful for debugging and manual intervention. +- **Headless Mode**: Runs in the background, saves resources, but you cannot view the browser interface, and it may be more easily detected by some websites. +::: + +## Login Mode + +Login mode will force disable headless mode. + +### Basic Usage +```bash +# Start the first Worker for login +npm start -- -login +``` + +### Multi-Worker Login + +If you have configured multiple Workers, you need to complete the login for each one individually: + +```bash +# Log in to each Worker sequentially +npm start -- -login=worker1 +npm start -- -login=worker2 +``` + +::: info Shared Login State +Multiple Workers under the same Instance (browser instance) share the login state. If using Unified Login like Google OAuth, you only need to log in once. +::: + +### WebUI Login Mode + +Once the service is running, you can also switch to login mode via the WebUI: + +1. Visit http://localhost:3000 +2. Go to the "System Management" page +3. Click the dropdown arrow on the "Restart" button +4. Select "Restart in Login Mode" or specify a specific Worker to log in. + +## 4. Next Steps + +Once the login is complete, please read the following: + +- [Configuration Guide](/en/config/overview) - Learn more about all configuration options. +- [API Reference](/en/api/overview) - Start using the API. diff --git a/docs/en/guide/introduction.md b/docs/en/guide/introduction.md new file mode 100644 index 0000000..b262082 --- /dev/null +++ b/docs/en/guide/introduction.md @@ -0,0 +1,42 @@ +# WebAI2API + +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +## Project Introduction + +**WebAI2API** is a tool that converts web-based AI services into a universal API based on **Camoufox (Playwright)**. By mimicking human operations to interact with websites like LMArena and Gemini, it provides interfaces compatible with the **OpenAI format**, while supporting **multi-window concurrency** and **multi-account management** (browser instance data isolation). + +### 📋 Support List + +| Website | Text Gen | Image Gen | Video Gen | +| :--- | :---: | :---: | :---: | +| [**LMArena**](https://lmarena.ai/) | ✅ | ✅ | 🚫 | +| [**Gemini Enterprise Business**](https://business.gemini.google/) | ✅ | ✅ | ✅ | +| [**Nano Banana Free**](https://nanobananafree.ai/) | 🚫 | ✅ | 🚫 | +| [**zAI**](https://zai.is/) | ✅ | ✅ | 🚫 | +| [**Google Gemini**](https://gemini.google.com/) | ✅ | ✅ | ✅ | +| [**ZenMux**](https://zenmux.ai/) | ✅ | ❌ | 🚫 | +| [**ChatGPT**](https://chatgpt.com/) | ✅ | ✅ | 🚫 | +| [**DeepSeek**](https://chat.deepseek.com/) | ✅ | 🚫 | 🚫 | +| [**Sora**](https://sora.chatgpt.com/) | 🚫 | 🚫 | ✅ | +| [**Google Flow**](https://labs.google/fx/zh/tools/flow) | 🚫 | ✅ | ❌ | +| [**Doubao**](https://www.doubao.com/) | ✅ | ✅ | ❌ | +| More coming soon... | - | - | - | + +::: tip Note +**Get Full Model List**: Use the `GET /v1/models` endpoint to view all available models and their details in your current configuration. + +✅ Supported; ❌ Not currently supported, but may be in the future; 🚫 Not supported by the website. +::: + +## Screenshots + +![WebAI2API](/guide_introduction/1.webp) + +![WebAI2API](/guide_introduction/2.webp) + +![WebAI2API](/guide_introduction/3.webp) + +![WebAI2API](/guide_introduction/4.webp) diff --git a/docs/en/guide/requirements.md b/docs/en/guide/requirements.md new file mode 100644 index 0000000..76d210b --- /dev/null +++ b/docs/en/guide/requirements.md @@ -0,0 +1,83 @@ +::: info +This English version is translated by **Gemini 3 Flash**. +::: + +# Requirements + +Before you start deploying WebAI2API, please ensure that your environment meets the following requirements. + +## System Requirements + +### Operating System + +- **Windows**: Windows 10/11 or Windows Server 2016+ +- **Linux**: Ubuntu 18.04+, Debian 10+, CentOS 7+, or other mainstream distributions +- **macOS**: macOS 10.15 (Catalina) or higher + +### Hardware Configuration + +| Resource | Minimum | Recommended (Single Instance) | Recommended (Multi-Instance) | +| :--- | :--- | :--- | :--- | +| **CPU** | 1 Core | 2 Cores or above | 2 Cores or above | +| **Memory** | 1 GB | 2 GB or above | 4 GB or above | +| **Disk** | 2 GB available | 5 GB or above | 7 GB or above | + +::: tip Real-world Performance +- **Oracle Free Tier** (1C1G, Debian 12): Limited resources, can be laggy, suitable for testing or light use only. +- **Alibaba Cloud Lightweight** (2C2G, Debian 11): Runs smoothly, used for project development and testing. +::: + +## Software Dependencies + +### Node.js + +- **Version Requirement**: v20.0.0 or higher (ABI 115+) +- **Package Manager**: pnpm (recommended) or npm + +```bash +# Check Node.js version +node --version + +# Install pnpm (if not installed) +npm install -g pnpm +``` + +### Camoufox + +Camoufox is the core dependency of this project and will be downloaded automatically during the installation process. + +::: warning Network Requirements +The installation process requires downloading pre-compiled dependencies like Camoufox from GitHub. Please ensure your network has access to GitHub. +::: + +## Docker Environment (Optional) + +If you choose to deploy via Docker, you need to install: + +- **Docker**: 20.10.0 or higher +- **Docker Compose**: 2.0.0 or higher (optional) + +```bash +# Check Docker version +docker --version +docker compose version +``` + +## Linux Specific Dependencies + +When running in non-headless mode on Linux, you may need to install additional packages: + +```bash +# Ubuntu/Debian +sudo apt-get install xvfb x11vnc + +# CentOS/RHEL +sudo yum install xorg-x11-server-Xvfb x11vnc + +# Arch Linux +sudo pacman -S xorg-server-xvfb x11vnc +``` + +## Next Steps + +Once your environment is ready, please proceed to [Quick Deployment](/en/guide/deployment) to start the installation. diff --git a/docs/en/index.md b/docs/en/index.md new file mode 100644 index 0000000..1768249 --- /dev/null +++ b/docs/en/index.md @@ -0,0 +1,34 @@ +--- +layout: home + +hero: + name: "WebAI2API" + text: "Web-based AI Services to OpenAI Compatible API" + tagline: Based on Camoufox (Playwright), mimicking human interactions with LMArena, Gemini, and more + actions: + - theme: brand + text: Quick Start + link: /en/guide/deployment + - theme: alt + text: Introduction + link: /en/guide/introduction + - theme: alt + text: GitHub + link: https://github.com/foxhui/WebAI2API + image: + src: /favicon.png + +features: + - icon: 🤖 + title: Human-like Interaction + details: Mimics human typing and mouse trajectories, evading automation detection via feature camouflaging. + - icon: 🎨 + title: Web Management + details: Provides a visual management interface supporting real-time logs, VNC connection, and adapter management. + - icon: 🚀 + title: Concurrent Isolation + details: Supports multi-window concurrency with instance-level data isolation for multiple accounts. + - icon: 🛡️ + title: Stable Protection + details: Built-in task queue, load balancing, failover, and error retries. +--- diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md index 5abc4ba..b1be5cd 100644 --- a/docs/guide/introduction.md +++ b/docs/guide/introduction.md @@ -18,6 +18,7 @@ | [**DeepSeek**](https://chat.deepseek.com/) | ✅ | 🚫 | 🚫 | | [**Sora**](https://sora.chatgpt.com/) | 🚫 | 🚫 | ✅ | | [**Google Flow**](https://labs.google/fx/zh/tools/flow) | 🚫 | ✅ | ❌ | +| [**豆包**](https://www.doubao.com/) | ✅ | ✅ | ❌ | | 待续... | - | - | - | ::: tip 实测环境表现 @@ -28,10 +29,10 @@ ## 项目截图 -![Image](https://github.com/user-attachments/assets/296a518e-c42b-4e39-8ff6-9b4381ed4f6e) +![Image](/guide_introduction/1.webp) -![Image](https://github.com/user-attachments/assets/bfa30ece-6947-4f18-b2c9-ccc8087b7e89) +![Image](/guide_introduction/2.webp) -![Image](https://github.com/user-attachments/assets/5b15ebd2-7593-4f0e-8561-83d6ba5d88ab) +![Image](/guide_introduction/3.webp) -![Image](https://github.com/user-attachments/assets/53deea29-4071-4a07-8a61-211761c5f2f7) +![Image](/guide_introduction/4.webp) diff --git a/docs/public/guide_introduction/1.webp b/docs/public/guide_introduction/1.webp new file mode 100644 index 0000000..662c081 Binary files /dev/null and b/docs/public/guide_introduction/1.webp differ diff --git a/docs/public/guide_introduction/2.webp b/docs/public/guide_introduction/2.webp new file mode 100644 index 0000000..83d3a46 Binary files /dev/null and b/docs/public/guide_introduction/2.webp differ diff --git a/docs/public/guide_introduction/3.webp b/docs/public/guide_introduction/3.webp new file mode 100644 index 0000000..4ed218b Binary files /dev/null and b/docs/public/guide_introduction/3.webp differ diff --git a/docs/public/guide_introduction/4.webp b/docs/public/guide_introduction/4.webp new file mode 100644 index 0000000..497e3d8 Binary files /dev/null and b/docs/public/guide_introduction/4.webp differ