一句话定义
ComfyUI 的工作流有两种 JSON 形态:UI 格式(画布结构,给人看)与 API 格式(以节点 id 为键的执行字典,给机器跑);开启"开发者模式"导出 API 格式后,用 HTTP POST /prompt 就能把任何工作流变成无人值守的批量生产线。
为什么重要
这是 ComfyUI 与"玩具工具"的分水岭:工作流即程序。批量出图、接入业务系统(电商管线 案例研究:电商商品图生产管线)、构建生成服务,都靠这一页。
前置知识
队列、种子与可复现性(队列与复现)、节点与工作流的心智模型：端口、连线与执行(节点 id 与数据流)。
核心概念
两种 JSON 的差异:
| UI 格式 | API 格式 | |
|---|---|---|
| 结构 | nodes[] + links[](画布坐标) | { "节点id": {class_type, inputs} } |
| 用途 | 界面保存/分享/还原画布 | 交给执行引擎 |
| 获取 | Workflow → Save | 开启 Dev mode → Export (API) |
| 节点 id | 数字字符串 | 同上(inputs 里以 ["id", 端口序号] 引用上游) |
最小可用调用(Python 标准库):
import json, urllib.request
workflow = json.load(open("workflow_api.json")) # 导出的 API 格式
workflow["6"]["inputs"]["text"] = "a product photo" # 6 = CLIP Text Encode 的节点 id
workflow["31"]["inputs"]["seed"] = 42 # 31 = KSampler
data = json.dumps({"prompt": workflow}).encode()
urllib.request.urlopen(urllib.request.Request(
"http://127.0.0.1:8188/prompt", data,
{"Content-Type": "application/json"})) # 入队常用端点:
| 端点 | 方法 | 作用 |
|---|---|---|
/prompt | POST | 提交工作流入队(返回 prompt_id) |
/history/{id} | GET | 查询任务状态与输出文件名 |
/view?filename=… | GET | 取回生成的图像 |
/ws | WebSocket | 实时进度(逐节点/预览) |
/interrupt | POST | 中断当前任务 |
原理与机制
API 格式就是执行引擎的输入语言:界面画布只是它的编辑器。执行流程:POST /prompt → 服务端校验节点与参数 → 入队 → 拓扑执行 → 产物落 output 并记入 history。自动化脚本做的事本质和"人在界面按运行"完全等价——因此 队列、种子与可复现性 的可复现三要素在 API 场景同样成立(模型+参数+seed 必须显式写进 JSON)。
批量生产的骨架:
for sku in 商品清单:
wf["6"]["inputs"]["text"] = 场景化 prompt(sku)
wf["31"]["inputs"]["seed"] = 固定基线种子 + sku 序号
POST /prompt → 轮询 /history → /view 取图 → 归档直观类比
UI 格式是乐谱(给人演奏看,带表情记号与排版),API 格式是MIDI 数据(给合成器精确执行)。导出 API = 把乐谱转成 MIDI;脚本循环改 prompt = 自动钢琴按曲单演奏一整晚。
实例与案例
- 电商批量出图(案例研究:电商商品图生产管线 详版):CSV 里每行一个 SKU(名称/场景/颜色),脚本循环替换 prompt 与蒙版图,一晚产出全目录素材。
- 进度监听:WebSocket 收到逐节点进度事件,可做 Web 看板;简单场景轮询 /history 即可。
- 多机分流:两台机器各起 ComfyUI,脚本按负载把 /prompt 发往不同地址——队列天然支持横向扩展。
常见误区
- 导出成 UI 格式去调 API:报错"invalid prompt";先在 Settings 勾选开发者模式,确认导出的是 API 格式。
- 节点 id 猜错:id 在不同工作流里不同;在界面上看节点标题旁的编号,或直接读 JSON 找 class_type。
- 忘了 seed 是字符串坑:某些节点的 inputs 值是列表
["上游id", 输出序号],直接当标量改会破坏连接;只改叶子参数(text/seed 等)。 - 不处理失败:队列静默失败(模型缺失等)会让批量任务"悄悄少图";每次 POST 后轮询 /history 校验 status。
- 把 API 服务暴露公网裸奔:
--listen+ 无鉴权 = 任何人可提交任意工作流(安全:不可信工作流与 pickle 风险);加反代鉴权或保持本机。
自测题
- UI 格式与 API 格式的结构与用途差异?
- 修改 API JSON 时,"叶子参数"与"上游引用"如何区分?
- 批量脚本的最小闭环包含哪四个步骤?
- 为什么批量任务要校验 /history?
参考答案
- UI:节点+连线+坐标,供界面还原;API:{id→class_type+inputs},供引擎执行。
- 叶子参数是标量(text/seed/number);上游引用是 ["节点id", 输出序号] 列表,不可当标量改。
- 读 API JSON → 循环改叶子参数 → POST /prompt → 轮询 /history 并经 /view 取图。
- 队列失败是静默的(模型缺失/参数错),不校验会导致批量产物缺图且难以发现。
与其他知识点的关系
- 案例研究:电商商品图生产管线 是本页的完整商业案例。
- 子图与模板复用:工作流的组件化 的子图让复杂工作流在 API 侧更易维护。
- 队列、种子与可复现性 的复现纪律在自动化场景直接决定产物可控性。
延伸阅读
- ComfyUI 官方 API 文档:docs.comfy.org(essentials/automation)
- 社区封装库(可选):comfyapi 类第三方封装
前置知识
队列、种子与可复现性节点与工作流的心智模型：端口、连线与执行