# ComfyUI 出图服务 · 使用说明

单卡（AMD RX 7900 XTX）跑 **Qwen-Image-2.1 GGUF** 文生图 / 图生图。流程：
**登录一次 → 提交工作流 → 轮询 → 取图**；作业号与 ComfyUI 的 prompt_id 相同。
图生图多一步：先把参考图上传换 `file_id`，提交时引用（见 §3）。

- 服务地址：`https://comfyui-api.weisanju.fun`
- 探活（免鉴权）：`GET /health` → `{"status":"ok","comfyui":true}`
- 端点清单：浏览器打开 `/docs`

单张耗时参考：1024²@12步 ≈ 21s，1024²@24步 ≈ 41s，2048²@24步 ≈ 152s；执行并发 1，排队按序。

## 1. 装 CLI 并登录（推荐路径）

```bash
npm install -g comfyui-cli     # npmjs 已发布，零依赖，需要 Node ≥ 22.5

comfyui login --url https://comfyui-api.weisanju.fun --label 我的笔记本
```

CLI 源码与完整用法（开发 / 测试 / 发布）：[github.com/weisanju/comfyui-cli](https://github.com/weisanju/comfyui-cli)。

登录是**两段审批**，任何人都能发起：

1. **注册审批**：新机器要先让持有 access code 的人批准一次（access code 就是服务方给的
   共享 token）。CLI 会打印注册审批页链接，把设备码和链接交给服务方即可；
   批完浏览器自动跳到设备授权页（机器已在册时打开注册页也会直接跳过去）
2. **设备授权**：发起登录的人自己在页面上确认（不再要 access code）

批过的机器按指纹记住，之后登录只剩第二段。换来的专属 token 落在
`~/.config/comfyui/auth.json`（0600），之后所有命令自动带上，形如 `comfyui_xxxx`，
默认 90 天有效，`comfyui logout` 可随时吊销；机器指纹在 `~/.config/comfyui/machine.json`。
已经有共享 token 的话也可以一步到位：`comfyui login --token <共享 token>`。

## 2. 出图

```bash
# 内置模板 + 常用参数
comfyui generate -t qwen-image-2.1-t2i-gguf-api --prompt "雪山下的木屋，清晨薄雾" --steps 12

# 图生图：参考图 + prompt（--resolution 0 = 出图保持参考图尺寸，详见 §3）
comfyui generate -t qwen-image-2.1-ref-gguf-api --image ./cat.png --resolution 0 \
  --prompt "把参考图变成水彩插画，保留构图" --steps 24

# 自带工作流（ComfyUI 前端「导出（API格式）」的 JSON）
comfyui generate -w my-workflow.json --size 1024x1024 --steps 24 --seed 42 --out ./out/
```

图片默认存 `./comfyui-out/`。`--prompt`/`--negative`/`--steps`/`--cfg`/`--size`/`--seed`/`--resolution`
会按 `class_type` 自动定位 KSampler / TextEncode / EmptyLatentImage 节点，
并按节点自己的输入名写入（`CLIPTextEncode` 用 `text`，Qwen 系用 `prompt`/`negative_prompt`），
内置模板与自带工作流通用；定位不到时按提示用 `--set 4.prompt=…`（「节点id.输入名=值」）精确指定。

| 选项 | 说明 |
|---|---|
| `-t, --template <名称>` / `-w, --workflow <文件>` | 二选一：内置模板 / API 格式工作流 JSON |
| `--prompt` `--negative` | 正面 / 负面提示词 |
| `--steps N` `--cfg N` `--seed N` | 采样步数 / CFG / 随机种子（`random` 或负数 = 随机） |
| `--size 宽x高` | 如 `1024x1024`；16~8192，取 32 的倍数 |
| `--image <文件>` | 参考图（图生图），1 张 PNG/JPEG/WebP、≤10MB / 40MP；与 `--size` 互斥 |
| `--resolution N` | 配 `--image` 用：参考图缩放到约 NxN 像素（保持比例、取 32 倍数），出图即此尺寸；`0` = 保持参考图自身尺寸（默认 1024） |
| `--set 节点id.输入=值` | 兜底覆盖任意节点输入，可重复 |
| `--out <目录\|文件>` `--no-wait` `--json` | 保存位置 / 提交即返回 / 机器可读输出 |

退出码：0 成功 / 1 运行错误 / 2 用法错误 / 3 作业 failed。

## 3. 参考图（图生图）

给一张参考图，让模型按 prompt 改造它（换风格 / 换背景 / 保留构图重画）：

```bash
comfyui generate -t qwen-image-2.1-ref-gguf-api --image ./cat.png --resolution 0 \
  --prompt "把参考图变成水彩插画，保留构图" --steps 24
```

- `--image <文件>`：PNG / JPEG / WebP，≤ 10 MB、≤ 40 MP，v1 只收 **1 张**。CLI 先在本地
  读文件、按魔数认格式，再上传换 `file_id`，提交作业时用 `inputs` 引用它
- `--resolution N`：配 `--image` 用，控制参考图缩放到的尺寸——**保持长宽比**缩到约 NxN
  像素、两边取 32 的倍数，出图就是缩放后的尺寸；`0` = 参考图不缩放、出图等于原图尺寸
  （取 32 的倍数）。范围 0~4096，默认 1024。`--size` 与 `--image` 互斥：
  要指定尺寸改用 `--resolution`
- 其余参数（`--prompt`/`--steps`/`--seed`…）照常；prompt 里可以写 `<image1>` 指代参考图
  （如 `让 <image1> 里的人站在雪山上`）
- 非 `--json` 时 stderr 打印 `参考图 → <file_id>（WxH，X MB）`；`--json` 输出多一段
  `reference: {file_id, width, height, bytes}`

上传的参考图存在服务端 ComfyUI 的 input 目录，**默认 24 小时**后由服务内的清扫任务删掉
（自己手动放进去的文件不受影响）。`file_id` 绑签发它的那枚 token：换 token / 换机器后要么
还用原来那枚引用，要么用新 token 重新上传（别的 token 引用 → 403）。

上传是**裸字节**（`Content-Type` 走头，格式认字节里的魔数，不信头），落在服务端后文件名由
服务生成，客户端不参与。`file_id` 只能提交作业时引用，不能下载、没有删除接口。

## 4. 其它命令

| 命令 | 说明 |
|---|---|
| `comfyui jobs [ID] [--limit N]` | 最近作业；给 ID 看详情；`--cancel` 取消 |
| `comfyui stats` | 队列深度 / 当前作业 / 近期平均耗时 |
| `comfyui templates` | 列出服务端内置模板名 |
| `comfyui share <job_id> [--ttl 1h]` | 给出图的作业签发限时分享链接（免鉴权下载，过期即失效）|
| `comfyui whoami` / `config` / `logout [--all]` | 当前凭据 / 本地配置 / 吊销退出 |
| `comfyui skill [-o 文件]` | 取服务端本文件（丢给 AI 代理用） |
| `comfyui update [--check] [--registry URL]` | 把 CLI 更新到 npm 最新版；`--check` 只看版本，`--registry` 换镜像源 |

通用选项 `--url` / `--token` 可覆盖；环境变量
`COMFYUI_CLI_URL`、`COMFYUI_CLI_TOKEN`（共享或设备 token 都行）、`COMFYUI_CLI_CONFIG_DIR`、
`COMFYUI_CLI_REGISTRY`（`update` 换源）。

## 5. 出图参数怎么选

### 步数不是越多越好

同种子 1024² 人像实测（拉普拉斯方差，越高越锐）：

| 步数 | 耗时 | 整图锐度 | 脸部锐度 |
|---|---|---|---|
| 12 | 22.7s | 95 | 124 |
| 24 | 39.1s | 111 | 144 |
| 40 | 61.7s | 113 | 152 |

- 12 → 24：整图 +17%、脸部 +16%，多花 72% 时间——**这一步最值**
- 24 → 40：只再涨 2% / 6%，却多花 58%；肉眼只剩皮肤纹理、衣料织纹更实一点

| 题材 | 建议步数 | 理由 |
|---|---|---|
| 风景、构图、背景图 | 12 | 低频内容 12 步就收敛 |
| **人像 / 人脸特写** | **24** | 12 步五官明显发糊；24 步是性价比拐点 |
| 最终出片、要放大看织纹发丝 | 40 | 只在成片环节用，试错阶段别用 |

### 想更"真实"时的调参顺序

1. **先清 prompt 里的柔化词**：`柔焦`、`浅景深`、`胶片颗粒`、`老照片质感` 是在明确
   要求模型虚化，效果比加步数大得多。只想要复古色调，写 `暖色调`、`低饱和` 就够
2. **再加分辨率**：2K 缩回 1K 看，比原生 1K 还锐约 20%，且五官/织纹/发丝更实
3. **最后才加步数**：过了 24 步收益就很小了

### 其它

- cfg 固定 1.0，代数上会消掉负向分支，所以 `--negative` **不起作用**
- 原生支持 2K，`--size` 取 32 的倍数；尺寸翻倍约 3.8 倍耗时（1024²@24步 40s → 2048²@24步 152s，不 OOM）
- 透明背景：prompt 用 `This is an RGBA format image with transparency. [主体描述]. The image has an alpha channel and a transparent background.`，存 PNG

## 6. 内置模板节点 id

`--set` 与 HTTP `overrides` 都按这些 id 定位。

### `qwen-image-2.1-t2i-gguf-api`（文生图）

| id | 节点 | 可覆盖的参数 |
|---|---|---|
| 4 | TextEncodeQwenImage21 | `prompt`、`negative_prompt`、`resolution` |
| 5 | EmptyLatentImage | `width`、`height`、`batch_size` |
| 6 | KSampler | `seed`、`steps`、`cfg`、`sampler_name`、`scheduler`、`denoise` |
| 8 | SaveImage | `filename_prefix` |
| 1 / 2 / 3 | UnetLoaderGGUF / CLIPLoader / VAELoader | 加载模型，一般不用改 |

### `qwen-image-2.1-ref-gguf-api`（图生图）

| id | 节点 | 可覆盖的参数 |
|---|---|---|
| 4 | LoadImage | `image` —— 服务端按 `inputs` 写入的上传文件名，别手改 |
| 5 | TextEncodeQwenImage21 | `prompt`、`negative_prompt`、`resolution` |
| 6 | KSampler | 同 t2i；`latent_image` 接 `["5",2]`、`denoise` 1.0 |
| 8 | SaveImage | `filename_prefix` |
| 1 / 2 / 3 | UnetLoaderGGUF / CLIPLoader / VAELoader | 加载模型，一般不用改 |

ref 模板没有 EmptyLatentImage：潜空间由 TextEncodeQwenImage21 的第 3 个输出按参考图尺寸
直接给出。`images.image_1` 这个输入名带小数点，`--set` 的「节点id.输入名」语法写不了它——
引用参考图只用提交作业时的 `inputs`（CLI 的 `--image` 就是干这个的，见 §3）。

## 7. HTTP API（不方便装 CLI 时）

鉴权：业务请求带 `Authorization: Bearer <TOKEN>`。token 两种拿法——直接用服务方给的
**共享 token**；或装 CLI 跑 `comfyui login` 换一枚专属的。手写设备码流程（两段审批，
全程除注册审批的 access code 外不需要共享 token）：

```
POST /oauth/device/code                     # 免鉴权，同 IP 限流 10s 一次
  → {device_code, user_code, registration_required, verification_uri_complete, ...}
POST /oauth/register  (user_code + token=access code)   # 新机器先过注册审批 → 303 跳授权页
POST /oauth/device/approve  (user_code)                 # 本人在授权页确认
POST /oauth/token  (grant_type=urn:ietf:params:oauth:grant-type:device_code, device_code)
  → 未完成审批时依次回 registration_pending / authorization_pending / slow_down
```

只有 `/health`、`/docs`、`/SKILL.md`、`/oauth/device*`、`POST /oauth/register`、
`POST /oauth/device/code`、`POST /oauth/token` 与 `/public/jobs/…`（分享链接）免 Bearer，其余都要。

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/v1/uploads` | 传参考图（裸字节，`Content-Type` 走头，`?name=` 仅标注）→ 201 |
| POST | `/v1/jobs` | 提交作业（对象或数组，数组 ≤ 50 即批量）→ 202 |
| GET | `/v1/jobs/{job_id}` | 状态 / 队列位置 / 图片清单 / 错误 / 耗时 |
| GET | `/v1/jobs/{job_id}/images/{index}` | 下载图片字节（`image/png`） |
| DELETE | `/v1/jobs/{job_id}` | 取消作业（幂等） |
| POST | `/v1/jobs/{job_id}/share` | 签发限时分享链接（body `{"ttl": 秒}`，默认 1 小时）|
| GET | `/public/jobs/{job_id}/images/{index}?exp=&sig=` | 按分享链接取图，**免鉴权**；过期 / 被改 → 403 |
| GET | `/v1/jobs?status=&limit=` | 最近作业列表 |
| GET | `/v1/workflows`、`/v1/workflows/{name}` | 模板名列表 / 取模板 JSON |
| GET | `/v1/stats` | 负载概览 |
| GET | `/v1/auth/whoami` | 当前凭据：`kind`(shared/token)、label、机器指纹、有效期 |
| GET/DELETE | `/v1/tokens[/{id}]` | 列出 / 吊销 token（仅共享 token） |
| GET | `/v1/clients` | 已登记机器列表（仅共享 token） |
| POST/DELETE | `/v1/clients/{id}/{approve\|deny}`、`/v1/clients/{id}` | 批准 / 拉黑 / 忘记机器（仅共享 token） |

提交（`workflow` 与 `workflow_name` 二选一，`overrides` 按节点合并进 `inputs`；
输入名必须写在节点上，写错会 400 并告诉你有哪些可用——写错的键 ComfyUI 会静默忽略）：

```bash
BASE=https://comfyui-api.weisanju.fun
TOKEN=<你的 token>

curl -s $BASE/v1/jobs -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{
  "workflow_name": "qwen-image-2.1-t2i-gguf-api",
  "overrides": {"4": {"prompt": "一只在雪山上的狐狸，电影感光线"},
                "5": {"width": 1024, "height": 1024},
                "6": {"seed": 12345, "steps": 24}}}'
# → 202 {"job_id":"0f0b…","status":"queued","queue_position":1,"poll_url":"…","images_url":"…"}

curl -s $BASE/v1/jobs/$JOB -H "Authorization: Bearer $TOKEN"    # 每 2s 轮询一次
# → {"status":"running","queue_position":null,"elapsed_s":12.3,"error":null,"images":[]}
# completed 时 images[] 给出 index 与可直接下载的 url；failed 时 error 是 ComfyUI 原样报错
curl -s $BASE/v1/jobs/$JOB/images/0 -H "Authorization: Bearer $TOKEN" -o out.png
```

图生图（先传参考图换 `file_id`，再用 `inputs` 引用；`resolution` 0 = 出图保持参考图尺寸）：

```bash
curl -s -X POST "$BASE/v1/uploads?name=cat.png" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: image/png' --data-binary @cat.png
# → 201 {"file_id":"fbf8b5f8-…","name":"cat.png","width":768,"height":512,"bytes":725434,"format":"png",…}

curl -s $BASE/v1/jobs -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{
  "workflow_name": "qwen-image-2.1-ref-gguf-api",
  "inputs": {"image_1": "fbf8b5f8-…"},
  "overrides": {"5": {"prompt": "把参考图变成水彩插画，保留构图", "resolution": 0},
                "6": {"seed": 12345, "steps": 24}}}'
```

想把图发给别人（对方没 token 也能看）：签发一条限时链接，`ttl` 秒（clamp 60 秒 ~ 7 天）：

```bash
curl -s -X POST $BASE/v1/jobs/$JOB/share -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"ttl": 1800}'
# → {"expires_in":1800,"images":[{"index":0,"url":"…/public/jobs/$JOB/images/0?exp=…&sig=…"}]}
curl -s "<拿到的 url>" -o shared.png     # 不带 Authorization；改字符 / 过期 → 403
```

CLI 一条命令等价：`comfyui share $JOB --ttl 30m`（默认 1 小时，`--json` 出机器可读）。
只能分享**已出图**的作业（还在排队/执行 → 400），链接只对应这一张图、签不进别的作业。

- `status`：`queued` → `running` → `completed` / `failed` / `cancelled`
- `inputs`：`{"image_1": "<file_id>"}` 把参考图接到工作流里第 N 个 `LoadImage` 节点（按节点 id
  升序），槽位从 1 起。`file_id` 绑签发它的 token：别人的 → 403，不存在 / 已过期 → 404；
  显式 `overrides` 在 `inputs` 之后应用，能覆盖它写进去的 `image`
- 自带工作流放进 `workflow`；顶层有 `nodes` 数组的是 UI 格式，会被 400 拒绝
- 批量：把对象放进数组，逐项校验、逐项给结果（`jobs[]` 与请求一一对应），能收的先入队

## 8. 状态码与限制

| 状态码 | 含义 |
|---|---|
| 400 | 工作流不合法：UI 格式 / `overrides` 指向不存在的节点或输入名 / 批量数组为空或超 50 项；`inputs` 键不是 `image_N`、参考图像素超 40 MP |
| 401 | 缺少 / 错误 / 已吊销 / 已过期的 token |
| 403 | 拿设备 token 访问 `/v1/tokens`、`/v1/clients`（管理端点只认共享 token）；引用了别的 token 上传的参考图；分享链接签名不对 / 已过期 |
| 404 | job_id、模板或参考图 `file_id` 不存在（作业只保留最近 200 条已结束的；参考图默认留 24 小时） |
| 413 | 上传的参考图超过 10 MB |
| 415 | 上传的内容不是 PNG / JPEG / WebP（魔数不符，或 `Content-Type` 不在这三种里） |
| 429 | 申请设备码太频繁（同 IP 10s 一次），按 `Retry-After` 稍后重试 |
| 502 | 上游取图失败 |
| 503 | 队列满（默认 8），按 `Retry-After: 30` 稍后重试 |

- 执行**并发 1**（单卡单任务）：提交后按 `queue_position` 自行调度，不要盲目重试
- 单作业超时 3600s，超时自动取消并标记 `failed`
- 作业记录落 SQLite，**服务重启后仍可按 job_id 查询**，在跑的作业会被接回继续跟踪
  （ComfyUI 本身不因封装层重启而停下），所以别因为一次查询失败就重提作业
- 图片留在 ComfyUI 的 output 目录，由服务方定期清理，下载请及时
