Qwen2API Enterprise Gateway

https://github.com/yujunzhixue/qwen2api
Admin
A unified gateway converting Qwen web chat capabilities to OpenAI, Anthropic Claude, and Gemini...
Tokens:8,931
Snippets:102
Trust Score:6.5
Update:4 months ago
Show doc for...
Tokens:
Raw
### Schema Compression Example Output

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Example of the output after schema compression.

```text
{file_path!: string, encoding?: utf-8|base64}
```

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

### Local development environment setup

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Commands to set up the backend and frontend development environments.

```bash
# Backend
python -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -r backend/requirements.txt
uvicorn backend.main:app --reload --port 7860
```

```bash
# Frontend (in another terminal)
cd frontend
npm install
npm run dev                          # http://localhost:5173
```

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

### Start Service Command

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Command to start the Qwen2API service using Docker Compose.

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

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

### Environment Variables Configuration

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Example .env file for configuring Qwen2API settings.

```env
# ========== 必须修改 ==========
ADMIN_KEY=change-me-now              # 管理台登录密钥，必须修改为强密码！

# ========== 基础配置 ==========
PORT=7860                            # 服务监听端口
WORKERS=1                            # Uvicorn worker 数量，必须保持 1（多 worker 会导致 JSON 文件冲突）
LOG_LEVEL=INFO                       # 日志级别：DEBUG/INFO/WARNING/ERROR

# ========== 并发控制 ==========
MAX_INFLIGHT=1                       # 每账号最大并发请求数（账号多时可改为 2）
MAX_RETRIES=3                        # 请求失败最大重试次数（网络不稳定时增加到 5）

# ========== 限流冷却 ==========
ACCOUNT_MIN_INTERVAL_MS=1200         # 同账号两次请求最小间隔（毫秒），被限流时启用
REQUEST_JITTER_MIN_MS=120            # 请求前随机抖动最小值（毫秒）
REQUEST_JITTER_MAX_MS=360            # 请求前随机抖动最大值（毫秒）
RATE_LIMIT_BASE_COOLDOWN=600         # 限流基础冷却时间（秒），频繁限流时增加到 1200
RATE_LIMIT_MAX_COOLDOWN=3600         # 限流最大冷却时间（秒）

# ========== 数据文件路径（Docker 部署通常不需要改）==========
ACCOUNTS_FILE=/workspace/data/accounts.json
USERS_FILE=/workspace/data/users.json
CONTEXT_CACHE_FILE=/workspace/data/context_cache.json
UPLOADED_FILES_FILE=/workspace/data/uploaded_files.json
```

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

### OpenAI Python SDK Example

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Demonstrates how to use the OpenAI Python SDK to interact with the Qwen2API endpoint.

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:7860/v1",
    api_key="YOUR_API_KEY",
)

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
    stream=False,
)
print(resp.choices[0].message.content)
```

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

### Schema Compression Example Input

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Example of a JSON Schema input for schema compression.

```json
{"type":"object","properties":{
         "file_path":{"type":"string"},
         "encoding":{"type":"string","enum":["utf-8","base64"]}},
       "required":["file_path"]}
```

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

### Image Generation Request Example

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Example of a cURL request to the image generation endpoint.

```bash
curl http://127.0.0.1:7860/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "dall-e-3",
    "prompt": "一只赛博朋克风格的猫，霓虹灯背景，超写实",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'
```

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

### Local Source Run

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Steps to clone the repository, navigate to the directory, and start the service from local source code.

```bash
git clone https://github.com/YuJunZhiXue/qwen2API.git
cd qwen2API
python start.py
```

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

### Image Generation Response Example

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Example JSON response from the image generation endpoint.

```json
{
  "created": 1712345678,
  "data": [
    {
      "url": "https://cdn.qwenlm.ai/output/.../image.png?key=...",
      "revised_prompt": "一只赛博朋克风格的猫，霓虹灯背景，超写实"
    }
  ]
}
```

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

### Environment file configuration

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Example of configuring environment file loading with a 'required: false' option.

```yaml
env_file:
  - path: .env
    required: false
```

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

### Anthropic Python SDK Example

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Shows how to use the Anthropic Python SDK with Qwen2API, compatible with Claude Code and Anthropic SDK.

```python
from anthropic import Anthropic

client = Anthropic(
    base_url="http://127.0.0.1:7860/anthropic",
    api_key="YOUR_API_KEY",
)

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.content[0].text)
```

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

### Switching Engine Mode

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Example of how to switch the ENGINE_MODE environment variable in the .env file and restart the service.

```env
ENGINE_MODE=httpx
```

```env
ENGINE_MODE=hybrid
```

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

### Direct curl calls

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Examples of calling the API using curl in OpenAI and Anthropic styles.

```bash
# OpenAI style
curl http://127.0.0.1:7860/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'
```

```bash
# Anthropic style
curl http://127.0.0.1:7860/anthropic/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

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

### Modifying Port Mapping

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Example of how to change the host port mapping in the docker-compose.yml file.

```yaml
ports:
  - "7860:7860"
```

```yaml
ports:
  - "8080:7860"
```

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

### Modifying Data Mount Directory

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Example of how to change the host directory for data persistence in the docker-compose.yml file.

```yaml
volumes:
  - ./data:/workspace/data
  - ./logs:/workspace/logs
```

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

### Google Gen AI Python SDK (Gemini)

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Example of using the Google Gen AI Python SDK to interact with the Gemini model via a local proxy.

```python
from google import genai

client = genai.Client(
    api_key="YOUR_API_KEY",
    http_options={"base_url": "http://127.0.0.1:7860"},
)

resp = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="你好",
)
print(resp.text)
```

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

### Modifying Shared Memory Size

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Example of how to increase the shared memory size in the docker-compose.yml file if the browser frequently crashes.

```yaml
shm_size: '256m'
```

```yaml
shm_size: '512m'
```

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

### Directory Preparation

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Commands to create necessary directories for Docker deployment.

```bash
mkdir qwen2api && cd qwen2api
mkdir -p data logs
```

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

### Run Unit Tests

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Command to run unit tests for the backend.

```bash
pytest backend/tests -v
```

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

### Local Buildx Push Multi-architecture Image

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Command to build and push a multi-architecture image using buildx, suitable for scenarios without CI.

```bash
# 1) Login to image repository (DockerHub/ACR/GHCR any)
docker login

# 2) Build and push multi-architecture image
./scripts/buildx-push.sh <your-repo-name>/qwen2api:<tag>
```

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

### Docker Compose Configuration

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

The docker-compose.yml file for setting up the Qwen2API service.

```yaml
services:
  qwen2api:
    image: yujunzhixue/qwen2api:latest
    container_name: qwen2api
    restart: unless-stopped
    env_file:
      - path: .env
        required: false
    ports:
      - "7860:7860"
    volumes:
      - ./data:/workspace/data
      - ./logs:/workspace/logs
    shm_size: '256m'
    environment:
      PYTHONIOENCODING: utf-8
      PORT: "7860"
      ENGINE_MODE: "hybrid"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7860/healthz"]
      interval: 30s
      timeout: 10s
      start_period: 120s
      retries: 3
```

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

### Claude Code CLI Configuration (Environment Variables)

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Configuration for Claude Code CLI using environment variables.

```bash
export ANTHROPIC_BASE_URL=http://127.0.0.1:7860/anthropic
export ANTHROPIC_API_KEY=YOUR_API_KEY
claude
```

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

### Restart Service

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Command to restart the service after modifying environment variables.

```bash
docker compose restart
```

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

### WebUI Management Console Default Entry

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

The default entry point for the WebUI management console, hosted by the backend.

```text
http://127.0.0.1:7860/
```

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

### Update Services

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Commands to pull the latest images and restart services.

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

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

### Mermaid Architecture Diagram

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

This diagram illustrates the architecture of the qwen2API, showing the flow of requests from clients through the FastAPI gateway to the upstream chat.qwen.ai service, and detailing the various components involved in protocol adaptation, runtime core capabilities, and client interaction.

```mermaid
flowchart LR
    Client["🖥️ 客户端 / SDK\n(OpenAI / Claude / Gemini)"]
    Upstream["☁️ chat.qwen.ai"]

    subgraph qwen2API["qwen2API（FastAPI 统一网关）"]
        Router["FastAPI Router + 中间件\n(CORS / Logging / Context)"]

        subgraph Adapters["协议适配层"]
            OA["OpenAI\n/v1/chat/completions"]
            CA["Claude\n/anthropic/v1/messages"]
            GA["Gemini\n/v1beta/models/*"]
            IA["Images\n/v1/images/generations"]
            FA["Files\n/v1/files"]
            Admin["Admin API\n/api/admin/*"]
            WebUI["WebUI\n/（静态托管）"]
        end

        subgraph Runtime["运行时核心能力"]
            Bridge["协议转换桥\n(多协议 <-> 统一格式)"]
            Executor["Qwen Executor\n(会话管理 + 流式处理)"]
            Auth["Auth Resolver\n(API key / Bearer)"]
            Pool["Account Pool\n(并发控制 + 限流冷却)"]
            QwenClient["Qwen Client\n(HTTP / 浏览器自动化)"]
            ToolParser["Tool Parser\n(工具调用解析)"]
            FileStore["File Store\n(本地文件暂存)"]
        end
    end

    Client --> Router
    Router --> OA & CA & GA & IA & FA
    Router --> Admin
    Router --> WebUI

    OA & CA & GA --> Bridge
    Bridge --> Executor
    Executor --> Auth
    Executor -.账号轮询.-> Pool
    Executor -.工具调用.-> ToolParser
    IA & FA --> FileStore
    Auth --> QwenClient
    QwenClient --> Upstream
    Upstream --> QwenClient
    Executor --> Bridge
    Bridge --> Client
```

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

### Claude Code CLI Configuration (JSON)

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Configuration for Claude Code CLI using a settings.json file.

```json
{
  "apiKey": "YOUR_API_KEY",
  "apiUrl": "http://127.0.0.1:7860/anthropic"
}
```

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

### Check Status

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Commands to check the status of the running services.

```bash
docker compose ps
docker compose logs -f
curl http://127.0.0.1:7860/healthz
```

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

### Add New Upstream Model Alias

Source: https://github.com/yujunzhixue/qwen2api/blob/main/README.md

Configuration for adding a new upstream model alias in MODEL_ALIAS_MAP.

```python
MODEL_ALIAS_MAP = {
    ...
    "my-custom-model": "qwen3.6-plus",
}
```
Tokens:
Raw