shuzhiren-comfyui/ComfyUI_API_Documentation.md

ComfyUI 后端 API 接口文档

目录

• 1. WebSocket 连接
• 2. 基础接口
  • 2.1 获取根页面
  • 2.2 获取 Embeddings
  • 2.3 列出模型类型
  • 2.4 获取指定文件夹的模型
  • 2.5 获取扩展
  • 2.6 查看图片
  • 2.7 查看元数据
  • 2.8 系统状态
  • 2.9 获取特性
  • 2.10 获取提示信息
  • 2.11 获取对象信息
  • 2.12 获取特定节点信息
• 3. 文件上传接口
  • 3.1 上传图片
  • 3.2 上传 Mask
• 4. 任务管理接口
  • 4.1 获取所有任务
  • 4.2 获取特定任务
  • 4.3 获取历史记录
  • 4.4 获取特定历史记录
  • 4.5 获取队列
  • 4.6 提交提示
  • 4.7 队列操作
  • 4.8 中断任务
  • 4.9 释放资源
  • 4.10 历史记录操作
• 5. 内部接口
  • 5.1 获取日志
  • 5.2 获取原始日志
  • 5.3 订阅日志
  • 5.4 获取文件夹路径
  • 5.5 获取文件列表
• 6. 任务提交与结果获取流程
  • 6.1 流程接口概述
  • 6.2 任务状态说明
  • 6.3 完整任务生命周期调用示例

---

1. WebSocket 连接

1.1 WebSocket 连接

接口路径： GET /ws

HTTP 方法： GET

请求参数：

参数名	类型	必填	说明
clientId	string	否	客户端ID，用于重连现有会话

请求头要求： 无特殊要求

响应数据结构：

• WebSocket 连接建立后，服务器会发送初始状态消息
• 支持接收和发送 JSON 格式的消息
• 支持二进制消息传输（预览图片等）

错误码及错误信息：

• 连接失败：WebSocket 连接异常

说明：

• 建立 WebSocket 连接用于实时通信
• 如果提供 clientId，会重用现有会话
• 首次连接时会发送服务器特性标志
• 支持实时接收任务状态更新和执行进度

---

2. 基础接口

2.1 获取根页面

接口路径： GET /

HTTP 方法： GET

请求参数： 无

请求头要求： 无特殊要求

响应数据结构：

• 返回 HTML 页面（index.html）

错误码及错误信息：

• 404：页面不存在

说明：

• 返回 ComfyUI 的前端主页
• 设置了不缓存的响应头

---

2.2 获取 Embeddings

接口路径： GET /embeddings

HTTP 方法： GET

请求参数： 无

请求头要求： 无特殊要求

响应数据结构：

[
  "embedding1",
  "embedding2",
  ...
]

字段说明：

• 返回 embeddings 文件夹中所有文件的名称（不含扩展名）

错误码及错误信息：

• 无

说明：

• 获取所有可用的 embedding 文件列表

---

2.3 列出模型类型

接口路径： GET /models

HTTP 方法： GET

请求参数： 无

请求头要求： 无特殊要求

响应数据结构：

[
  "checkpoints",
  "loras",
  "embeddings",
  "vae",
  ...
]

字段说明：

• 返回所有模型文件夹类型的名称

错误码及错误信息：

• 无

说明：

• 获取所有可用的模型类型列表

---

2.4 获取指定文件夹的模型

接口路径： GET /models/{folder}

HTTP 方法： GET

请求参数：

参数名	类型	必填	说明
folder	string	是	模型文件夹名称（路径参数）

请求头要求： 无特殊要求

响应数据结构：

[
  "model1.safetensors",
  "model2.safetensors",
  ...
]

字段说明：

• 返回指定文件夹中的所有模型文件

错误码及错误信息：

• 404：指定的文件夹不存在

说明：

• 获取指定类型文件夹中的所有模型文件

---

2.5 获取扩展

接口路径： GET /extensions

HTTP 方法： GET

请求参数： 无

请求头要求： 无特殊要求

响应数据结构：

[
  "/extensions/core/extension1.js",
  "/extensions/custom/extension2.js",
  ...
]

字段说明：

• 返回所有 JavaScript 扩展文件的路径

错误码及错误信息：

• 无

说明：

• 获取前端扩展文件列表，包括核心扩展和自定义节点扩展

---

2.6 查看图片

接口路径： GET /view

HTTP 方法： GET

请求参数：

参数名	类型	必填	说明
filename	string	是	文件名
type	string	否	文件类型（output/input/temp），默认 output
subfolder	string	否	子文件夹路径
preview	string	否	预览参数（格式：image_format;quality）
channel	string	否	通道类型（rgba/rgb/a），默认 rgba

请求头要求： 无特殊要求

响应数据结构：

• 返回图片文件或预览图片
• Content-Type 根据图片格式自动设置

错误码及错误信息：

• 400：文件名无效或路径不合法
• 403：访问权限不足
• 404：文件不存在

说明：

• 查看或下载生成的图片
• 支持预览格式转换和质量调整
• 支持通道分离（RGB、Alpha）

---

2.7 查看元数据

接口路径： GET /view_metadata/{folder_name}

HTTP 方法： GET

请求参数：

参数名	类型	必填	说明
folder_name	string	是	文件夹名称（路径参数）
filename	string	是	文件名（查询参数）

请求头要求： 无特殊要求

响应数据结构：

{
  "__metadata__": {
    "key1": "value1",
    "key2": "value2"
  }
}

字段说明：

• 返回 safetensors 文件的元数据

错误码及错误信息：

• 404：文件不存在或不是 safetensors 格式

说明：

• 获取 safetensors 模型文件的元数据信息

---

2.8 系统状态

接口路径： GET /system_stats

HTTP 方法： GET

请求参数： 无

请求头要求： 无特殊要求

响应数据结构：

{
  "system": {
    "os": "windows",
    "ram_total": 17179869184,
    "ram_free": 8589934592,
    "comfyui_version": "0.2.0",
    "required_frontend_version": "1.2.0",
    "installed_templates_version": "1.0.0",
    "required_templates_version": "1.0.0",
    "python_version": "3.10.0",
    "pytorch_version": "2.0.0",
    "embedded_python": false,
    "argv": []
  },
  "devices": [
    {
      "name": "cuda:0",
      "type": "cuda",
      "index": 0,
      "vram_total": 8589934592,
      "vram_free": 4294967296,
      "torch_vram_total": 8589934592,
      "torch_vram_free": 4294967296
    }
  ]
}

字段说明：

• system：系统信息
  • os：操作系统类型
  • ram_total：总内存（字节）
  • ram_free：可用内存（字节）
  • comfyui_version：ComfyUI 版本
  • required_frontend_version：所需前端版本
  • installed_templates_version：已安装模板版本
  • required_templates_version：所需模板版本
  • python_version：Python 版本
  • pytorch_version：PyTorch 版本
  • embedded_python：是否使用嵌入式 Python
  • argv：启动参数
• devices：设备信息数组
  • name：设备名称
  • type：设备类型
  • index：设备索引
  • vram_total：总显存（字节）
  • vram_free：可用显存（字节）
  • torch_vram_total：PyTorch 总显存（字节）
  • torch_vram_free：PyTorch 可用显存（字节）

错误码及错误信息：

• 无

说明：

• 获取系统资源使用情况和版本信息

---

2.9 获取特性

接口路径： GET /features

HTTP 方法： GET

请求参数： 无

请求头要求： 无特殊要求

响应数据结构：

{
  "custom_nodes_from_web": true,
  ...
}

字段说明：

• 返回服务器支持的特性列表

错误码及错误信息：

• 无

说明：

• 获取服务器支持的特性标志

---

2.10 获取提示信息

接口路径： GET /prompt

HTTP 方法： GET

请求参数： 无

请求头要求： 无特殊要求

响应数据结构：

{
  "exec_info": {
    "queue_remaining": 5
  }
}

字段说明：

• exec_info：执行信息
  • queue_remaining：队列中剩余的任务数

错误码及错误信息：

• 无

说明：

• 获取当前队列状态信息

---

2.11 获取对象信息

接口路径： GET /object_info

HTTP 方法： GET

请求参数： 无

请求头要求： 无特殊要求

响应数据结构：

{
  "KSampler": {
    "input": {
      "required": {
        "seed": ["INT", {"default": 0, "min": 0, "max": 18446744073709551615}],
        "steps": ["INT", {"default": 20, "min": 1, "max": 1000}],
        ...
      },
      "optional": {...}
    },
    "input_order": {...},
    "output": ["LATENT"],
    "output_is_list": [false],
    "output_name": ["LATENT"],
    "name": "KSampler",
    "display_name": "KSampler",
    "description": "KSampler description",
    "python_module": "nodes",
    "category": "sampling",
    "output_node": false
  },
  ...
}

字段说明：

• 返回所有节点的信息字典
• 每个节点包含：
  • input：输入参数定义（required/optional）
  • input_order：输入参数顺序
  • output：输出类型列表
  • output_is_list：输出是否为列表
  • output_name：输出名称
  • name：节点类名
  • display_name：显示名称
  • description：节点描述
  • python_module：Python 模块
  • category：节点分类
  • output_node：是否为输出节点

错误码及错误信息：

• 无

说明：

• 获取所有可用节点的详细信息

---

2.12 获取特定节点信息

接口路径： GET /object_info/{node_class}

HTTP 方法： GET

请求参数：

参数名	类型	必填	说明
node_class	string	是	节点类名（路径参数）

请求头要求： 无特殊要求

响应数据结构：

{
  "KSampler": {
    "input": {...},
    "output": ["LATENT"],
    ...
  }
}

字段说明：

• 返回指定节点的详细信息（同 2.11）

错误码及错误信息：

• 无（如果节点不存在，返回空对象）

说明：

• 获取指定节点的详细信息

---

3. 文件上传接口

3.1 上传图片

接口路径： POST /upload/image

HTTP 方法： POST

请求参数：

参数名	类型	必填	说明
image	file	是	图片文件
overwrite	string	否	是否覆盖（true/false/1）
type	string	否	上传类型（input/temp/output），默认 input
subfolder	string	否	子文件夹路径

请求头要求：

• Content-Type: multipart/form-data

响应数据结构：

{
  "name": "image.png",
  "subfolder": "",
  "type": "input"
}

字段说明：

• name：保存的文件名
• subfolder：子文件夹路径
• type：文件类型

错误码及错误信息：

• 400：文件无效或路径不合法

说明：

• 上传图片到指定文件夹
• 自动处理文件名冲突（添加序号）
• 支持覆盖模式

---

3.2 上传 Mask

接口路径： POST /upload/mask

HTTP 方法： POST

请求参数：

参数名	类型	必填	说明
image	file	是	Mask 图片文件
original_ref	string	是	原始图片引用（JSON 字符串）
overwrite	string	否	是否覆盖
type	string	否	上传类型
subfolder	string	否	子文件夹路径

请求头要求：

• Content-Type: multipart/form-data

响应数据结构：

{
  "name": "mask.png",
  "subfolder": "",
  "type": "input"
}

字段说明：

• 同 3.1

错误码及错误信息：

• 400：参数无效或原始图片不存在
• 403：访问权限不足

说明：

• 上传 mask 图片并将其应用到原始图片
• original_ref 格式：{"filename": "image.png", "type": "output", "subfolder": ""}

---

4. 任务管理接口

4.1 获取所有任务

接口路径： GET /api/jobs

HTTP 方法： GET

请求参数：

参数名	类型	必填	说明
status	string	否	状态过滤（逗号分隔）：pending, in_progress, completed, failed
workflow_id	string	否	工作流 ID 过滤
sort_by	string	否	排序字段（created_at/execution_duration），默认 created_at
sort_order	string	否	排序方向（asc/desc），默认 desc
limit	integer	否	返回数量限制（正整数）
offset	integer	否	跳过数量（非负整数），默认 0

请求头要求： 无特殊要求

响应数据结构：

{
  "jobs": [
    {
      "id": "prompt_id_1",
      "status": "completed",
      "priority": 1,
      "create_time": 1234567890000,
      "execution_start_time": 1234567891000,
      "execution_end_time": 1234567895000,
      "outputs_count": 4,
      "preview_output": {
        "filename": "image.png",
        "subfolder": "",
        "type": "output",
        "nodeId": "3",
        "mediaType": "images"
      },
      "workflow_id": "workflow_1"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 100,
    "has_more": true
  }
}

字段说明：

• jobs：任务列表
  • id：任务 ID（prompt_id）
  • status：任务状态（pending/in_progress/completed/failed）
  • priority：优先级
  • create_time：创建时间（毫秒时间戳）
  • execution_start_time：执行开始时间
  • execution_end_time：执行结束时间
  • execution_error：执行错误信息（失败时）
  • outputs_count：输出数量
  • preview_output：预览输出
  • workflow_id：工作流 ID
• pagination：分页信息
  • offset：偏移量
  • limit：限制数量
  • total：总数
  • has_more：是否有更多

错误码及错误信息：

• 400：参数无效（状态值、排序字段等）

说明：

• 获取所有任务列表，支持过滤、排序和分页
• 包括运行中、排队、已完成和失败的任务

---

4.2 获取特定任务

接口路径： GET /api/jobs/{job_id}

HTTP 方法： GET

请求参数：

参数名	类型	必填	说明
job_id	string	是	任务 ID（路径参数）

请求头要求： 无特殊要求

响应数据结构：

{
  "id": "prompt_id_1",
  "status": "completed",
  "priority": 1,
  "create_time": 1234567890000,
  "execution_start_time": 1234567891000,
  "execution_end_time": 1234567895000,
  "outputs": {
    "3": {
      "images": [
        {
          "filename": "image.png",
          "subfolder": "",
          "type": "output"
        }
      ]
    }
  },
  "execution_status": {
    "status_str": "success",
    "messages": [...]
  },
  "workflow": {
    "prompt": {...},
    "extra_data": {...}
  },
  "outputs_count": 4,
  "preview_output": {...},
  "workflow_id": "workflow_1"
}

字段说明：

• 同 4.1，额外包含：
  • outputs：完整输出数据
  • execution_status：执行状态详情
  • workflow：工作流详情

错误码及错误信息：

• 400：job_id 参数缺失
• 404：任务不存在

说明：

• 获取指定任务的详细信息，包括完整输出和工作流数据

---

4.3 获取历史记录

接口路径： GET /history

HTTP 方法： GET

请求参数：

参数名	类型	必填	说明
max_items	integer	否	最大返回数量
offset	integer	否	偏移量，默认 -1（返回所有）

请求头要求： 无特殊要求

响应数据结构：

{
  "prompt_id_1": {
    "prompt": [...],
    "outputs": {...},
    "status": {...}
  },
  ...
}

字段说明：

• 返回历史记录字典，key 为 prompt_id
• 每个记录包含：
  • prompt：提示数据
  • outputs：输出数据
  • status：状态信息

错误码及错误信息：

• 无

说明：

• 获取已执行任务的历史记录

---

4.4 获取特定历史记录

接口路径： GET /history/{prompt_id}

HTTP 方法： GET

请求参数：

参数名	类型	必填	说明
prompt_id	string	是	提示 ID（路径参数）

请求头要求： 无特殊要求

响应数据结构：

{
  "prompt": [...],
  "outputs": {...},
  "status": {...}
}

字段说明：

• 同 4.3

错误码及错误信息：

• 无（如果不存在返回空对象）

说明：

• 获取指定提示 ID 的历史记录

---

4.5 获取队列

接口路径： GET /queue

HTTP 方法： GET

请求参数： 无

请求头要求： 无特殊要求

响应数据结构：

{
  "queue_running": [
    [1, "prompt_id_1", {...}, {...}, [...]]
  ],
  "queue_pending": [
    [2, "prompt_id_2", {...}, {...}, [...]],
    [3, "prompt_id_3", {...}, {...}, [...]]
  ]
}

字段说明：

• queue_running：正在运行的任务列表
• queue_pending：等待中的任务列表
• 每个任务是一个 5 元组：
  • [0]：优先级（数字）
  • [1]：prompt_id
  • [2]：prompt 数据
  • [3]：extra_data
  • [4]：outputs_to_execute

错误码及错误信息：

• 无

说明：

• 获取当前队列状态，包括运行中和等待中的任务

---

4.6 提交提示

接口路径： POST /prompt

HTTP 方法： POST

请求参数：

参数名	类型	必填	说明
prompt	object	是	工作流提示对象
prompt_id	string	否	提示 ID，默认自动生成 UUID
client_id	string	否	客户端 ID
number	number	否	任务编号
front	boolean	否	是否插入队列前面
partial_execution_targets	array	否	部分执行目标
extra_data	object	否	额外数据

请求头要求：

• Content-Type: application/json

响应数据结构：

{
  "prompt_id": "550a8d1c-1234-4567-89ab-123456789abc",
  "number": 1,
  "node_errors": {}
}

字段说明：

• prompt_id：生成的提示 ID
• number：任务编号
• node_errors：节点错误信息

错误码及错误信息：

• 400：提示无效或验证失败
  • error：错误信息
  • node_errors：节点错误详情

说明：

• 提交工作流任务到队列
• 自动验证提示的有效性
• 返回 prompt_id 用于后续查询

---

4.7 队列操作

接口路径： POST /queue

HTTP 方法： POST

请求参数：

参数名	类型	必填	说明
clear	boolean	否	是否清空队列
delete	array	否	要删除的任务 ID 列表

请求头要求：

• Content-Type: application/json

响应数据结构：

• HTTP 200 OK

错误码及错误信息：

• 无

说明：

• 清空队列或删除指定任务
• 可以同时执行清空和删除操作

---

4.8 中断任务

接口路径： POST /interrupt

HTTP 方法： POST

请求参数：

参数名	类型	必填	说明
prompt_id	string	否	要中断的任务 ID（可选）

请求头要求：

• Content-Type: application/json

响应数据结构：

• HTTP 200 OK

错误码及错误信息：

• 无

说明：

• 中断正在运行的任务
• 如果提供 prompt_id，只中断指定任务
• 如果不提供，中断所有正在运行的任务

---

4.9 释放资源

接口路径： POST /free

HTTP 方法： POST

请求参数：

参数名	类型	必填	说明
unload_models	boolean	否	是否卸载模型
free_memory	boolean	否	是否释放内存

请求头要求：

• Content-Type: application/json

响应数据结构：

• HTTP 200 OK

错误码及错误信息：

• 无

说明：

• 释放系统资源
• 可以卸载模型和/或释放内存

---

4.10 历史记录操作

接口路径： POST /history

HTTP 方法： POST

请求参数：

参数名	类型	必填	说明
clear	boolean	否	是否清空历史记录
delete	array	否	要删除的历史记录 ID 列表

请求头要求：

• Content-Type: application/json

响应数据结构：

• HTTP 200 OK

错误码及错误信息：

• 无

说明：

• 清空历史记录或删除指定历史记录
• 可以同时执行清空和删除操作

---

5. 内部接口

5.1 获取日志

接口路径： GET /internal/logs

HTTP 方法： GET

请求参数： 无

请求头要求： 无特殊要求

响应数据结构：

"2024-01-01 12:00:00 - Log message 1\n2024-01-01 12:01:00 - Log message 2\n..."

字段说明：

• 返回格式化的日志字符串

错误码及错误信息：

• 无

说明：

• 获取系统日志（内部接口，仅供前端使用）

---

5.2 获取原始日志

接口路径： GET /internal/logs/raw

HTTP 方法： GET

请求参数： 无

请求头要求： 无特殊要求

响应数据结构：

{
  "entries": [
    {"t": "2024-01-01 12:00:00", "m": "Log message 1"},
    {"t": "2024-01-01 12:01:00", "m": "Log message 2"}
  ],
  "size": {
    "cols": 80,
    "rows": 24
  }
}

字段说明：

• entries：日志条目数组
  • t：时间戳
  • m：消息内容
• size：终端大小
  • cols：列数
  • rows：行数

错误码及错误信息：

• 无

说明：

• 获取原始日志数据（内部接口）

---

5.3 订阅日志

接口路径： PATCH /internal/logs/subscribe

HTTP 方法： PATCH

请求参数：

参数名	类型	必填	说明
clientId	string	是	客户端 ID
enabled	boolean	是	是否启用订阅

请求头要求：

• Content-Type: application/json

响应数据结构：

• HTTP 200 OK

错误码及错误信息：

• 无

说明：

• 订阅或取消订阅日志推送（内部接口）

---

5.4 获取文件夹路径

接口路径： GET /internal/folder_paths

HTTP 方法： GET

请求参数： 无

请求头要求： 无特殊要求

响应数据结构：

{
  "checkpoints": "path/to/checkpoints",
  "loras": "path/to/loras",
  "embeddings": "path/to/embeddings",
  ...
}

字段说明：

• 返回所有文件夹类型的路径

错误码及错误信息：

• 无

说明：

• 获取所有文件夹路径（内部接口）

---

5.5 获取文件列表

接口路径： GET /internal/files/{directory_type}

HTTP 方法： GET

请求参数：

参数名	类型	必填	说明
directory_type	string	是	目录类型（output/input/temp）

请求头要求： 无特殊要求

响应数据结构：

[
  "file1.png",
  "file2.png",
  ...
]

字段说明：

• 返回指定目录中的文件列表（按修改时间倒序）

错误码及错误信息：

• 400：无效的目录类型

说明：

• 获取指定目录中的文件列表（内部接口）

---

6. 任务提交与结果获取流程

6.1 流程接口概述

ComfyUI 的任务提交与结果获取流程涉及以下核心接口：

1. 提交任务接口：POST /prompt - 提交工作流任务
2. 查询任务接口：GET /api/jobs/{job_id} - 查询任务状态和结果
3. 队列查询接口：GET /queue - 查询队列状态
4. 历史记录接口：GET /history/{prompt_id} - 获取已完成任务的详细信息
5. 文件查看接口：GET /view - 查看生成的图片文件

接口关联方式：

• 提交任务后，POST /prompt 返回 prompt_id
• 使用 prompt_id 通过 GET /api/jobs/{job_id} 查询任务状态
• 任务完成后，通过 GET /history/{prompt_id} 获取完整结果
• 使用返回的文件信息通过 GET /view 下载或查看生成的图片

---

6.2 任务状态说明

任务状态（status）有以下四种：

状态值	英文	说明
pending	待执行	任务在队列中等待执行
in_progress	执行中	任务正在执行
completed	已完成	任务执行成功
failed	失败	任务执行失败

状态转换流程：

pending → in_progress → completed
                    ↓
                  failed

状态判断逻辑：

• pending：任务在 queue_pending 列表中
• in_progress：任务在 queue_running 列表中
• completed：任务在历史记录中，且 status.status_str == "success"
• failed：任务在历史记录中，且 status.status_str == "error"

---

6.3 完整任务生命周期调用示例

步骤 1：提交任务

请求：

POST /prompt
Content-Type: application/json

{
  "prompt": {
    "1": {
      "class_type": "CheckpointLoaderSimple",
      "inputs": {
        "ckpt_name": "v1-5-pruned-emaonly.safetensors"
      }
    },
    "2": {
      "class_type": "CLIPTextEncode",
      "inputs": {
        "text": "a beautiful landscape",
        "clip": ["1", 1]
      }
    },
    "3": {
      "class_type": "KSampler",
      "inputs": {
        "seed": 123456789,
        "steps": 20,
        "cfg": 7.0,
        "sampler_name": "euler",
        "scheduler": "normal",
        "denoise": 1.0,
        "model": ["1", 0],
        "positive": ["2", 0],
        "negative": ["2", 0],
        "latent_image": ["4", 0]
      }
    },
    "4": {
      "class_type": "EmptyLatentImage",
      "inputs": {
        "width": 512,
        "height": 512,
        "batch_size": 1
      }
    },
    "5": {
      "class_type": "VAEDecode",
      "inputs": {
        "samples": ["3", 0],
        "vae": ["1", 2]
      }
    },
    "6": {
      "class_type": "SaveImage",
      "inputs": {
        "filename_prefix": "ComfyUI",
        "images": ["5", 0]
      }
    }
  },
  "client_id": "client_123"
}

响应：

{
  "prompt_id": "550a8d1c-1234-4567-89ab-123456789abc",
  "number": 1,
  "node_errors": {}
}

---

步骤 2：查询任务状态

请求：

GET /api/jobs/550a8d1c-1234-4567-89ab-123456789abc

响应（执行中）：

{
  "id": "550a8d1c-1234-4567-89ab-123456789abc",
  "status": "in_progress",
  "priority": 1,
  "create_time": 1234567890000,
  "outputs_count": 0,
  "workflow_id": null
}

响应（已完成）：

{
  "id": "550a8d1c-1234-4567-89ab-123456789abc",
  "status": "completed",
  "priority": 1,
  "create_time": 1234567890000,
  "execution_start_time": 1234567891000,
  "execution_end_time": 1234567895000,
  "outputs": {
    "6": {
      "images": [
        {
          "filename": "ComfyUI_00001.png",
          "subfolder": "",
          "type": "output"
        }
      ]
    }
  },
  "execution_status": {
    "status_str": "success",
    "messages": [
      ["execution_start", {"timestamp": 1234567891000}],
      ["execution_success", {"timestamp": 1234567895000}]
    ]
  },
  "workflow": {
    "prompt": {...},
    "extra_data": {...}
  },
  "outputs_count": 1,
  "preview_output": {
    "filename": "ComfyUI_00001.png",
    "subfolder": "",
    "type": "output",
    "nodeId": "6",
    "mediaType": "images"
  },
  "workflow_id": null
}

响应（失败）：

{
  "id": "550a8d1c-1234-4567-89ab-123456789abc",
  "status": "failed",
  "priority": 1,
  "create_time": 1234567890000,
  "execution_start_time": 1234567891000,
  "execution_end_time": 1234567892000,
  "execution_error": {
    "node_id": "3",
    "exception_type": "RuntimeError",
    "exception_message": "CUDA out of memory",
    "traceback": "..."
  },
  "outputs_count": 0,
  "workflow_id": null
}

---

步骤 3：查看生成的图片

请求：

GET /view?filename=ComfyUI_00001.png&type=output&subfolder=

响应：

• 返回图片文件（PNG 格式）

请求（带预览参数）：

GET /view?filename=ComfyUI_00001.png&type=output&preview=webp;90

响应：

• 返回 WebP 格式的预览图片（质量 90）

---

步骤 4：查询历史记录

请求：

GET /history/550a8d1c-1234-4567-89ab-123456789abc

响应：

{
  "prompt": [
    1,
    "550a8d1c-1234-4567-89ab-123456789abc",
    {
      "1": {
        "class_type": "CheckpointLoaderSimple",
        "inputs": {...}
      },
      ...
    },
    {
      "client_id": "client_123",
      "create_time": 1234567890000
    },
    [...]
  ],
  "outputs": {
    "6": {
      "images": [
        {
          "filename": "ComfyUI_00001.png",
          "subfolder": "",
          "type": "output"
        }
      ]
    }
  },
  "status": {
    "status_str": "success",
    "messages": [...]
  }
}

---

步骤 5：查询队列状态（可选）

请求：

GET /queue

响应：

{
  "queue_running": [
    [1, "550a8d1c-1234-4567-89ab-123456789abc", {...}, {...}, [...]]
  ],
  "queue_pending": [
    [2, "another_prompt_id", {...}, {...}, [...]]
  ]
}

---

完整流程伪代码示例

import requests
import time

# 1. 提交任务
def submit_task(workflow):
    response = requests.post(
        "http://localhost:8188/prompt",
        json={"prompt": workflow, "client_id": "my_client"}
    )
    return response.json()["prompt_id"]

# 2. 轮询任务状态
def wait_for_completion(prompt_id, poll_interval=1, timeout=300):
    start_time = time.time()
    while time.time() - start_time < timeout:
        response = requests.get(f"http://localhost:8188/api/jobs/{prompt_id}")
        job = response.json()
        
        if job["status"] == "completed":
            return job
        elif job["status"] == "failed":
            raise Exception(f"Task failed: {job.get('execution_error')}")
        
        time.sleep(poll_interval)
    
    raise TimeoutError("Task timed out")

# 3. 获取生成的图片
def get_image(filename, subfolder=""):
    response = requests.get(
        "http://localhost:8188/view",
        params={
            "filename": filename,
            "type": "output",
            "subfolder": subfolder
        }
    )
    return response.content

# 完整流程
workflow = {
    "1": {
        "class_type": "CheckpointLoaderSimple",
        "inputs": {"ckpt_name": "v1-5-pruned-emaonly.safetensors"}
    },
    # ... 其他节点
}

# 提交任务
prompt_id = submit_task(workflow)
print(f"Task submitted: {prompt_id}")

# 等待完成
job = wait_for_completion(prompt_id)
print(f"Task completed: {job}")

# 获取图片
for node_id, outputs in job["outputs"].items():
    for image in outputs.get("images", []):
        image_data = get_image(image["filename"], image["subfolder"])
        with open(image["filename"], "wb") as f:
            f.write(image_data)
        print(f"Saved: {image['filename']}")

---

WebSocket 实时监听（可选）

除了轮询，还可以使用 WebSocket 实时接收任务状态更新：

const ws = new WebSocket('ws://localhost:8188/ws?clientId=my_client');

ws.onopen = () => {
    console.log('WebSocket connected');
};

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    
    if (data.type === 'status') {
        console.log('Queue status:', data.data);
    } else if (data.type === 'executing') {
        console.log('Executing node:', data.data.node);
    } else if (data.type === 'progress') {
        console.log('Progress:', data.data);
    } else if (data.type === 'execution_success') {
        console.log('Execution successful:', data.data);
    } else if (data.type === 'execution_error') {
        console.error('Execution error:', data.data);
    }
};

---

附录

API 前缀说明

ComfyUI 支持两种 API 路径格式：

1. 无前缀：/prompt, /queue, /history 等
2. 带前缀：/api/prompt, /api/queue, /api/history 等

两种格式都可以使用，建议使用带 /api 前缀的格式以便于代理和转发。

错误处理

所有接口在发生错误时都会返回相应的 HTTP 状态码和错误信息：

• 400：请求参数错误
• 403：访问权限不足
• 404：资源不存在
• 500：服务器内部错误

错误响应格式：

{
  "error": "Error message",
  "node_errors": {}
}

认证

ComfyUI 默认不启用认证。如果需要启用认证，请参考相关配置文档。

速率限制

ComfyUI 默认不实施速率限制。在生产环境中，建议通过反向代理（如 Nginx）实施速率限制。

---

文档版本： 1.0
最后更新： 2026-03-12
ComfyUI 版本： 0.2.0+