### Manual Deployment and Startup

Source: https://context7.com/foxhui/webai2api/llms.txt

Commands for installing dependencies, initializing browser environments, and starting the service on Linux or local machines.

```bash
# 1. 安装 NPM 依赖
pnpm install

# 2. 安装预编译依赖（浏览器等）
# 需要连接 GitHub 下载资源，网络受限时使用代理
npm run init
# 使用代理
npm run init -- -proxy=http://username:passwd@host:port

# 3. Linux 依赖安装
apt install -y xvfb x11vnc libgtk-3-0 libx11-xcb1 libasound2

# 4. 启动服务
npm start

# Linux - 使用虚拟显示启动
npm start -- -xvfb -vnc

# 登录模式（强制关闭无头模式和自动化特征）
npm start -- -login
npm start -- -login=workerName  # 指定 Worker 登录
```

--------------------------------

### System Status Response Example

Source: https://context7.com/foxhui/webai2api/llms.txt

Example response for the system status endpoint. It provides uptime in seconds, CPU usage percentage, and memory usage in bytes (used and total).

```json
{
  "uptime": 3600,
  "cpu": {"usage": 25.5},
  "memory": {"used": 512000000, "total": 2048000000},
  "safeMode": {"enabled": false, "reason": null}
}
```

--------------------------------

### Model List Response Example

Source: https://context7.com/foxhui/webai2api/llms.txt

Example response when requesting the list of available models. It details each model's ID, creation timestamp, owner, image policy, and type.

```json
{
  "object": "list",
  "data": [
    {
      "id": "gemini-3.1-flash",
      "object": "model",
      "created": 1234567890,
      "owned_by": "gemini_text",
      "image_policy": "optional",
      "type": "text"
    },
    {
      "id": "gemini-3-pro-image-preview",
      "object": "model",
      "created": 1234567890,
      "owned_by": "lmarena",
      "image_policy": "optional",
      "type": "image"
    },
    {
      "id": "flux-2-pro",
      "object": "model",
      "created": 1234567890,
      "owned_by": "lmarena",
      "image_policy": "optional",
      "type": "image"
    },
    {
      "id": "p-image-edit",
      "object": "model",
      "created": 1234567890,
      "owned_by": "lmarena",
      "image_policy": "required",
      "type": "image"
    }
  ]
}
```

--------------------------------

### Configure Server Settings

Source: https://github.com/foxhui/webai2api/blob/main/README.md

Example configuration for the server port and authentication token in data/config.yaml.

```yaml
server:
  # 监听端口
  port: 3000
  # 鉴权 API Token (可使用 npm run genkey 生成)
  # 该配置会对 API 接口和 WebUI 生效
  auth: sk-change-me-to-your-secure-key
```

--------------------------------

### Configuration File (config.yaml)

Source: https://context7.com/foxhui/webai2api/llms.txt

Example configuration for server settings, backend instances, and browser behavior.

```yaml
# 日志等级: debug | info | warn | error
logLevel: info

server:
  # 监听端口
  port: 3000
  # 鉴权 API Token (至少 10 个字符)
  auth: sk-change-me-to-your-secure-key
  # 流式请求心跳设置
  keepalive:
    # 心跳模式: "comment" (推荐) 或 "content"
    mode: "comment"

backend:
  pool:
    # 调度策略: least_busy | round_robin | random
    strategy: least_busy

    # 故障转移配置
    failover:
      enabled: true
      maxRetries: 2
      imgDlRetry: false
      imgDlRetryMaxRetries: 2

    # 生成等待超时（毫秒）
    waitTimeout: 120000

    # 浏览器实例列表
    instances:
      - name: "browser_default"
        workers:
          - name: "default"
            # 适配器类型: lmarena, lmarena_text, gemini_biz, gemini_biz_text,
            # gemini, gemini_text, chatgpt, chatgpt_text, deepseek_text,
            # zai_is, zai_is_text, nanobananafree_ai, zenmux_ai_text,
            # sora, doubao, doubao_text, google_flow
            type: lmarena

      # 多实例配置示例（独立数据目录 + 专属代理）
      - name: "browser_us_01"
        userDataMark: "us_01"  # 数据目录: data/camoufoxUserData_us_01
        proxy:
          enable: true
          type: socks5
          host: 192.168.1.10
          port: 1080
          user: myuser
          passwd: mypassword
        workers:
          - name: "us_lmarena"
            type: lmarena
          - name: "us_gemini"
            type: gemini_biz_text

  # 适配器专属配置
  adapter:
    gemini_biz:
      entryUrl: "https://business.gemini.google/home/cid/8888a888-b6e0-88be-86e1-888cf3ee8cf4"
    lmarena:
      returnUrl: false  # 开启后直接返回图片 URL
      modelFilter:
        mode: whitelist  # whitelist | blacklist
        list:
          - gemini-3-pro-image-preview
          - gemini-2.5-flash-image-preview

queue:
  # 队列缓冲区大小（非流式请求额外排队数）
  queueBuffer: 2
  # 图片数量上限（最大 10）
  imageLimit: 5

browser:
  # 浏览器可执行文件路径（留空使用默认）
  path: ""
  # 是否启用无头模式
  headless: false
  # 拟人鼠标轨迹: false | true | "camou"
  humanizeCursor: true
  # 站点隔离（关闭可降低内存占用）
  fission: true
  # CSS 性能优化注入
  cssInject:
    animation: false  # 禁用网页动画
    filter: false     # 禁用滤镜和阴影
    font: false       # 降低字体渲染质量
  # 全局代理配置
  proxy:
    enable: false
    type: http  # http | socks5
    host: 127.0.0.1
    port: 7890
```

--------------------------------

### Start the Service

Source: https://github.com/foxhui/webai2api/blob/main/README.md

Commands to launch the service in standard, virtual display, or login modes.

```bash
npm start
npm start -- -xvfb -vnc
npm start -- -login (-xvfb -vnc)
```

--------------------------------

### GET /v1/models

Source: https://github.com/foxhui/webai2api/blob/main/README.md

Retrieve the list of all available models and their detailed configurations.

```APIDOC
## GET /v1/models

### Description
Retrieve the list of all available models and their detailed configurations based on the current server setup.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **data** (array) - List of available models and their metadata.
```

--------------------------------

### Get All Adapter Metadata

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve metadata for all available adapters. Requires an Authorization header.

```bash
curl http://localhost:3000/admin/adapters \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Cookies Response Example

Source: https://context7.com/foxhui/webai2api/llms.txt

Example response when requesting cookies. It includes the worker name and a list of cookies, each with its name, value, domain, path, expiration, and security flags.

```json
{
  "worker": "browser_default",
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123...",
      "domain": ".lmarena.ai",
      "path": "/",
      "expires": 1735689600,
      "httpOnly": true,
      "secure": true
    }
  ]
}
```

--------------------------------

### Image Generation Response Example (Streaming, Base64)

Source: https://context7.com/foxhui/webai2api/llms.txt

Example of a streaming response for image generation, where image data is provided in Base64 format.

```APIDOC
### Response Example (Streaming, Base64)

```
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","model":"flux-2-pro","choices":[{"delta":{"content":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."},"finish_reason":"stop"}]}
data: [DONE]
```
```

--------------------------------

### Image Generation Request

Source: https://context7.com/foxhui/webai2api/llms.txt

Example of sending a multi-modal request for image generation.

```bash
# 文生图请求
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "messages": [
      {
        "role": "user",
        "content": "生成一只可爱的橘猫坐在窗台上看夕阳的图片"
      }
    ],
    "stream": true
  }'
```

--------------------------------

### Task Queue Status Response Example

Source: https://context7.com/foxhui/webai2api/llms.txt

Example response for the task queue status. It shows the total, processing, and waiting task counts, along with details of tasks currently in progress or queued.

```json
{
  "processing": 2,
  "waiting": 5,
  "total": 7,
  "processingTasks": [
    {"id": "abc123", "model": "gemini-3.1-flash", "startTime": 1234567890}
  ],
  "waitingTasks": [
    {"id": "def456", "model": "flux-2-pro", "queueTime": 1234567891}
  ]
}
```

--------------------------------

### Install Linux System Dependencies

Source: https://github.com/foxhui/webai2api/blob/main/README.md

Required system packages for running the service on Linux distributions.

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

--------------------------------

### Initialize NPM Dependencies

Source: https://github.com/foxhui/webai2api/blob/main/README.md

Install project dependencies and browser binaries. Use the -proxy flag if network access to GitHub is restricted.

```bash
pnpm install
npm run init
npm run init -- -proxy=http://username:passwd@host:port
```

--------------------------------

### OpenAI Compatible API Requests

Source: https://context7.com/foxhui/webai2api/llms.txt

Examples for sending text completion requests and handling responses using the OpenAI-compatible API.

```bash
# 基础文本对话请求（流式）
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "gemini-3.1-flash",
    "messages": [
      {"role": "system", "content": "你是一个有帮助的助手。"},
      {"role": "user", "content": "你好，请介绍一下自己"}
    ],
    "stream": true
  }'

# 非流式响应示例
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "gemini-3.1-pro",
    "messages": [
      {"role": "user", "content": "解释什么是机器学习"}
    ],
    "stream": false
  }'

# 响应示例（非流式）
{
  "id": "chatcmpl-1234567890",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gemini-3.1-pro",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "机器学习是人工智能的一个分支..."
    },
    "finish_reason": "stop"
  }]
}

# 启用推理/思考过程输出
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "gemini-3.1-flash-thinking",
    "messages": [{"role": "user", "content": "分析这个数学问题"}],
    "stream": true,
    "reasoning": true
  }'
```

--------------------------------

### Get Instance/Worker Configuration

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve the current configuration for instances and workers. Requires an Authorization header.

```bash
curl http://localhost:3000/admin/config/instances \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Get Load Balancing and Failover Configuration

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve the current load balancing and failover settings. Requires an Authorization header.

```bash
curl http://localhost:3000/admin/config/pool \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Request OpenAI Compatible Chat Completion

Source: https://github.com/foxhui/webai2api/blob/main/README.md

Example cURL request to the /v1/chat/completions endpoint.

```bash
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": "你好,请介绍一下你自己"}
    ],
    "stream": true
  }'
```

--------------------------------

### Image Generation Streaming Response Example

Source: https://context7.com/foxhui/webai2api/llms.txt

Example of a streaming response for image generation, where image data is provided in Base64 format within JSON chunks. The stream ends with a `[DONE]` marker.

```json
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","model":"flux-2-pro","choices":[{"delta":{"content":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."},"finish_reason":"stop"}]}
data: [DONE]
```

--------------------------------

### Get Server Configuration

Source: https://context7.com/foxhui/webai2api/llms.txt

Fetches the current server configuration settings. This is useful for auditing or understanding the current operational parameters of the server.

```bash
curl http://localhost:3000/admin/config/server \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Get History Statistics Summary

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve a summary of statistics for request history within a specified date range. Requires start and end date parameters and an Authorization header.

```bash
curl "http://localhost:3000/admin/history/stats?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### GET /v1/models

Source: https://github.com/foxhui/webai2api/blob/main/README.md

Retrieves a list of available models that can be used for generation tasks.

```APIDOC
## GET /v1/models

### Description
Fetches a list of all available AI models supported by the API.

### Method
GET

### Endpoint
`/v1/models`

### Request Example
```bash
curl http://localhost:3000/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **models** (array) - A list of available model objects.
  - **id** (string) - The unique identifier for the model.
  - **name** (string) - The display name of the model.

#### Response Example
```json
{
  "models": [
    {
      "id": "sdxl-1024",
      "name": "Stable Diffusion XL 1024"
    },
    {
      "id": "dall-e-3",
      "name": "DALL-E 3"
    }
  ]
}
```
```

--------------------------------

### Get Available Models

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve a list of all models available on the server, including their image input policies and types. This is useful for selecting the appropriate model for your task.

```bash
curl http://localhost:3000/v1/models \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Get Browser Configuration

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieves the current configuration settings for the browser component. This helps in understanding how the browser automation is set up.

```bash
curl http://localhost:3000/admin/config/browser \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Get Available Models

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieves a list of all available models, including their image input policies and types.

```APIDOC
## GET /v1/models

### Description
Fetches a list of all models available in the current configuration, including information about their image input capabilities and model type.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **object** (string) - The type of object returned (e.g., "list").
- **data** (array) - An array of model objects.
  - **id** (string) - The unique identifier for the model.
  - **object** (string) - The type of the object (e.g., "model").
  - **created** (integer) - Timestamp of when the model was created.
  - **owned_by** (string) - The entity that owns the model.
  - **image_policy** (string) - The policy for image input (e.g., "optional", "required").
  - **type** (string) - The type of the model (e.g., "text", "image").

### Request Example
```bash
curl http://localhost:3000/v1/models \
  -H "Authorization: Bearer sk-your-api-key"
```

### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "gemini-3.1-flash",
      "object": "model",
      "created": 1234567890,
      "owned_by": "gemini_text",
      "image_policy": "optional",
      "type": "text"
    },
    {
      "id": "gemini-3-pro-image-preview",
      "object": "model",
      "created": 1234567890,
      "owned_by": "lmarena",
      "image_policy": "optional",
      "type": "image"
    },
    {
      "id": "flux-2-pro",
      "object": "model",
      "created": 1234567890,
      "owned_by": "lmarena",
      "image_policy": "optional",
      "type": "image"
    },
    {
      "id": "p-image-edit",
      "object": "model",
      "created": 1234567890,
      "owned_by": "lmarena",
      "image_policy": "required",
      "type": "image"
    }
  ]
}
```
```

--------------------------------

### Get Cookies

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieves cookies for a specified browser instance and domain.

```APIDOC
## GET /v1/cookies

### Description
Retrieves cookies for a specified browser instance. This can be used for integration with other tools and to leverage the project's automatic renewal feature.

### Method
GET

### Endpoint
/v1/cookies

### Query Parameters
- **name** (string) - Optional - The name of the browser instance (default: "browser_default").
- **domain** (string) - Optional - The domain for which to retrieve cookies.

### Response
#### Success Response (200)
- **worker** (string) - The name of the browser worker.
- **cookies** (array) - An array of cookie objects.
  - **name** (string) - The name of the cookie.
  - **value** (string) - The value of the cookie.
  - **domain** (string) - The domain the cookie belongs to.
  - **path** (string) - The path the cookie is valid for.
  - **expires** (integer) - The expiration timestamp of the cookie.
  - **httpOnly** (boolean) - Indicates if the cookie is HTTP-only.
  - **secure** (boolean) - Indicates if the cookie is secure.

### Request Example
```bash
# Get all cookies for the default instance
curl "http://localhost:3000/v1/cookies" \
  -H "Authorization: Bearer sk-your-api-key"

# Get cookies for a specific instance and domain
curl "http://localhost:3000/v1/cookies?name=browser_default&domain=lmarena.ai" \
  -H "Authorization: Bearer sk-your-api-key"
```

### Response Example
```json
{
  "worker": "browser_default",
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123...",
      "domain": ".lmarena.ai",
      "path": "/",
      "expires": 1735689600,
      "httpOnly": true,
      "secure": true
    }
  ]
}
```
```

--------------------------------

### Get List of Models Used in History

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve a list of all models that have been used in the request history. Requires an Authorization header.

```bash
curl http://localhost:3000/admin/history/models \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Get VNC Status

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve the current status of the VNC server. Requires an Authorization header.

```bash
curl http://localhost:3000/admin/vnc/status \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Retrieve Model List via cURL

Source: https://github.com/foxhui/webai2api/blob/main/README.md

Fetches the list of available models using the GET /v1/models endpoint.

```bash
curl http://localhost:3000/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Get Cookies for Specific Instance and Domain

Source: https://context7.com/foxhui/webai2api/llms.txt

Fetch cookies for a particular browser instance and domain. This allows for more targeted cookie retrieval, essential for specific web interactions.

```bash
curl "http://localhost:3000/v1/cookies?name=browser_default&domain=lmarena.ai" \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Get Basic Statistics

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve basic statistics including today's successful and failed requests. Requires an Authorization header.

```bash
curl http://localhost:3000/admin/stats \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### GET /v1/cookies

Source: https://github.com/foxhui/webai2api/blob/main/README.md

Obtains the latest cookies for use with other tools, leveraging the project's auto-login functionality.

```APIDOC
## GET /v1/cookies

### Description
Retrieves the latest cookies, utilizing the project's automatic login feature, which can be used by other tools.

### Method
GET

### Endpoint
`/v1/cookies`

### Query Parameters
- **name** (string) - Optional - The name of the browser instance. Defaults to `default`.
- **domain** (string) - Optional - Filters cookies for a specific domain.

### Request Example
```bash
# 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"
```

### Response
#### Success Response (200)
- **cookies** (array) - A list of cookie objects.
  - **name** (string) - The name of the cookie.
  - **value** (string) - The value of the cookie.
  - **domain** (string) - The domain the cookie belongs to.
  - **path** (string) - The path the cookie is valid for.
  - **expires** (number) - The expiration date of the cookie as a Unix timestamp.
  - **httpOnly** (boolean) - Whether the cookie is accessible only via HTTP.
  - **secure** (boolean) - Whether the cookie is sent over secure connections.
  - **sameSite** (string) - The SameSite attribute of the cookie.

#### Response Example
```json
{
  "cookies": [
    {
      "name": "sessionid",
      "value": "abcdef12345",
      "domain": "lmarena.ai",
      "path": "/",
      "expires": 1700000000,
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    }
  ]
}
```
```

--------------------------------

### Get Media File from History

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve a media file associated with a history record. Requires the media file name and an Authorization header. Use --output to save the file.

```bash
curl http://localhost:3000/admin/history/media/image_123.png \
  -H "Authorization: Bearer sk-your-api-key" \
  --output image.png
```

--------------------------------

### Get All Cookies from Default Browser Instance

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve all cookies associated with the default browser instance. This is useful for integrating with other tools that require cookie data.

```bash
curl "http://localhost:3000/v1/cookies" \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Get Request History List (Paginated)

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve a paginated list of request history. Requires page and pageSize parameters, and an Authorization header.

```bash
curl "http://localhost:3000/admin/history?page=1&pageSize=20" \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Retrieve Cookies via cURL

Source: https://github.com/foxhui/webai2api/blob/main/README.md

Fetches cookies for a specific browser instance and domain using the GET /v1/cookies endpoint.

```bash
# 获取指定实例和域名的 Cookie
curl "http://localhost:3000/v1/cookies?name=browser_default&domain=lmarena.ai" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Query Statistics for a Date Range

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve statistics for a specified date range. Requires start and end date parameters and an Authorization header.

```bash
curl "http://localhost:3000/admin/stats/range?start=2024-01-01&end=2024-01-31" \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Get Single Request History Detail

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve the details of a single request history item by its ID. Requires the request ID and an Authorization header.

```bash
curl http://localhost:3000/admin/history/abc123 \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Get System Status

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve the current operational status of the system, including CPU and memory usage, and whether safe mode is enabled. This is crucial for monitoring system health.

```bash
curl http://localhost:3000/admin/status \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Get Task Queue Status

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieves the current status of the task queue, including the number of tasks being processed and waiting. This helps in understanding system load and task progression.

```bash
curl http://localhost:3000/admin/queue \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Delete History Records by Date Range

Source: https://context7.com/foxhui/webai2api/llms.txt

Delete all history records within a specified date range. Requires DELETE method, start and end date query parameters, and an Authorization header.

```bash
curl -X DELETE "http://localhost:3000/admin/history?startDate=2024-01-01&endDate=2024-01-15" \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Deploy with Docker

Source: https://github.com/foxhui/webai2api/blob/main/README.md

Run the service using Docker CLI or Docker Compose.

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

```bash
docker-compose up -d
```

--------------------------------

### Get/Update Adapter Configuration

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve or update the configuration for adapters. Use POST for updates with JSON payload and Authorization header.

```bash
curl http://localhost:3000/admin/config/adapters \
  -H "Authorization: Bearer sk-your-api-key"
```

```bash
curl -X POST http://localhost:3000/admin/config/adapters \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "lmarena": {
      "returnUrl": true,
      "modelFilter": {"mode": "whitelist", "list": ["gemini-3-pro-image-preview"]}
    },
    "gemini_biz": {
      "entryUrl": "https://business.gemini.google/home/cid/xxx"
    }
  }'
```

--------------------------------

### List Data Folders

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve a list of available data folders. Requires an Authorization header.

```bash
curl http://localhost:3000/admin/data-folders \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Configuration Management

Source: https://context7.com/foxhui/webai2api/llms.txt

Endpoints for retrieving and updating system configurations.

```APIDOC
## GET /admin/config/instances

### Description
Retrieves the instance/worker configuration.

### Method
GET

### Endpoint
/admin/config/instances

### Request Example
```bash
curl http://localhost:3000/admin/config/instances \
  -H "Authorization: Bearer sk-your-api-key"
```

## GET /admin/config/pool

### Description
Retrieves the load balancing and failover configuration.

### Method
GET

### Endpoint
/admin/config/pool

### Request Example
```bash
curl http://localhost:3000/admin/config/pool \
  -H "Authorization: Bearer sk-your-api-key"
```

## POST /admin/config/pool

### Description
Updates the pool configuration, including strategy and failover settings.

### Method
POST

### Endpoint
/admin/config/pool

### Request Body
- **strategy** (string) - Required - The load balancing strategy (e.g., "least_busy").
- **failover** (object) - Optional - Failover configuration.
  - **enabled** (boolean) - Required - Whether failover is enabled.
  - **maxRetries** (integer) - Required - Maximum number of retries.

### Request Example
```json
{
  "strategy": "least_busy",
  "failover": {"enabled": true, "maxRetries": 3}
}
```
```

--------------------------------

### Adapter Management

Source: https://context7.com/foxhui/webai2api/llms.txt

Endpoints for managing AI model adapters.

```APIDOC
## GET /admin/adapters

### Description
Retrieves metadata for all available adapters.

### Method
GET

### Endpoint
/admin/adapters

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the adapter.
- **displayName** (string) - User-friendly name of the adapter.
- **description** (string) - Description of the adapter's functionality.
- **modelCount** (integer) - Number of models supported by the adapter.
- **models** (array of strings) - List of model names supported by the adapter.
- **modelFilter** (object) - Configuration for filtering models.
  - **mode** (string) - "blacklist" or "whitelist".
  - **list** (array of strings) - List of models in the filter.
- **configSchema** (array of objects) - Schema for adapter-specific configuration.
  - **key** (string) - Configuration key.
  - **label** (string) - User-friendly label for the configuration.
  - **type** (string) - Data type of the configuration (e.g., "boolean").
  - **default** (any) - Default value for the configuration.

### Response Example
```json
[
  {
    "id": "lmarena",
    "displayName": "LMArena (图片生成)",
    "description": "使用 LMArena 平台生成图片，支持多种图片生成模型。",
    "modelCount": 40,
    "models": ["gemini-3-pro-image-preview", "flux-2-pro", "gpt-image-1"],
    "modelFilter": {"mode": "blacklist", "list": []},
    "configSchema": [
      {"key": "returnUrl", "label": "返回图片 URL", "type": "boolean", "default": false}
    ]
  }
]
```

## GET /admin/config/adapters

### Description
Retrieves the current configuration for adapters.

### Method
GET

### Endpoint
/admin/config/adapters

### Request Example
```bash
curl http://localhost:3000/admin/config/adapters \
  -H "Authorization: Bearer sk-your-api-key"
```

## POST /admin/config/adapters

### Description
Updates the configuration for one or more adapters.

### Method
POST

### Endpoint
/admin/config/adapters

### Request Body
- **adapterId** (object) - Required - An object where keys are adapter IDs and values are their configurations.
  - **returnUrl** (boolean) - Optional - Specific to 'lmarena' adapter.
  - **modelFilter** (object) - Optional - Model filtering configuration.
    - **mode** (string) - Required - "whitelist" or "blacklist".
    - **list** (array of strings) - Required - List of models.
  - **entryUrl** (string) - Optional - Specific to 'gemini_biz' adapter.

### Request Example
```json
{
  "lmarena": {
    "returnUrl": true,
    "modelFilter": {"mode": "whitelist", "list": ["gemini-3-pro-image-preview"]}
  },
  "gemini_biz": {
    "entryUrl": "https://business.gemini.google/home/cid/xxx"
  }
}
```
```

--------------------------------

### Admin API - Configuration Management

Source: https://context7.com/foxhui/webai2api/llms.txt

Endpoints for retrieving and updating server and browser configurations.

```APIDOC
## GET /admin/config/server, POST /admin/config/server, GET /admin/config/browser, POST /admin/config/browser

### Description
Provides endpoints to manage server and browser configurations. You can retrieve the current settings or update them with new values.

### Method
GET (retrieve configuration), POST (update configuration)

### Endpoint
- `/admin/config/server` (for server configuration)
- `/admin/config/browser` (for browser configuration)

### Request Body (for POST requests)
#### Server Configuration Update
- **port** (integer) - Optional - The port the server listens on.
- **auth** (string) - Optional - The API key for authentication.
- **queueBuffer** (integer) - Optional - The buffer size for the task queue.
- **imageLimit** (integer) - Optional - The limit for image processing.

#### Browser Configuration Update
- **headless** (boolean) - Optional - Whether to run the browser in headless mode.
- **humanizeCursor** (boolean) - Optional - Whether to humanize the cursor movement.
- **fission** (boolean) - Optional - Whether to enable fission mode.

### Request Example
```bash
# Get server configuration
curl http://localhost:3000/admin/config/server \
  -H "Authorization: Bearer sk-your-api-key"

# Update server configuration
curl -X POST http://localhost:3000/admin/config/server \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ 
    "port": 3000, 
    "auth": "sk-new-api-key", 
    "queueBuffer": 3, 
    "imageLimit": 5 
  }'

# Get browser configuration
curl http://localhost:3000/admin/config/browser \
  -H "Authorization: Bearer sk-your-api-key"

# Update browser configuration
curl -X POST http://localhost:3000/admin/config/browser \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ 
    "headless": false, 
    "humanizeCursor": true, 
    "fission": true 
  }'
```
```

--------------------------------

### Restart Service (Normal)

Source: https://context7.com/foxhui/webai2api/llms.txt

Initiates a standard restart of the service. Use this for routine maintenance or after configuration changes that require a service reload.

```bash
curl -X POST http://localhost:3000/admin/restart \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Multi-Image Input Request

Source: https://context7.com/foxhui/webai2api/llms.txt

This endpoint supports combining multiple images (up to 10) into a single output. Each image should be provided as a separate image_url object in the content array.

```bash
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "gpt-image-1",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "将这两张图片合成为一张"},
          {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGg..."}},
          {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGg..."}}
        ]
      }
    ],
    "stream": true
  }'
```

--------------------------------

### Image to Image Request with Reference Image

Source: https://context7.com/foxhui/webai2api/llms.txt

Use this endpoint to transform an image into a different style using a reference image. Ensure the image URL is correctly formatted with base64 encoding.

```bash
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "flux-2-pro",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "将这张图片转换为水彩画风格"},
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
            }
          }
        ]
      }
    ],
    "stream": true
  }'
```

--------------------------------

### Clear Cache

Source: https://context7.com/foxhui/webai2api/llms.txt

Clear the system cache. Requires POST method and an Authorization header.

```bash
curl -X POST http://localhost:3000/admin/cache/clear \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Image Generation (with reference image)

Source: https://context7.com/foxhui/webai2api/llms.txt

This endpoint allows for image generation based on a text prompt and a reference image. It supports streaming responses.

```APIDOC
## POST /v1/chat/completions

### Description
Generates an image based on a text prompt and a reference image, with support for streaming responses.

### Method
POST

### Endpoint
http://localhost:3000/v1/chat/completions

### Request Body
- **model** (string) - Required - The model to use for generation (e.g., "flux-2-pro").
- **messages** (array) - Required - An array of message objects. Each object can contain text and/or image URLs.
  - **role** (string) - Required - The role of the message sender (e.g., "user").
  - **content** (array) - Required - An array of content parts.
    - **type** (string) - Required - The type of content (e.g., "text", "image_url").
    - **text** (string) - Optional - The text content.
    - **image_url** (object) - Optional - An object containing the image URL.
      - **url** (string) - Required - The URL of the image (can be a data URL).
- **stream** (boolean) - Optional - Whether to stream the response.
```

--------------------------------

### Read System Logs

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve recent system logs. Specify the number of lines to retrieve using the 'lines' parameter. Requires an Authorization header.

```bash
curl "http://localhost:3000/admin/logs?lines=200" \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Delete Statistics for a Date Range

Source: https://context7.com/foxhui/webai2api/llms.txt

Delete statistics within a specified date range. Requires DELETE method, start and end date parameters, and an Authorization header.

```bash
curl -X DELETE "http://localhost:3000/admin/stats/range?start=2024-01-01&end=2024-01-15" \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Query Request History with Filters

Source: https://context7.com/foxhui/webai2api/llms.txt

Retrieve request history with filtering by status, model, and date range. Requires relevant query parameters and an Authorization header.

```bash
curl "http://localhost:3000/admin/history?status=success&model=gemini-3.1-flash&startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer sk-your-api-key"
```

--------------------------------

### Multimodal Request (Text-to-Image / Image-to-Image)

Source: https://github.com/foxhui/webai2api/blob/main/README.md

This section describes how to make multimodal requests for image generation. It specifies supported image formats, data formatting, and automatic conversion by the server. It also details the parameters `model` and `stream`, including the recommended heartbeat mechanism for stream responses.

```APIDOC
## Multimodal Request (Text-to-Image / Image-to-Image)

### Description
Supports text-to-image and image-to-image generation requests. Images must be provided in Base64 Data URL format.

### Supported Image Formats
- **Formats**: PNG, JPEG, GIF, WebP
- **Quantity**: Maximum 10 images (specific limits may vary by website)
- **Data Format**: Must use Base64 Data URL format
- **Automatic Conversion**: Server automatically converts all images to JPG for compatibility.

### Parameters
#### Request Body Parameters
- **model** (string) - Required - Model name. Use `/v1/models` to get a list of available models.
- **stream** (boolean) - Recommended - Whether to enable streaming responses, including a heartbeat mechanism.

### Heartbeat Mechanism
To prevent long connection timeouts, the system offers two heartbeat modes:
1. **Comment Mode (Default/Recommended)**: Sends `:keepalive` comments, adhering to SSE standards for best compatibility.
2. **Content Mode**: Sends empty data packets, intended for specific clients that only reset timeouts upon receiving JSON data.

### Request Example
```json
{
  "prompt": "A futuristic cityscape at sunset",
  "model": "stable-diffusion-xl-1024-v1-0",
  "stream": true,
  "images": [
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
  ]
}
```

### Response Example (Stream)
```
:keepalive
data: {"message": "Processing image..."}

data: {"progress": 50}

data: {"image_url": "http://example.com/image.jpg"}
```
```

--------------------------------

### Statistics and Logs

Source: https://context7.com/foxhui/webai2api/llms.txt

Endpoints for retrieving and managing system statistics and logs.

```APIDOC
## GET /admin/stats

### Description
Retrieves basic statistics, including today's success and failure counts.

### Method
GET

### Endpoint
/admin/stats

### Response
#### Success Response (200)
- **instances** (integer) - Number of active instances.
- **workers** (integer) - Number of active workers.
- **success** (integer) - Count of successful operations.
- **failed** (integer) - Count of failed operations.

### Response Example
```json
{
  "instances": 2,
  "workers": 4,
  "success": 150,
  "failed": 3
}
```

## GET /admin/stats/range

### Description
Queries statistics for a specified date range.

### Method
GET

### Endpoint
/admin/stats/range

### Query Parameters
- **start** (string) - Required - Start date in YYYY-MM-DD format.
- **end** (string) - Required - End date in YYYY-MM-DD format.

### Request Example
```bash
curl "http://localhost:3000/admin/stats/range?start=2024-01-01&end=2024-01-31" \
  -H "Authorization: Bearer sk-your-api-key"
```

## DELETE /admin/stats/range

### Description
Deletes statistics for a specified date range.

### Method
DELETE

### Endpoint
/admin/stats/range

### Query Parameters
- **start** (string) - Required - Start date in YYYY-MM-DD format.
- **end** (string) - Required - End date in YYYY-MM-DD format.

### Request Example
```bash
curl -X DELETE "http://localhost:3000/admin/stats/range?start=2024-01-01&end=2024-01-15" \
  -H "Authorization: Bearer sk-your-api-key"
```

## GET /admin/logs

### Description
Retrieves system logs, with an option to specify the number of lines.

### Method
GET

### Endpoint
/admin/logs

### Query Parameters
- **lines** (integer) - Optional - Number of recent lines to retrieve (default is 200).

### Request Example
```bash
curl "http://localhost:3000/admin/logs?lines=200" \
  -H "Authorization: Bearer sk-your-api-key"
```

## DELETE /admin/logs

### Description
Clears all system logs.

### Method
DELETE

### Endpoint
/admin/logs

### Request Example
```bash
curl -X DELETE http://localhost:3000/admin/logs \
  -H "Authorization: Bearer sk-your-api-key"
```

## POST /admin/cache/clear

### Description
Clears the system cache.

### Method
POST

### Endpoint
/admin/cache/clear

### Request Example
```bash
curl -X POST http://localhost:3000/admin/cache/clear \
  -H "Authorization: Bearer sk-your-api-key"
```
```