ComfyUI 工作流怎麼打包成 API：教程、排障和 FAQ

ComfyUI 很適合搭建 AI 繪圖、換臉、放大、局部重繪和視頻生成工作流。但如果只停留在 Web 界面裏拖節點，它更像一個創作工具；如果想接入網站、Bot、後臺任務或企業流程，就需要把工作流打包成 API。

這篇按“教程 + 排障 + FAQ”整理，目標是把一個能在 ComfyUI 裏手動運行的工作流，變成後端可以提交任務、等待結果、下載圖片的接口。重點不在寫一個複雜平臺，而是先跑通最小閉環。

先理解 ComfyUI 的 API 化思路

ComfyUI 的 API 調用本質上不是“把節點變成函數”，而是把整個工作流 JSON 作爲 prompt 提交給 ComfyUI 後端。後端按節點圖執行，生成結果後，你再通過 history 或文件接口拿輸出。

最小鏈路是：

在 ComfyUI Web 界面調好工作流。
導出 API 格式的 workflow JSON。
在後端代碼裏替換 prompt、圖片、尺寸、seed 等輸入。
調用 /prompt 提交任務。
根據 prompt_id 查詢 /history。
讀取輸出圖片或視頻文件。

只要這個鏈路跑通，就可以繼續封裝成你自己的 REST API、隊列任務或 SaaS 功能。

準備一個穩定工作流

不要一開始就拿幾十個自定義節點的複雜工作流做 API 化。先選一個能穩定出圖的基礎 workflow，例如：

文生圖。
圖生圖。
圖片放大。
局部重繪。
固定風格海報。

先在 Web UI 裏確認幾件事：

模型文件已經下載。
自定義節點沒有缺失。
輸入圖片路徑能正常讀取。
單次運行能生成結果。
輸出節點能保存圖片。

如果手動都跑不通，API 調用只會把問題隱藏得更深。

導出 API 格式 workflow

在 ComfyUI 界面裏，普通保存的 workflow 和 API 調用需要的 prompt JSON 不完全一樣。通常要開啓開發者相關選項，然後導出 API 格式。

你要拿到的 JSON 大致長這樣：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


{
  "3": {
    "class_type": "KSampler",
    "inputs": {
      "seed": 123456,
      "steps": 20,
      "cfg": 7,
      "sampler_name": "euler",
      "scheduler": "normal"
    }
  },
  "6": {
    "class_type": "CLIPTextEncode",
    "inputs": {
      "text": "a cat sitting on a desk"
    }
  }
}

每個數字 key 是節點 ID。API 化時，你要修改的通常就是這些節點的 inputs。

找到需要替換的節點

導出後先不要急着寫代碼。打開 JSON，標記哪些字段要由用戶輸入控制。

常見需要替換的字段：

用途	常見節點	常見字段
正向提示詞	`CLIPTextEncode`	`text`
反向提示詞	`CLIPTextEncode`	`text`
隨機種子	`KSampler`	`seed`
步數	`KSampler`	`steps`
尺寸	`EmptyLatentImage`	`width`、`height`
輸入圖片	`LoadImage`	`image`
輸出文件	`SaveImage`	`filename_prefix`

建議在項目裏維護一個映射表，例如：

1
2
3
4
5
6
7


{
  "positive_prompt_node": "6",
  "negative_prompt_node": "7",
  "sampler_node": "3",
  "latent_node": "5",
  "save_node": "9"
}

這樣後續 workflow 節點調整時，只需要改映射，不用在業務代碼裏到處找節點 ID。

用 Python 提交 prompt

下面是一個最小示例：讀取 workflow JSON，替換提示詞，然後提交給本地 ComfyUI。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


import json
import urllib.request
import uuid

COMFYUI_URL = "http://127.0.0.1:8188"


def queue_prompt(prompt):
    payload = {
        "prompt": prompt,
        "client_id": str(uuid.uuid4())
    }
    data = json.dumps(payload).encode("utf-8")
    req = urllib.request.Request(
        f"{COMFYUI_URL}/prompt",
        data=data,
        headers={"Content-Type": "application/json"}
    )
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read().decode("utf-8"))


with open("workflow_api.json", "r", encoding="utf-8") as f:
    workflow = json.load(f)

workflow["6"]["inputs"]["text"] = "a clean product photo of a white sneaker"
workflow["7"]["inputs"]["text"] = "blurry, low quality, text watermark"
workflow["3"]["inputs"]["seed"] = 123456789

result = queue_prompt(workflow)
print(result)

成功後通常會返回 prompt_id。後續就靠它查詢結果。

查詢任務結果

提交任務後，ComfyUI 不會馬上把圖片直接返回給你。需要查詢 history：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


import json
import time
import urllib.request


def get_history(prompt_id):
    with urllib.request.urlopen(f"{COMFYUI_URL}/history/{prompt_id}") as resp:
        return json.loads(resp.read().decode("utf-8"))


prompt_id = result["prompt_id"]

for _ in range(60):
    history = get_history(prompt_id)
    if prompt_id in history:
        print(json.dumps(history[prompt_id], indent=2, ensure_ascii=False))
        break
    time.sleep(1)
else:
    raise TimeoutError("ComfyUI task timed out")

history 裏會包含輸出節點和文件信息。你需要從裏面找到 filename、subfolder、type 等字段，再調用 /view 下載。

下載輸出圖片

一個常見下載方式是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


from urllib.parse import urlencode


def download_image(filename, subfolder="", folder_type="output"):
    params = urlencode({
        "filename": filename,
        "subfolder": subfolder,
        "type": folder_type
    })
    url = f"{COMFYUI_URL}/view?{params}"
    with urllib.request.urlopen(url) as resp:
        return resp.read()

拿到 bytes 後可以寫入本地文件、上傳對象存儲，或者返回給你的業務 API。

封裝成自己的 REST API

實際項目裏，不建議讓前端直接調用 ComfyUI。更穩的結構是：

1
2
3
4
5
6
7
8
9


用户前端
  ↓
你的业务 API
  ↓
任务队列
  ↓
ComfyUI API
  ↓
对象存储 / 本地输出目录

業務 API 負責：

校驗用戶參數。
控制尺寸、步數、模型和風格。
限制併發和頻率。
管理任務狀態。
返回最終圖片 URL。

ComfyUI 只負責執行生成，不直接暴露給公網。

常見報錯：連接不上 ComfyUI

典型表現：

1
2


connection refused
failed to connect to 127.0.0.1:8188

排查順序：

ComfyUI 是否正在運行。
端口是否是 8188。
後端代碼和 ComfyUI 是否在同一臺機器。
Docker、WSL 或遠程服務器裏 localhost 是否指向正確。
防火牆是否攔截端口。

如果後端跑在容器裏，127.0.0.1 指的是容器本身，不是宿主機。需要改成宿主機地址或使用 Docker 網絡服務名。

常見報錯：prompt 格式不對

典型表現：

1
2


invalid prompt
prompt outputs failed validation

常見原因：

使用了普通 workflow JSON，而不是 API 格式 JSON。
節點 ID 寫錯。
刪除了某個必需輸入。
輸入類型不匹配，例如把數字寫成字符串。
自定義節點缺失，導致 class_type 無法識別。

排查方法：

先用原始導出的 JSON 提交，不做任何替換。
原始 JSON 能跑，再逐個替換字段。
對照 Web UI 中的節點 ID 和字段。
看 ComfyUI 控制檯的詳細報錯。

不要一次替換十幾個字段。每次只改一個變量，最容易定位。

常見報錯：找不到模型或自定義節點

典型表現：

1
2
3


CheckpointLoaderSimple: ckpt_name not found
Cannot import custom node
class_type not found

原因通常是 API 服務器環境和你導出 workflow 的環境不一致。

檢查這些目錄：

models/checkpoints
models/loras
models/vae
models/controlnet
custom_nodes

如果在開發機能跑，部署機不能跑，優先檢查模型文件名、自定義節點版本和依賴包。

常見報錯：輸入圖片讀取失敗

圖生圖、換臉、局部重繪經常遇到圖片路徑問題。

注意幾點：

LoadImage 通常讀取 ComfyUI 輸入目錄裏的文件。
直接傳本機任意路徑不一定可用。
API 調用前可能需要先上傳圖片到 ComfyUI。
Windows 和 Linux 路徑格式不同。

更穩的做法是把用戶圖片上傳到 ComfyUI 的 input 目錄或使用上傳接口，再把返回的文件名寫入 LoadImage 節點。

常見報錯：任務一直排隊

如果 /prompt 返回了 prompt_id，但 history 一直沒有結果，可能是：

GPU 正在執行其他任務。
某個節點卡住。
模型加載非常慢。
顯存不足導致反覆切換。
ComfyUI 後端已經報錯但業務端沒讀取到。

建議做：

查看 ComfyUI 控制檯日誌。
給業務側輪詢加超時。
限制併發任務數量。
對大圖、視頻、高清修復設置更長但明確的超時。
失敗後返回可讀錯誤，而不是讓用戶一直等。

常見報錯：顯存不足

典型表現：

1
2


CUDA out of memory
Allocation failed

處理方法：

降低分辨率。
減少 batch size。
減少 steps。
換更小模型。
關閉不必要的 ControlNet、LoRA 或高清修復。
對不同工作流設置不同隊列。

API 化以後更要控制用戶輸入。不要讓用戶隨便傳 4096 x 4096、100 steps、多個 LoRA 疊加，否則服務很容易被打滿。

常見問題：結果文件找不到

如果 history 裏有文件名，但下載時報 404，常見原因是：

filename、subfolder、type 參數傳錯。
輸出節點不是 SaveImage。
文件保存到臨時目錄。
任務失敗，history 裏沒有真正輸出。
多實例部署時，請求到了另一臺 ComfyUI。

排查時先打印 history 的 outputs，不要憑記憶拼 URL。

上線前要做的保護

把 ComfyUI 包成 API 後，不要裸奔上線。至少要考慮：

鑑權。
頻率限制。
併發限制。
輸入尺寸限制。
prompt 長度限制。
禁止用戶選擇任意模型路徑。
輸出文件清理。
失敗重試和超時。
任務狀態持久化。

ComfyUI 很適合做生成引擎，但業務層要自己補上權限、隊列、審計和資源控制。

FAQ

ComfyUI 自帶 API 嗎？

有。常用的是 /prompt、/history/{prompt_id} 和 /view 這類接口。實際項目通常會在外面再包一層業務 API，避免直接暴露 ComfyUI。

爲什麼導出的 workflow 不能直接調用？

可能導出的是普通 workflow，不是 API 格式；也可能缺模型、自定義節點，或者某些輸入路徑只在 Web UI 當前環境裏有效。先用原始 API JSON 測試，再逐步替換參數。

前端可以直接調用 ComfyUI 嗎？

不建議。前端直接調用會暴露服務地址，也不好做鑑權、限流和參數控制。更穩的是前端調用你的後端，後端再調用 ComfyUI。

多用戶併發怎麼處理？

不要讓所有請求直接打到 ComfyUI。建議加任務隊列，限制併發數，按任務狀態輪詢。高成本工作流可以單獨隊列。

輸出圖片應該存在哪裏？

開發階段可以存在 ComfyUI output 目錄。上線後更建議上傳到對象存儲或業務文件服務，再返回穩定 URL，同時定期清理本地臨時文件。

節點 ID 變了怎麼辦？

如果重新編輯 workflow，節點 ID 可能變化。建議維護一份參數映射，並在每次更新 workflow 後跑一次最小 API 測試。

可以把多個 workflow 做成一個 API 嗎？

可以，但不要讓用戶直接傳任意 workflow JSON。更安全的做法是後端維護白名單模板，用戶只能選擇模板和有限參數。

視頻工作流和圖片工作流有什麼區別？

視頻工作流通常耗時更長、顯存壓力更大、輸出文件更大，必須加更嚴格的隊列、超時和文件管理。先把圖片鏈路跑通，再擴展視頻。

小結

把 ComfyUI 工作流打包成 API，本質是把穩定的節點圖變成可替換參數的 prompt JSON，再通過 /prompt 提交任務，通過 /history 查詢結果，通過 /view 獲取文件。真正的難點不在發請求，而在工作流穩定性、參數邊界、隊列併發、文件管理和錯誤處理。

建議先從一個最簡單的文生圖 workflow 開始，跑通導出、提交、輪詢、下載四步。等最小閉環穩定後，再加入上傳圖片、風格模板、用戶隊列和生產級保護。