C · HTTP / WebSocket 路由表
这是一张源码阅读地图，不是稳定公开 API 的版本承诺。部分 legacy 路由还会被复制到 /api 前缀；可选功能、Manager 和 frontend package 会改变最终表。
实时连接
| 方法 | 路径 | 作用 | 关键状态 |
|---|---|---|---|
| GET | /ws | WebSocket 建连、重连、状态与执行消息 | sockets[sid]、feature flags |
常见服务端事件：status、execution_start、executing、progress、executed、execution_cached、execution_success、execution_error。预览使用 binary frame。
能力与前端
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | / | 托管 FrontendManager 提供的首页 |
| GET | /extensions | 前端扩展清单 |
| GET | /embeddings | embedding 名称 |
| GET | /system_stats | 系统、设备、版本与内存信息 |
| GET | /features | 后端 feature flags |
| GET | /object_info | 全部节点 schema |
| GET | /object_info/{node_class} | 单节点 schema |
| GET | /workflow_templates | custom node workflow templates |
| GET | /i18n | 自定义节点本地化资源 |
| GET | /node_replacements | 前端/服务端节点替换信息 |
| GET | /global_subgraphs | 全局子图列表 |
| GET | /global_subgraphs/{id} | 单个全局子图 |
/object_info 是调试节点注册的首选：如果节点不在这里，问题发生在发现/装载/schema 阶段，不在画布渲染。
模型发现
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /models | 可枚举的模型 folder categories |
| GET | /models/{folder} | 某类别下的相对模型名 |
| GET | /experiment/models | 新模型管理接口总览 |
| GET | /experiment/models/{folder} | 实验接口的类别内容 |
| GET | /experiment/models/preview/{folder}/{path_index}/{filename...} | 模型预览 |
这些路由读取 folder_paths 注册，不触发 checkpoint model detection。
文件上传与查看
| 方法 | 路径 | 作用 | 安全点 |
|---|---|---|---|
| POST | /upload/image | 上传 input/output/temp 图像 | commonpath、重名处理 |
| POST | /upload/mask | 以 alpha 更新原图 mask | original_ref 再验证 |
| GET | /view | 原图、preview、RGB/alpha、asset hash | traversal、MIME、attachment |
| GET | /view_metadata/{folder_name} | 读取特定模型/文件 metadata | folder category 边界 |
Prompt、队列与历史
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /prompt | 当前队列/Prompt 状态摘要 |
| POST | /prompt | 验证并把 API Prompt 入队 |
| GET | /queue | waiting + running |
| POST | /queue | 删除/清理等待队列项 |
| POST | /interrupt | 请求中断当前执行 |
| POST | /free | 请求卸载模型/释放内存 |
| GET | /history | 内存执行 history 列表 |
| GET | /history/{prompt_id} | 某 Prompt history |
| POST | /history | 清空或删除 history 项 |
POST /prompt 返回成功只说明 validation + enqueue 成功；最终状态应看 WebSocket 或 history。
Jobs facade
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /api/jobs | 统一列出 queued/running/completed jobs |
| GET | /api/jobs/{job_id} | 查询单个 job |
| POST | /api/jobs/{job_id}/cancel | 取消指定 job |
| POST | /api/jobs/cancel | 批量/条件取消 |
Jobs 在该快照中是对现有 queue/history 状态的 API 表达，不应自动推断为独立持久任务数据库。
用户与设置
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /users | profile 列表/存储模式 |
| POST | /users | 新增 profile |
| GET | /userdata | 列目录 |
| GET | /v2/userdata | 新版列表语义 |
| GET | /userdata/{file} | 读取用户文件 |
| POST | /userdata/{file} | 写用户文件 |
| DELETE | /userdata/{file} | 删除用户文件 |
| POST | /userdata/{file}/move/{dest} | 移动用户文件 |
| GET | /settings | 全部设置 |
| GET | /settings/{id} | 单项设置 |
| POST | /settings | 批量/整体写设置 |
| POST | /settings/{id} | 单项写设置 |
comfy-user 选择 profile，不等于强认证；路径仍以 user public root 做包含检查。
可选 Assets API
仅启用 Assets 时：
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /api/assets | 过滤、分页列资产引用 |
| GET | /api/assets/{uuid} | 单条详情 |
| GET | /api/assets/{uuid}/content | 下载/查看内容 |
| POST | /api/assets/from-hash | 由内容 hash 解析/创建引用 |
| POST | /api/assets | 创建/上传资产 |
| PUT | /api/assets/{uuid} | 更新引用 metadata |
| DELETE | /api/assets/{uuid} | 删除引用/资产语义 |
| GET | /api/tags | tag 列表/统计 |
| POST | /api/assets/{uuid}/tags | 添加 tag |
| DELETE | /api/assets/{uuid}/tags | 删除 tag |
| GET | /api/assets/tags/refine | 按当前过滤细化 tags |
| POST | /api/assets/seed | 启动目录扫描 |
| GET | /api/assets/seed/status | 扫描状态 |
| POST | /api/assets/seed/cancel | 取消扫描 |
| POST | /api/assets/prune | 标记/清理缺失引用 |
内部子应用与兼容路由
add_routes() 还会：
- 挂 internal routes 到
/internal子应用； - 将非
/api、非/internal的 legacy routes 复制到/api； - 以
/extensions/{name}挂 custom node web 目录； - 挂 embedded docs；
- 挂静态前端根目录，并限制静态 symlink 策略。
因此通过源码搜索 decorator 得到的表仍不一定等于运行实例 router 的所有路径。最可靠的运行时答案来自实际 feature flags、已加载 managers 与 app router。
调用关系速查
提交生成： POST /prompt → WebSocket events → GET /view
轮询生成： POST /prompt → GET /history/{id} → GET /view
取消等待： GET /queue → POST /api/jobs/{id}/cancel 或 POST /queue
中断运行： POST /interrupt / jobs cancel → cooperative interrupt
查节点： GET /object_info/{class}
查模型名： GET /models/{folder}
上传输入： POST /upload/image(type=input) → API Prompt LoadImage客户端健壮性
- 不依赖未文档化路由永久存在；记录后端 version/features。
- 处理 HTTP validation 与 WebSocket execution error 两阶段失败。
- 重连保留 client ID，并用 prompt ID 对齐事件。
- 下载结果时使用服务端返回的 filename/subfolder/type，而不是手拼绝对路径。
- 对 Assets 做 feature detection；关闭时回退传统文件引用。
- 不把 history 当永久结果仓库，及时复制业务需要的数据。
Last updated on