# Lumyren ComfyUI 节点

把 Lumyren 的远端模型接入 ComfyUI，同时保留本地的图片和视频处理节点。节点包使用 Python 标准库调用本站接口；图片张量转换使用 ComfyUI 已有的 PyTorch、NumPy 和 Pillow，不需要安装 Node.js 或下载本地模型权重。

## 安装与配置

在已有的 ComfyUI Python 3.10 及以上环境中，将完整 `comfyui-lumyren` 文件夹放入 `custom_nodes`，然后重启 ComfyUI。节点出现在 `Lumyren` 分类，包内的 `models.json` 提供发布时的目录选择，执行参数和开放状态仍以实时接口为准。

从启动 ComfyUI 的受限环境配置 `LUMYREN_API_KEY` 和 `LUMYREN_ACCOUNT_ID`。Key 从自己的 Lumyren 空间创建；不填写在画布节点、工作流 JSON 或对话里。正式地址默认 `https://lumyren.com`。节点导入与画布加载不会自动访问接口或生成。

默认历史记录保存在 ComfyUI 用户目录的 `lumyren/空间ID` 中，文件私有；可通过绝对路径 `LUMYREN_HISTORY_DIR` 指定历史记录的父目录。结果保存到 ComfyUI 输出目录的 `lumyren/空间ID`。保留原历史记录，升级节点无需清空它。

## 先报价再提交

把 `examples/01-text-to-image.json` 拖入画布。填写本次创作的 `intent_name`，核对模型与参数，运行后先查看报价。示例的 `submit` 默认关闭，不创建生成任务。

固定价显示 `saleUsd`；语言任务显示按实际用量结算的预留上限，预留不等于最终扣费。普通估算媒体价格不能当作固定价使用。

在已经授权的费用范围内，将 `maximum_usd` 填为本次允许的最高固定费用或语言预留额，再启用 `submit` 并运行。每个新的创作使用不同 `intent_name`；恢复同一次创作保留原名称和完整参数。

同名意图已经有报价时，反复运行不再报价；参数变了会明确报冲突，原记录不覆盖。提交前保存原报价与 UUID。提交超时或重启后，用原意图再次运行以找回同一任务；已经取得任务 ID 时，直接查询原任务。

报价过期不会自动生成新付费意图。先检查原记录和任务状态，再为一项明确的新创作设置新名称。`submission_unknown` 与 `billing_review` 沿原任务核对，不新建任务来盲目重做。

## 输入与结果节点

| 节点 | 用途 |
| --- | --- |
| Model Contract | 读取所选型号的实时契约；可输入自定义完整型号以访问新增模型 |
| Set Parameter | 将文本或 JSON 值放入契约指定的参数字段 |
| Reference List | 组合上传引用列表，用于模型支持的多参考字段 |
| Upload Image | 将一个 ComfyUI IMAGE 编码为 PNG 后上传；同名相同字节复用上传 ID |
| Upload File | 从 ComfyUI input 目录选择原文件，支持服务端接受的图片、视频和音频 |
| Prepare Quote | 获取并持久保存报价，不生成或扣款 |
| Submit Saved Task | 在给定金额上限内提交原意图；恢复时找回原任务 |
| Task Status | 读取已有任务，可短暂等待；超时不重发生成 |
| Download Result | 校验并保存图片、视频、音频、3D、文本等原文件，图片与音视频可预览 |
| Image Result | 把已经校验的图片转换成一个 ComfyUI IMAGE，接入后续本地节点 |
| Text Result | 读取已经校验的 UTF-8 文本或结构 JSON，不执行生成内容 |

Task Status 的 `wait_seconds` 为0时查询一次，最大120秒；网络请求本身还受连接超时约束。视频可能超过该等待时间，保留任务 ID 后继续查询。取消本地等待不会取消已经提交供应商的任务。

生成完成后把真实任务 ID 传入结果节点，`asset_index` 选择任务作品列表中的一项。相同文件已下载且字节与摘要一致时直接复用；已存在但损坏的文件不会被覆盖。按提示选择新的处理方式，保留原文件便于核对。

## 四个示例

- `01-text-to-image.json`：文生图报价、受控提交与状态读取。
- `02-image-to-video.json`：选择原图、上传、设置 `image` 参数并创建图生视频。
- `03-reference-video.json`：从 input 目录选择两个图片文件，组成 `reference_images` 后创建参考视频。
- `04-three-video-tasks.json`：三个独立命名的视频任务，每个任务分别报价和限制金额；并行执行情况由宿主安排。

所有示例默认只报价。图像文件需要替换为你选定的实际文件；每次执行还需要相应空间的权限、有效费率和余额。多任务示例的总费用上限是各节点上限之和，不是一个统一打包价。

单次文件最大256 MiB，拒绝目录、符号链接与读入时变化的源文件。Upload Image 上传的是选定张量编码后的 PNG；Upload File 保留选定源文件的原始字节。传入的媒体类型与数量仍须符合该型号契约。

## 权限和保留期

查询模型使用公开目录；生成需要相应 Key 权限，任务使用 `jobs:read` / `jobs:write`，上传使用 `assets:write`，结果使用 `assets:read`。Key 限额和模型限制由服务端持续执行，节点不绕过它们，也不自动充值。

服务器上的输入、作品和文本保留24小时；重放、查询和下载不延长保留期。已经下载到自己电脑的文件由你保存。上传引用和生成内容是私有数据，分享画布前检查其中手动粘贴的引用和输出；节点不会把 API Key 保存到工作流。

错误提示的 `requestId` 可用于工单核对。`intent_busy` 表示同名记录当前被另一个执行使用，等待它结束后继续原任务。`intent_input_conflict` 表示同名创作参数已经变动，不自动改写旧意图。丢失历史记录时先查询工作空间已有任务，不换名称重复生成来恢复。