# visualgpt-2api

**Repository Path**: Chinese-tingfeng/visualgpt-2api

## Basic Information

- **Project Name**: visualgpt-2api
- **Description**: FastAPI 异步架构、需自备 Cookie、集成 Cloudscraper 强力绕过 Cloudflare 人机验证、原生 OpenAI 格式 API 转换、Docker 一键部署
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-10
- **Last Updated**: 2025-12-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 视觉奇点：VisualGPT-2API (v2.0) 🚀

![协议状态](https://img.shields.io/badge/Genesis%20Protocol-%CE%A9%20(Omega)%20Edition-blueviolet)
![架构范式](https://img.shields.io/badge/Architecture-lzA6%20Paradigm-critical)
![许可证](https://img.shields.io/badge/License-Apache%202.0-blue)
![技术栈](https://img.shields.io/badge/Tech-FastAPI%20%7C%20Docker%20%7C%20Cloudscraper-brightgreen)

> "我们并非仅仅在编写代码，我们是在为冰冷的机器注入视觉的灵魂，是在为每一个普通人开启一扇通往创意宇宙的传送门。"

欢迎来到 `visualgpt-2api` 的世界！这是一个充满激情与巧思的项目，它的核心使命只有一个：**将 VisualGPT 网站背后那强大而有趣的 AI 图像处理能力，从其精美的网页中"解放"出来，封装成一个稳定、开放、且与全世界主流创作工具无缝对接的标准化 API。**

我们相信，强大的工具不应被束缚在单一的界面中。通过这个项目，无论您是 ComfyUI 的节点大师，还是热爱自动化的脚本小子，都能将 VisualGPT 的魔法融入到您的创作流程中。

---

本期网站：https://visualgpt.io/

## ✨ 项目亮点

-   🎨 **多模型统一接口**: 将 `Nano Banana` (快速编辑), `Seedream 4.0` (4K高清), `Background Remover` (自动抠图) 等多个模型，统一在标准的 OpenAI `/v1/images/edits` 接口下
-   💻 **内置"驾驶舱" (Web UI)**: 自带功能完善、风格现代的 Web UI 测试面板，无需任何配置就能直观测试所有参数
-   🧩 **无缝生态融入**: 提供针对 **ComfyUI** 和 **Stable Diffusion WebUI** 的"保姆级"集成教程
-   🛡️ **智能网络穿透**: 内置 `cloudscraper` 模块，自动处理 Cloudflare 的 JavaScript 挑战和验证
-   📦 **一键"创世纪" (Docker 部署)**: 极致简化的 Docker Compose 配置，真正实现"一条命令，启动所有"
-   🔑 **企业级安全**: 内置 `API_MASTER_KEY` 认证，保护您的服务不被未授权访问

---

## 🗺️ 项目蓝图与当前状态

### **第一阶段：核心功能实现 (已完成 ✔️)**

-   [x] **逆向工程**: 成功分析 VisualGPT.io 的核心 API 调用流程
-   [x] **STS 认证攻克**: 实现自动获取阿里云 OSS 临时上传凭证并完成图片上传
-   [x] **核心模型封装**: 完成对 `Nano Banana`, `Seedream 4.0`, `Background Remover` 的 API 封装
-   [x] **OpenAI 格式兼容**: 提供 `/v1/models` 和 `/v1/images/edits` 标准接口
-   [x] **Docker 化部署**: 提供 `Dockerfile` 和 `docker-compose.yml` 实现一键启动

### **第二阶段：用户体验优化 (已完成 ✔️)**

-   [x] **Web UI 测试面板**: 构建功能完整的内置前端界面，用于快速测试和参数调整
-   [x] **UI 参数对齐**: Web UI 支持分辨率、长宽比、生成数量等所有高级参数
-   [x] **详尽文档**: 撰写这份您正在阅读的、力求详尽的说明文档

### **第三阶段：社区与生态扩展 (进行中... 🚀)**

-   [ ] **流式传输支持**: 对于长耗时任务，探索通过 WebSocket 或 SSE 实现更友好的进度反馈
-   [ ] **凭证自动续期**: 研究 `Cookie` 生命周期，探索使用自动化工具实现无人值守
-   [ ] **模型自动发现**: 增加自动探测新模型的机制，动态更新模型列表
-   [ ] **更广泛的工具集成**: 提供更多第三方工具的集成教程或专用脚本

---

## 🏗️ 系统架构

```mermaid
graph TB
    A[用户请求] --> B[FastAPI 服务器]
    B --> C{认证验证}
    C -->|通过| D[路由分发]
    C -->|失败| E[返回 401 错误]
    
    D --> F[VisualGPT 提供商]
    F --> G[Cloudscraper 模块]
    G --> H[VisualGPT 官方 API]
    
    F --> I[OSS 上传器]
    I --> J[阿里云 OSS]
    
    H --> K[处理结果]
    J --> K
    K --> L[返回用户]
    
    M[Web UI] --> B
    N[ComfyUI] --> B
    O[SD WebUI] --> B
    
    style A fill:#e1f5fe
    style M fill:#f3e5f5
    style N fill:#e8f5e8
    style O fill:#fff3e0
```

## 🛠️ 技术栈深度解析

| 技术/组件 | 难度评级 | 重要性 | 核心作用 | 技术原理深度解析 |
| :--- | :--- | :--- | :--- | :--- |
| **FastAPI** | ★★★☆☆ | ★★★★★ | **API 服务核心框架** | 基于 Starlette 和 Pydantic，提供异步高性能支持。自动生成 OpenAPI 文档，让接口调试和集成变得异常简单 |
| **Cloudscraper** | ★★★★☆ | ★★★★★ | **反爬虫绕过专家** | 内置 JavaScript 解释器，模拟真实浏览器行为，破解 Cloudflare 的 IUAM 挑战，获取有效会话凭证 |
| **OSS2** | ★★★☆☆ | ★★★★★ | **云存储安全桥梁** | 实现 STS 安全令牌模式，使用临时凭证与阿里云 OSS 安全交互，避免直接暴露长期密钥 |
| **Docker** | ★★★☆☆ | ★★★★☆ | **环境一致性保障** | 容器化封装确保开发、测试、生产环境完全一致，彻底解决依赖冲突问题 |
| **Nginx** | ★★★☆☆ | ★★★★☆ | **高性能流量网关** | 反向代理 + 负载均衡，处理静态文件服务，为高并发场景提供稳定基础 |

---

## 🚀 快速开始

### **环境要求**

-   Docker & Docker Compose
-   至少 2GB 可用内存
-   稳定的网络连接

### **三步部署指南**

**第 1 步：获取项目**
```bash
git clone https://github.com/lzA6/visualgpt-2api.git
cd visualgpt-2api
```

**第 2 步：配置认证凭证**

1.  访问 [VisualGPT](https://visualgpt.io/) 并登录
2.  按 F12 打开开发者工具，进入 Network 面板
3.  执行任意图像操作，找到 API 请求
4.  复制完整的 Cookie 值
5.  配置环境变量：
```bash
cp .env.example .env
# 编辑 .env 文件，填入您的 Cookie
VISUALGPT_COOKIE="your_cookie_here"
API_MASTER_KEY="your_secret_key"
```

**第 3 步：启动服务**
```bash
docker-compose up -d --build
```

访问 `http://localhost:8088` 即可开始使用！

---

## 🎯 使用指南

### **Web UI 测试面板**

我们的内置界面让测试变得简单直观：

1.  **上传图像**: 拖拽或点击上传区域
2.  **选择模型**: 
    - `nano-banana`: 快速创意生成
    - `seedream-4.0`: 4K 高清输出  
    - `background-remover`: 智能背景移除
3.  **调整参数**: 分辨率、长宽比、生成数量等
4.  **输入提示词**: 使用预设或自定义创意描述
5.  **一键生成**: 实时查看处理结果

### **API 直接调用**

**标准 OpenAI 格式端点:**
```bash
curl -X POST "http://localhost:8088/v1/images/edits" \
  -H "Authorization: Bearer your_api_key" \
  -F "image=@input.png" \
  -F "prompt=cyberpunk style" \
  -F "model=seedream-4.0" \
  -F "n=2" \
  -F "size=4K"
```

**请求参数说明:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `image` | file | ✅ | 输入图像文件 |
| `prompt` | string | ✅ | 处理提示词 |
| `model` | string | ✅ | 模型标识符 |
| `n` | integer | ❌ | 生成数量 (1-4) |
| `size` | string | ❌ | 输出分辨率 |
| `aspect_ratio` | string | ❌ | 宽高比 |

---

## 🔌 生态集成

### **ComfyUI 集成**

1. 安装 `ComfyUI-OpenAI-Nodes` 扩展
2. 添加 `OpenAIImageEdit` 节点
3. 配置参数：
   ```json
   {
     "base_url": "http://localhost:8088/v1",
     "api_key": "your_master_key", 
     "model": "seedream-4.0"
   }
   ```
4. 连接工作流并运行

### **Stable Diffusion WebUI 集成**

1. 安装 `OpenAI-Integration` 扩展
2. 在设置中配置 API 端点：
   ```
   API Base: http://localhost:8088/v1
   API Key: your_master_key
   ```
3. 在 img2img 标签页中使用 VisualGPT 模型

### **Python 客户端示例**

```python
import requests

def visualgpt_edit(image_path, prompt, model="nano-banana"):
    url = "http://localhost:8088/v1/images/edits"
    
    with open(image_path, 'rb') as image_file:
        files = {'image': image_file}
        data = {
            'prompt': prompt,
            'model': model,
            'n': 2
        }
        headers = {'Authorization': 'Bearer your_api_key'}
        
        response = requests.post(url, files=files, data=data, headers=headers)
        return response.json()

# 使用示例
result = visualgpt_edit('input.jpg', 'make it anime style')
print(result)
```

---

## 📊 性能与监控

### **服务健康检查**
```bash
# 检查服务状态
curl http://localhost:8088/health

# 查看可用模型
curl http://localhost:8088/v1/models
```

### **日志查看**
```bash
# 查看实时日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs app
```

---

## 🔧 故障排除

### **常见问题解决方案**

**问题 1: Cookie 过期**
```
错误: STS token 获取失败
解决方案: 重新获取并更新 .env 中的 Cookie
```

**问题 2: 内存不足**
```
错误: Container 异常退出
解决方案: 增加 Docker 内存分配至 2GB+
```

**问题 3: 端口冲突**
```
错误: 端口 8088 已被占用
解决方案: 修改 docker-compose.yml 中的端口映射
```

**问题 4: 网络超时**
```
错误: Cloudflare 挑战失败
解决方案: 检查网络连接，重启服务重试
```

### **调试模式**
在 `.env` 中设置 `DEBUG=true` 可开启详细日志输出：
```bash
DEBUG=true
LOG_LEVEL=DEBUG
```

---

## 🎨 创意工作流示例

### **概念艺术生成流程**
```
原始照片 → [Background Remover] → 干净主体 → [Seedream 4.0] → 高质量概念艺术
```

### **产品展示优化流程**  
```
产品照片 → [Nano Banana] → 多种风格变体 → 选择最佳 → [Seedream 4.0] → 4K 成品
```

### **批量处理脚本**
```python
import os
from concurrent.futures import ThreadPoolExecutor

def process_batch(input_dir, output_dir, prompt):
    with ThreadPoolExecutor(max_workers=3) as executor:
        for filename in os.listdir(input_dir):
            if filename.endswith(('.jpg', '.png')):
                input_path = os.path.join(input_dir, filename)
                executor.submit(process_single, input_path, output_dir, prompt)
```

---

## 🤝 贡献指南

我们欢迎各种形式的贡献！无论是代码改进、文档完善，还是创意想法，都是宝贵的贡献。

### **开发环境搭建**
```bash
# 克隆项目
git clone https://github.com/lzA6/visualgpt-2api.git

# 安装依赖
pip install -r requirements.txt

# 启动开发服务器
uvicorn main:app --reload --host 0.0.0.0 --port 8088
```

### **提交规范**
- `feat`: 新功能
- `fix`: 问题修复  
- `docs`: 文档更新
- `test`: 测试相关
- `refactor`: 代码重构

---

## 📄 许可证

本项目基于 Apache 2.0 许可证开源 - 详见 [LICENSE](LICENSE) 文件。

---

## 🌟 致谢

感谢所有为这个项目做出贡献的开发者，特别感谢：

- **VisualGPT 团队** - 提供了强大的底层 AI 能力
- **FastAPI 社区** - 优秀的 Web 框架生态
- **所有测试用户** - 宝贵的反馈和建议

---

## 🔮 愿景

> "我们相信，创意的工具应该像空气一样无处不在，像水一样自由流动。这个项目只是开始，真正的奇迹将在每个人的创意中绽放。"

---

**开始您的视觉创意之旅吧！** 🎉

如果有任何问题，请查阅 [Issues](https://github.com/lzA6/visualgpt-2api/issues) 或提交新的问题报告。

*让创意，不再有边界。*

这个优化版本主要改进：

1. **结构重组** - 更清晰的层次和逻辑流
2. **技术深度** - 详细的技术原理和架构说明
3. **实用导向** - 丰富的代码示例和集成指南
4. **问题解决** - 完整的故障排除章节
5. **视觉增强** - 使用 Mermaid 图表展示架构
6. **格式统一** - 一致的标记和排版风格
7. **实用性** - 增加了具体的工作流示例和脚本
8. **完整性** - 补充了贡献指南和致谢部分

文档现在更加专业、实用且易于理解。