把工作流接入原生 API：从正确导出到取得 prompt_id

用途与适用范围

本指南面向调用自有或获授权 ComfyUI 实例的开发者。网站提供的 MCP 与 ComfyUI 原生 HTTP API 是两套不同接口；这里讨论后者，不涉及自动登录第三方平台或绕过访问限制。

已核对的依据

官方服务端路由定义 POST /prompt 负责校验与排队，返回 prompt_id 或结构化错误。执行事件与历史接口用于后续追踪，因此提交请求与任务完成必须分开。 D09 D10 C01

开始前需要分清的事项

1. 使用当前实例能够正常打开和运行的工作流，并采用 API 导出格式。

2. 核对自定义节点与模型在目标服务端存在，不假设本机与服务器环境一致。

3. 远程部署使用受保护入口，不把无限制生成接口直接暴露公网。

操作与检查步骤

以下步骤是基于所列资料编排的操作建议；具体文件、版本和运行环境仍需按实际项目核对。

第 1 步。 从原生 UI 导出 API 工作流，确认节点包含 class_type 和 inputs；不要直接把带位置的 UI nodes 数组当 prompt。

第 2 步。 使用服务端实际模型选项和文件路径替换必要输入，保持所有连接 ID 与输出槽有效。

第 3 步。 构造包含 prompt 和可追踪 client_id 的请求体；发送后检查 HTTP 状态及 error/node_errors，不忽略失败响应。

第 4 步。 拿到 prompt_id 后保存它，按 WebSocket 或历史接口跟踪成功、失败、中断；重试逻辑要防止重复排队。

可复制的检查命令

请求结构示意（API_WORKFLOW 应替换为真实导出对象）：

const body = { prompt: API_WORKFLOW, client_id: CLIENT_ID };
const response = await fetch(`${COMFY_BASE_URL}/prompt`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
});
const result = await response.json();
if (!response.ok || !result.prompt_id) {
  throw new Error("提交失败：请读取已脱敏的 error 与 node_errors");
}

完成后的检查

请求通过校验、产生有效 ID，并最终取得对应任务结果。仅返回 HTTP 200 或队列编号不能对用户显示“已生成”。

注意事项与尚未确认的部分

以下代码片段只展示请求外形，不是可独立执行的完整工作流。实际节点定义、认证与网络超时应按部署实现。

资料核对日期：2026-09-21。本站未执行此工作流，未进行 GPU、最低显存或耗时测试。

原始资料

• D09 · ComfyUI Server API routes。核对：2026-09-21。
• D10 · ComfyUI execution messages。核对：2026-09-21。
• C01 · ComfyUI execution.py validation。核对：2026-09-21。

相关排查与操作

• POST /prompt 返回 400：读取 node_errors，区分校验和执行失败
• Node has no class_type：区分错误导出与真正缺少节点
• WebSocket 有连接却收不到结果：按 prompt_id 跟踪终止状态
• API 结果怎么取回：从任务历史到实际图片文件