语言 / Language: 中文 | English

qwen2API 用于将通义千问（chat.qwen.ai）网页版能力转换为 OpenAI、Anthropic Claude 与 Gemini 兼容接口。项目后端基于 FastAPI，前端基于 React + Vite，内置管理台、账号池、工具调用解析、图片生成链路与多种部署方式。

• 项目说明
• 架构概览
• 核心能力
• 接口支持
• 模型映射
• 待审批账户机制
• 图片生成
• 快速开始
  • 方式一：Docker 直接运行预构建镜像（推荐）
  • 方式二：本地源码运行
• 环境变量说明（.env）
• docker-compose.yml 说明
• 端口说明
• WebUI 管理台
• 数据持久化
• 常见问题
• 许可证与免责声明

本项目提供以下能力：

1. 将千问网页对话能力转换为 OpenAI Chat Completions 接口。
2. 将千问网页对话能力转换为 Anthropic Messages 接口。
3. 将千问网页对话能力转换为 Gemini GenerateContent 接口。
4. 提供独立的图片生成接口 POST /v1/images/generations。
5. 支持工具调用（Tool Calling）与工具结果回传。
6. 提供管理台，用于账号管理、API Key 管理、图片生成测试与运行状态查看。
7. 提供多账号轮询、限流冷却、重试与按需浏览器自动化能力。

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

架构说明：

• 后端：Python FastAPI（backend/），统一处理多协议适配与上游调用
• 前端：React 管理台（frontend/），运行时托管静态构建产物
• 部署：Docker（推荐）、本地运行、Vercel、Zeabur

核心特性：

• 统一路由内核：所有协议入口统一汇聚到 FastAPI Router，避免多入口行为漂移
• 协议转换桥：Claude / Gemini 入口先转换为统一格式，再调用上游，最后转换回原协议响应
• 工具调用支持：支持 OpenAI / Claude / Gemini 三种工具调用格式，自动解析与转换
• 账号池管理：多账号轮询、并发控制、限流冷却、自动重试
• 文件附件：支持文件上传、本地暂存、上下文注入
• 图片生成：独立图片生成接口，支持多种尺寸比例

• OpenAI / Anthropic / Gemini 三套接口兼容。
• 工具调用解析与工具结果回传。
• 默认请求链路走直连 HTTP；注册、激活、刷新 Token 时按需启用浏览器自动化。
• 多账号并发池、动态冷却、故障重试。
• 基于千问网页真实工具链路的图片生成。
• WebUI 管理台。
• 健康检查与就绪检查接口。

当前默认将主流客户端模型名称统一映射至 qwen3.6-plus。

未命中映射表时，默认回退为传入模型名本身；若管理台设置了自定义映射规则，则以配置为准。

为了增强系统的安全性与可控性，qwen2API 引入了待审批账户机制。该机制允许非管理员用户通过公共 API 提交账户凭证，这些账户会被暂时存储在一个隔离的数据区域中，直到管理员审核并批准后才会正式加入账号池。

1. 账户提交：非管理员用户通过公共 API 端点 POST /api/public/pending-accounts 提交账户信息。
2. 数据隔离：提交的账户信息会存储在独立的 data/pending_accounts.json 文件中，与正式账号池完全隔离。
3. 管理员审核：管理员在管理台的“待审批账户”页面可以查看所有待审批的账户列表。
4. 账户验证：管理员可以选择批准或拒绝某个待审批账户：
   • 批准：系统会尝试使用该账户登录并验证其有效性，成功后将其添加到正式账号池。
   • 拒绝：直接从待审批列表中删除该账户记录。
5. 安全措施：
   • 公共 API 端点具有速率限制（每个 API Key 每小时最多 10 次提交）。
   • 系统会检查提交的邮箱是否已在正式账号池或待审批列表中存在，防止重复提交。

• 提交待审批账户：POST /api/public/pending-accounts
  • 请求头需包含有效的 API Key：Authorization: Bearer YOUR_API_KEY
  • 请求体需包含账户信息：{ "email": "user@example.com", "password": "password", "proxy": "proxy_url_or_null" }

📖 详细接口文档: docs/public_api.md

• 列出待审批账户：GET /api/admin/pending-accounts
• 批准账户：POST /api/admin/pending-accounts/{id}/approve
• 拒绝账户：POST /api/admin/pending-accounts/{id}/reject

qwen2API 提供与 OpenAI Images 接口兼容的图片生成能力。

• 接口：POST /v1/images/generations
• 默认模型别名：dall-e-3
• 实际底层：qwen3.6-plus + 千问网页 image_gen 工具
• 返回图片链接域名：通常为 cdn.qwenlm.ai

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"
  }'

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

前端图片生成页面内置以下比例：

• 1:1
• 16:9
• 9:16
• 4:3
• 3:4

/v1/chat/completions 支持根据用户消息自动识别图片生成意图。例如：

• “帮我画一张……”
• “生成一张图片……”
• “draw an image of ……”

当识别为图片生成请求时，系统会自动切换到图片生成管道。

此方式适用于生产环境、测试服务器与普通部署场景。
优点是：不需要本地编译前端，不需要在服务器构建镜像，不需要服务器自行下载 Camoufox。

mkdir qwen2api && cd qwen2api
mkdir -p data logs

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"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7860/healthz"]
      interval: 30s
      timeout: 10s
      start_period: 120s
      retries: 3

建议至少写入以下内容：

# ========== 必须修改 ==========
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

环境变量详细说明：

docker-compose.yml 配置说明：

docker compose up -d

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

docker compose pull
docker compose up -d

此方式适用于本地开发与调试。

• Python 3.12+
• Node.js 20+

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

python start.py 会自动完成以下工作：

1. 安装后端依赖
2. 启动前端开发服务器
3. 启动后端服务

项目提供 .env.example 作为模板。以下为主要参数说明。

• 默认请求链路统一走直连 HTTP。
• 浏览器自动化不再作为可切换的请求模式存在，仅在注册、激活、刷新 Token 等账号自愈场景按需启动。
• 首次触发这些场景时，如果本机尚未安装 Camoufox，系统会自动补装浏览器内核。

以下是推荐的 Compose 配置：

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"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7860/healthz"]
      interval: 30s
      timeout: 10s
      start_period: 120s
      retries: 3

通常只需要根据部署环境修改以下内容：

1. 端口映射

   ports:
     - "7860:7860"

   如果服务器 7860 已占用，可以改为：

   ports:
     - "8080:7860"

2. 共享内存

   shm_size: "256m"

   如果浏览器容易崩溃，可改为：

   shm_size: "512m"

3. 数据挂载目录

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

   如需自定义存储路径，可替换左侧宿主机目录。

Docker 镜像中已经构建好前端静态文件，并由后端统一托管：

• 后端 API：http://host:7860/*
• 前端管理台：http://host:7860/

因此 Docker 部署时默认只有一个端口 7860。

本地开发通常有两种方式：

1. 使用 python start.py
   前端会先构建为静态文件，再由后端统一托管。此时通常仍是一个端口。

2. 使用前端 Vite 开发服务器单独运行
   例如：

   • 前端：http://localhost:5173
   • 后端：http://localhost:7860

这种模式仅用于前端开发调试，不是生产部署模式。

管理台默认由后端托管，入口为：

http://127.0.0.1:7860/

主要页面包括：

默认数据目录：

• data/accounts.json：上游账号信息
• data/users.json：下游 API Key / 用户数据
• data/captures.json：抓取结果
• data/config.json：运行时配置
• logs/：运行日志

生产环境请务必持久化 data/ 与 logs/。

如果 Compose 版本支持：

env_file:
  - path: .env
    required: false

则 .env 不存在时仍可启动，使用镜像默认配置。
但正式部署建议始终创建 .env，至少设置 ADMIN_KEY。

请使用“Docker 直接运行预构建镜像”方式。
该方式不依赖服务器下载浏览器内核，也不需要服务器本地构建镜像。

排查步骤：

1. 确认上游账号在网页中可正常使用图片生成。
2. 查看日志中的 [T2I] 与 [T2I-SSE] 输出。
3. 确认部署的是最新镜像版本。
4. 确认前端页面未缓存旧资源。

本项目采用 MIT License 发布。你可以根据 MIT License 的条款使用、复制、修改、分发本项目源代码，但必须保留原始版权声明与许可证文本。

本项目用于协议兼容、接口转换、自动化测试与个人技术研究。项目本身不提供任何官方授权的通义千问商业接口服务。

1. 本项目与阿里云、通义千问及相关官方服务无任何从属、代理或商业合作关系。
2. 本项目不是官方产品，也不构成任何官方服务承诺。
3. 使用者应自行评估所在地区的法律法规、上游服务条款、账号合规性与数据安全要求。
4. 因使用本项目导致的账号封禁、请求受限、数据丢失、服务中断、法律纠纷或其他风险，由使用者自行承担责任。
5. 项目维护者不对任何直接或间接损失承担责任。
6. 不建议将本项目用于违反上游服务条款、违反法律法规或存在明显合规风险的场景。

如果权利人认为本项目内容侵犯其合法权益，请通过仓库 Issue 或其他公开联系方式提出，维护者将在核实后处理。