# z-image-turbo2api

**Repository Path**: ogurayui/z-image-turbo2api

## Basic Information

- **Project Name**: z-image-turbo2api
- **Description**: 将 ComfyUI 工作流（z-image-turbo）转换为 OpenAI 兼容 API 的桥接服务，内置 Web UI，支持文生图/图生图
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-02-17
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ComfyUI API Bridge v2.0

OpenAI 兼容的 ComfyUI API 桥接服务，支持 **文生图 (txt2img)** 和 **图生图 (img2img)**。

## 特性

- **OpenAI API 兼容**：支持所有 OpenAI 格式的客户端调用
- **文生图/图生图**：完整支持 txt2img 和 img2img 两种模式
- **Web UI**：内置美观的 Web 界面，支持拖拽上传
- **智能清理**：自动清理2小时前的旧图片，防止磁盘占满
- **超时保护**：任务超过10分钟自动取消，避免资源占用
- **断连取消**：客户端关闭/刷新网页时自动取消任务
- **本地存储**：生成的图片自动保存到浏览器本地数据库

## 文件结构

```
comfyui-api-bridge/
├── main.py                 # API 服务主程序
├── index.html             # Web UI 界面
├── start.bat              # Windows 启动脚本
├── requirements.txt       # Python 依赖
├── workflow_txt2img.json  # 文生图工作流
├── workflow_img2img.json  # 图生图工作流
└── README.md             # 本文档
```

## 快速开始

### 1. 先启动 ComfyUI

确保 ComfyUI 服务已启动（默认端口 8188）

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 启动 API 服务

```bash
# Windows: 双击 start.bat
# 或命令行运行:
python main.py
```

服务默认运行在 `http://127.0.0.1:9000`

### 4. 打开 Web UI

浏览器访问 `http://127.0.0.1:9000` 或双击打开 `index.html`

## 环境变量配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `COMFYUI_HOST` | 127.0.0.1 | ComfyUI 主机地址 |
| `COMFYUI_PORT` | 8188 | ComfyUI 端口 |
| `API_PORT` | 9000 | API 服务端口 |
| `API_KEY` | sk-comfyui-z-image-turbo | API 密钥 |
| `WORKFLOW_TXT2IMG` | workflow_txt2img.json | 文生图工作流文件 |
| `WORKFLOW_IMG2IMG` | workflow_img2img.json | 图生图工作流文件 |

示例：
```bash
set API_PORT=8080
set API_KEY=your-secret-key
python main.py
```

## API 接口

### 文生图 (txt2img)

```bash
POST /v1/images/generations
Authorization: Bearer sk-comfyui-z-image-turbo
Content-Type: application/json

{
    "model": "z-image-turbo",
    "prompt": "一只可爱的橘猫坐在窗台上，晨光，写实风格",
    "size": "1024x1024",
    "n": 1
}
```

### 图生图 (img2img)

```bash
POST /v1/images/edits
Authorization: Bearer sk-comfyui-z-image-turbo
Content-Type: application/json

{
    "model": "z-image-turbo",
    "prompt": "转换成动漫风格",
    "image": "<base64 编码的图片>",
    "strength": 0.6,
    "size": "1024x1024",
    "n": 1
}
```

**strength 参数说明：**
- 0.0 = 保持原图（无变化）
- 0.5 = 适度变化
- 1.0 = 完全变化（类似文生图）

### 表单上传（图生图）

```bash
POST /v1/images/img2img
Authorization: Bearer sk-comfyui-z-image-turbo
Content-Type: multipart/form-data

prompt: 转换风格
image: <图片文件>
strength: 0.6
size: 1024x1024
n: 1
```

### 取消任务

```bash
POST /cancel
Authorization: Bearer sk-comfyui-z-image-turbo
```

### 查看任务状态

```bash
GET /task/status
Authorization: Bearer sk-comfyui-z-image-turbo
```

返回示例：
```json
{
    "status": "running",
    "prompt_id": "uuid-string",
    "running_time": 120,
    "max_duration": 600,
    "will_timeout_in": 480
}
```

### 手动清理旧图片

```bash
POST /cleanup
Authorization: Bearer sk-comfyui-z-image-turbo
```

### 健康检查

```bash
GET /health
```

### 重新加载工作流

```bash
POST /reload
Authorization: Bearer sk-comfyui-z-image-turbo
```

## 参数说明

### 文生图 (txt2img)

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| prompt | string | 必填 | 提示词 |
| size | string | 1024x1024 | 图片尺寸，格式：宽x高 |
| n | int | 1 | 生成数量 (1-4) |

### 图生图 (img2img)

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| prompt | string | 必填 | 提示词 |
| image | string | 必填 | Base64 编码的图片 |
| strength | float | 0.6 | 变化强度 (0-1) |
| size | string | 1024x1024 | 输出尺寸 |
| n | int | 1 | 生成数量 (1-4) |

## 支持的尺寸

| 比例 | 可选尺寸 |
|------|----------|
| 1:1 | 512x512, 768x768, 1024x1024, 1280x1280, 1536x1536 |
| 4:3 | 640x480, 800x600, 1024x768, 1280x960, 1600x1200 |
| 3:4 | 480x640, 600x800, 768x1024, 960x1280, 1200x1600 |
| 16:9 | 640x360, 960x540, 1280x720, 1600x900, 1920x1080 |
| 9:16 | 360x640, 540x960, 720x1280, 900x1600, 1080x1920 |
| 自定义 | 任意 256-4096 范围内的尺寸 |

## 第三方客户端配置

### NewAPI / OneAPI

| 设置项 | 值 |
|--------|-----|
| 类型 | 自定义 / OpenAI |
| 名称 | Z-Image-Turbo |
| 基础 URL | http://127.0.0.1:9000 |
| API 密钥 | sk-comfyui-z-image-turbo |
| 模型 | z-image-turbo |

### ChatGPT-Next-Web / LobeChat

- **接口地址**：`http://127.0.0.1:9000`
- **API Key**：`sk-comfyui-z-image-turbo`
- **自定义模型**：`z-image-turbo`

## Web UI 功能

- **双模式切换**：文生图 / 图生图
- **拖拽上传**：支持拖拽图片到上传区域
- **强度调节**：图生图时可调节变化强度
- **多种比例**：支持 1:1、4:3、16:9 等常见比例
- **画廊管理**：查看、下载、删除、复制提示词
- **图片预览**：点击画廊图片可全屏预览
- **本地存储**：图片自动保存到浏览器 IndexedDB
- **进度显示**：实时显示生成进度和耗时

## 自动清理机制

服务内置自动清理功能：

1. **定时清理**：每10分钟检查一次
2. **旧文件清理**：删除生成时间超过2小时的图片
3. **任务超时**：运行超过10分钟的任务自动取消
4. **断连清理**：客户端断开连接时自动取消任务

清理目录：
- `~/ComfyUI/output`
- `./ComfyUI/output`
- `./output`

## 故障排除

### "txt2img/img2img workflow not configured"
- 检查 workflow_txt2img.json 和 workflow_img2img.json 是否存在
- 检查 JSON 格式是否正确

### "ComfyUI error" / "ComfyUI unreachable"
- 确认 ComfyUI 已启动
- 检查 COMFYUI_HOST 和 COMFYUI_PORT 配置
- 检查防火墙设置

### 生成超时
- 正常生成需要 10-30 秒
- 尝试减小尺寸（如 512x512）
- 检查 ComfyUI 控制台是否有错误

### 图生图不工作
- 确保工作流包含 LoadImage 节点
- 检查图片是否上传成功
- 确认图片格式支持（PNG、JPG）

### 端口被占用
```bash
# 更换端口
set API_PORT=9001
python main.py
```

## 开发计划

- [x] 基础 txt2img/img2img 功能
- [x] Web UI 界面
- [x] 自动清理机制
- [x] 超时保护
- [x] 断连取消
- [ ] 队列管理
- [ ] 并发控制
- [ ] 模型热切换

## 许可证

MIT License

## 致谢

- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) - 强大的 Stable Diffusion 后端
- [FastAPI](https://fastapi.tiangolo.com/) - 高性能 Web 框架