comfyui_o1key/README.md

Comfyui_o1key

通过 api.o1key.cn 调用 AI 模型的 ComfyUI 自定义节点集合。

功能特性

• 🎨 文生图 / 图生图
• 🔄 批量并发生成（最多 1000 张）
• 📐 10 种宽高比
• 🎯 智能分辨率，或手动选择 1K / 2K / 4K
• 🌱 可控随机种子
• 💬 左侧「聊天」面板支持多模型对话，初始默认使用 gpt-6-sol
• 🧠「提示词专家」节点支持多模型文本与多模态输入，新建节点默认使用 gpt-6-sol

项目文档

• 用户安装与使用：当前文件
• 维护者与 AI 协作入口：docs/README.md
• 项目工作约定：AGENTS.md
• 架构与运行边界：docs/architecture.md
• 开发与测试：docs/development.md、docs/testing.md

---

📦 安装

方法一：通过 ComfyUI Manager（推荐）

1. 在 ComfyUI 中打开 Manager
2. 搜索 Comfyui_o1key
3. 点击安装
4. 重启 ComfyUI

方法二：手动安装

cd ComfyUI/custom_nodes
git clone https://git.o1key.com/publisher/comfyui_o1key.git
cd comfyui_o1key
pip install -r requirements.txt

然后重启 ComfyUI。

Windows 用户也可以在 ComfyUI 左侧侧栏打开“更新”面板更新插件；使用前请阅读下方关于本地修改的提示。

---

⚙️ 配置

获取 API 密钥

1. 访问 vip.o1key.com
2. 注册并获取 API 密钥

配置方式

配置 API 密钥（必需）

方法一：ComfyUI 界面配置（推荐）⭐

启动 ComfyUI 后，点击左侧栏的「令牌管理」，填写 API Key、选择网络线路，然后点击「保存并立即生效」。也可以在该窗口测试连接或清除已保存的 Key。

方法二：手动创建配置文件

在插件目录下创建 .config 文件：

O1KEY_API_KEY=你的API密钥

⚠️ 安全提示

.config 文件包含敏感信息，已添加到 .gitignore 中，不会被提交到版本控制。 请妥善保管你的 API 密钥，不要分享给他人。

配置 API 地址（可选）

默认使用 https://api.o1key.cn，通常无需修改。

通常应通过「令牌管理」选择全局网络线路。如需调试自定义地址，可在 .config 中添加：

O1KEY_API_BASE_URL=https://your-api-domain.com
O1KEY_ASYNC_API_BASE_URL=https://your-async-api-domain.com

配置键和线路解析规则见 配置文档。

---

🔄 更新插件

本次发布以当前代码作为新基线，部分旧节点 ID 已移除。包含这些节点的旧工作流可能显示“缺失节点”；更新前请备份工作流。完整清单和处理办法见 发布兼容性决定。

方法一：ComfyUI 侧栏

1. 点击 ComfyUI 左侧侧栏的“更新”图标。
2. 在面板中点击“检查并更新”，确认从 git.o1key.com/publisher/comfyui_o1key 获取后等待结果。
3. 如果提示依赖变化，在 ComfyUI 使用的 Python 环境中安装 requirements.txt。
4. 重启 ComfyUI。

面板只对没有已跟踪文件修改的 Git main 分支执行快进更新。本地代码有修改、历史分叉、网络故障或新版本与未跟踪文件冲突时会给出原因和处理建议，不会强制重置或清理本地文件。已有安装的 origin 地址不会被自动改写。

方法二：手动更新

从 O1Key 发布仓库拉取：

cd ComfyUI/custom_nodes/comfyui_o1key
git fetch https://git.o1key.com/publisher/comfyui_o1key.git main
git merge --ff-only FETCH_HEAD
pip install -r requirements.txt --upgrade

💡 提示： 更新面板不会修改 .config；手动更新前请自行确认工作区没有未保存的代码修改。

---

📚 节点说明

提示词（多功能）

在输入框中用单独一行的 --- 分隔多套提示词，然后选择输出方式：

• 「全部使用」输出全部提示词。
• 「随机抽取n套」按“抽取数量”不重复随机选择，例如准备 10 套后填写 1、3 或 5；抽中的提示词会按原始顺序输出。
• 「指定序号」按从 1 开始的序号选择并按填写顺序输出，支持 1,3,5、中文逗号、空格和 2-4 区间。

控件会随模式动态切换：「随机抽取n套」只显示“抽取数量”，“指定序号”只显示“指定序号”，而“全部使用”会隐藏两者；显示切换不会清空已经填写的值。多套结果仍使用单独一行的 --- 连接，可直接交给支持批量提示词的下游节点。抽取数量超过现有套数、序号越界、重复或格式错误时，节点会在执行前给出明确提示。旧工作流中的节点 ID、提示词和功能位置保持兼容；旧「随机抽取1套」会迁移为「随机抽取n套」并把数量设为 1，旧「随机抽取多套」会保留原数量并迁移到统一模式。新增的“抽取数量”和“指定序号”仍位于原控件之后。

自动红偏校正

「自动红偏校正」的最后一个控件是 ComfyUI 原生 seed，支持生成后随机化。改变 seed 会让节点重新执行；校色算法是确定性的，同一图片和校色参数始终得到相同结果。旧工作流加载时会补入默认 seed 0，保留已保存的灰卡亮度与色度值。

o1key 图片生成 / o1key 保存图像

「o1key 图片生成」的提示词仅在节点内的多行编辑框填写，不显示提示词 STRING 输入端口。旧工作流加载时会移除原有的外部提示词连线，保留节点内已保存的提示词；如原先完全依赖上游字符串，请在面板内补填提示词。

模型列表新增 GPT Image 2.5 Sunburst（最新，高质量）和 GPT Image 2.5 Flare（快速，日常）。两者与 GPT Image 2 使用相同的「智能 / 1K / 2K / 4K」分辨率和「智能、1:1、3:2、2:3、4:3、3:4、16:9、9:16」宽高比；特价、优质、企业线路分别调用模型 ID 的 -sp、-sd 和无后缀版本。下文的 GPT Image 2 参数说明也适用于这两个 GPT Image 2.5 模型。

面板式图片生成节点统一支持 Nano Banana 系列、GPT Image 2 与 Seedream 5.0 Pro。提示词右下角使用带 ✨ 图标的「AI帮写」按钮；独立 Nano Banana 节点不再提供提示词优化按钮。参数区按“生成参数”和“保存设置”分组，采用双列网格布局；提示词独立显示为“画面描述”区域，随机种子按钮仍内嵌在种子输入框右侧。ComfyUI Nodes 1.0 因识别到 seed 输入而自动添加的「生成后控制」与该按钮功能重复，因此会由面板隐藏，不占用节点顶部空间。模型、线路、分辨率、宽高比、生图数量和种子常显；模型专属参数会随模型动态切换：仅 Nano Banana 2 显示「思考等级」和「在线搜索」，GPT Image 2 / 2.5 显示「质量」「背景」和「蒙版」，GPT Image 2 / 2.5 与 Seedream 5.0 Pro 都显示作为 API 参数的「输出格式」。在线搜索默认为「关闭」，关闭时不发送相关参数；选择「打开」时，请求体顶层发送 google_search: true。这些参数不收进高级设置弹层；切换模型只隐藏不适用参数，不会清空已选值。分辨率新增默认值「智能」；选择它时，Nano Banana、GPT Image 和 Seedream 的上游请求都不发送 size，由模型决定输出尺寸。选择具体档位时，GPT Image 2 会把分辨率与宽高比映射为具体像素尺寸；宽高比选择「智能」时按正方形映射为 1024x1024 / 2048x2048 / 2880x2880。背景支持自动、透明和不透明，输出格式支持 JPEG、PNG 和 WebP；新建 GPT 设置默认 PNG，已有工作流保留保存的格式，其中透明背景只能搭配 PNG 或 WebP。所有模型每次请求最多使用 10 张参考图。GPT Image 新选项支持每条提示词生成 1–8 张，旧工作流中的 9 张仍可执行；其余模型保持 1 / 2 / 4 / 9。GPT Image 2.5 的质量另支持「超高 / 最高」，分别发送 xhigh / max；GPT Image 2 仅支持原有四档。提示词支持用独占一行的 --- 分隔多条内容；所有模型和执行入口都会按“提示词数量 × 生图数量”生成任务，任务排列为同一提示词的所选张数在前、下一条提示词随后，单次最多 1000 个任务。任务会按受控并发分批执行，GPT Image 与 Seedream 请求中的 n 固定为 1。模型线路在面板中显示为「特价（便宜）/ 优质（小贵）/ 企业（贵）」，工作流内部仍保存兼容值「畅速 / 直连 / 专线」；思考等级默认为「低」，显示为「低（耗时低，智力低）/ 高（耗时高，智力高）」；缩放图片显示为「不缩放（无大图）/ 智能缩放（有大图）」。带标签的下拉参数在菜单收起后也会显示当前选项的标签。

Seedream 5.0 Pro 位于 GPT Image 2 下方，支持「智能 / 1K / 2K」分辨率与「智能、1:1、4:3、3:4、16:9、9:16、3:2、2:3、21:9」宽高比；具体档位会转换为接口要求的精确像素尺寸。参考图通过当前全局线路的 /v1/o1key/uploads 上传为临时 HTTPS URL，再按原顺序传入 images。输出格式实际发送 output_format=png/jpeg；水印不提供界面开关，固定发送 watermark=false。

Seedream 5.0 Pro 的每张普通参考图需满足火山引擎当前限制：文件不超过 30MB，宽和高均大于 14px，宽高比在 1:16～16:1 之间，总像素不超过 6000×6000（3600 万）。「图层拆分」使用独立下限：单张待拆图片的总像素必须在 512×512～6000×6000 之间，文件大小和宽高比限制不变。面板会在本地文件上传前检查，后端也会在临时上传或生图请求前再次校验；不符合时会显示当前尺寸及对应限制，不会消耗生图请求。

Seedream 还提供「图层拆分」。开启后必须且只能上传 1 张待拆图片，生图数量固定为 1，批量出图关闭，输出固定为 PNG，分辨率改为「智能 / 1K / 1.5K / 2K」；提示词可以留空，也可以描述希望拆出的主体、背景或文字。一次任务返回 1 张底图和最多 16 个透明图层。从面板点击「开始生成」时会自动建立两条保存分支：IMAGE 连接的「o1key 保存图像」只接收底图，LAYERS 连接的「o1key 保存图层」接收其余透明图层；整批结果只保存一次，不会重复请求或重复落盘。普通模式默认只显示 IMAGE 输出端；选择 Seedream 并开启「图层拆分」后显示「图层」和「图层遮罩」，不常用的「图层信息」默认隐藏。旧工作流如果已经连接「图层信息」，该端口仍会显示并保持连线。IMAGE 是可直接预览、保存或继续处理的主图（拆分模式下为底图）；「图层」是按层输出、尺寸可能不同的透明 RGB 图层列表，对应透明度由「图层遮罩」提供。

通过「o1key 图片生成」面板上传的参考图、素材图、目标图和蒙版直接写入 ComfyUI 当前配置的 input 根目录，不再新建 o1key_uploads 子目录。参考图、素材图和目标图轨道末尾始终保留「添加参考图/素材图/目标图」卡片；可以点击选择文件，也可以从系统文件管理器把图片直接拖到该卡片或整条轨道完成上传。外部文件松开后会立即清除整条轨道和上传卡片的拖放状态，不会在参考图区残留绿色背景或外框。参考图和目标图区均提供「画布取图」：先执行裁剪、缩放、预览或保存节点，再点击该按钮即可从当前画布已有的图片结果中选择一张；面板会读取所选结果并按普通上传重新写入 input，随后自动加入当前图片清单，无需手动下载再上传。若文件名已存在，复用 ComfyUI 的原生命名规则追加自然数字（例如 商品.jpg、商品 (1).jpg、商品 (2).jpg），不会覆盖已有文件；面板保存服务器返回的实际文件名。旧工作流中已经保存的 input/o1key_uploads/... 图片引用仍可继续读取，请勿移动或删除这些历史文件。

「批量出图」面向通用图像生产，不限定服装行业，也可用于商品替换、包装设计、空间改造、妆发迁移、材质替换、角色设计和视觉风格应用等场景。关闭时，参考图、任务数量和执行方式都保持原有行为。开启后，界面把图片分为两个职责明确的区域：

• 「素材图」提供需要引用的对象、元素、风格、材质或结构。
• 「目标图」是素材内容最终要应用到的图片。

批量模式提供三种执行方式：

• 「整组素材 → 多个目标」会把当前所有素材图作为一组，并依次与每张目标图组成一次请求。例如 3 张素材图、10 张目标图、每组生图数为 1 时，共生成 10 张；该模式每组最多 9 张素材图，为当前目标图保留第 10 个参考位。
• 「全匹配（素材 × 目标）」会把每张素材图分别与每张目标图组合。例如 10 张素材图和 10 张目标图会展开为 100 个请求。每个请求只携带当前素材图和当前目标图，不会把 20 张图片一起发送给模型。
• 「单图批量（每张素材独立）」不需要目标图。将多张模特图上传到素材区后，每张图都会作为该次请求的唯一参考图，适合批量换动作、换表情或做其他无需额外对照图的修改。选中后目标图区会隐藏，已保存的目标图清单不参与该批次。

批量素材和目标清单的上限均为 50 张。「整组素材 → 多个目标」由于会把整组素材放入同一次请求，素材区仍限 9 张，但目标图可上传 50 张；「全匹配」和「单图批量」的素材区可上传 50 张。最终展开后仍受单次 1000 个任务上限约束。

素材图和目标图使用两条独立的横向大卡轨道，缩略图为 102 × 102，上传和「画布取图」收在各自标题行；普通模式沿用同一套大卡样式，只显示参考图轨道。轨道通过独立的最大 256 × 256 WebP 预览加载图片，只有打开全屏大图时才读取原始文件；缩略图不会覆盖原图，AI帮写和生成 API 始终使用上传到 input 的原始图片。标题行同时显示当前图片数量，素材图区说明会随模式切换：「整组素材 → 多个目标」显示“整组参与”，「全匹配（素材 × 目标）」显示“匹配时每张独立”，「单图批量」显示“每张独立生成”。

上传后，每张缩略图左下角显示它在实际模型请求中的图号，例如「图2」或「图4」。缩略图不再显示独立的排序手柄；鼠标左键按住图片即可直接拖动排序。拖动时原卡片会明显缩小、变暗并显示“移动中”，当前轨道同步高亮，目标位置通过粗插入线和卡片位移展示。缩略图获得焦点后，也可用 Alt + ←/→ 前后微调，或用 Alt + Home/End 移到首尾。素材图和目标图分别排序，调整后图号、工作流清单、AI帮写和实际生成请求会立即使用新顺序；仍有图片上传时会暂时锁定当前图片组的排序。第1张参考图会标明其主图/色彩基准语义。单击已上传的缩略图会在当前 ComfyUI 画布上打开与左侧「资产」一致的全屏大图预览；拖动操作结束后不会误触大图。可点击遮罩或关闭按钮，也可按 Esc 关闭，多图使用左右按钮或方向键切换。缩略图悬停时不显示额外文字标签。批量界面不显示额外的“描述示例”板块。

每张参考图、素材图和目标图的右下角都有「替换」按钮：选择一张本地图片后，新图会留在原位置，其他图片和顺序不变；验证或上传失败时保留旧图。左上角的编辑按钮继续用于裁剪和标记。点击后可按「自由 / 原图 / 1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 16:9 / 9:16」快速裁剪，也可用「遮罩」画笔涂出半透明红色关注区域，或用彩色「画笔」自由圈选和批注物品。「箭头」从按下位置开始、以松开位置作为箭头尖端，用于精确指定需要关注或修改的画面位置，并支持颜色与粗细调整。「贴图」可从本地上传一张上层图片：拖动图片移动，拖动四角等比缩放，拖动顶部圆点旋转，按住 Shift 时以 15° 吸附；还可调节透明度、替换、移除或重置贴图。编辑器支持撤销和重做；应用后会把裁剪、贴图与标记合成为一张新的 PNG，通过 ComfyUI 原生上传接口写入 input 并替换当前清单项，原文件不会被覆盖。箭头、画笔和视觉遮罩位于贴图之上，确保指示内容不会被遮挡。贴图的控制框不会进入输出；贴图源文件只在当前弹窗中临时读取，不会写入工作流。「遮罩」是直接合成进图片的视觉标记，不会创建或修改 ComfyUI MASK 数据，也不会自动填入 GPT Image 的「蒙版」参数。

配对模式中的「生图数量」显示为「每组生图数」；单图批量中显示为「每图生成数」。界面会按“有效提示词数 × 配对或素材数 × 每组/每图生图数”显示任务总数，并受单次 1000 个任务上限约束。Nano Banana 与 GPT Image 2、面板后台任务与标准 ComfyUI 执行使用相同的展开顺序；单个失败槽位只重试原来的参考图组合。批量出图暂不支持 GPT 蒙版编辑，开启前需先移除蒙版。

提示词框右下角提供“魔法棒图标 + AI帮写”的文字按钮。填写提示词并按需上传参考图后，点击按钮会使用 gpt-5.6-sol 和高思考分析当前文字及全部参考图；处理期间会显示“AI帮写中…”，完成后再将一份可直接用于生图的提示词回填到原输入框。优化以视觉元素与具体对象的绑定为第一优先级；图生图场景会进一步明确必须保持不变的内容和需要改变的目标。API Key 只在服务端读取，不会传给浏览器或写入工作流。

Nano Banana 与 GPT Image 2 的最终 UTF-8 JSON 请求体（含 Base64）都按 18 MiB 本地安全上限检查。新建 GPT 设置的「缩放图片」默认为「智能缩放」，已有工作流保留保存的选择；「不缩放」时超限会直接拒绝。智能缩放使用 Lanczos 从原图等比缩小占用最大的参考图，直到请求体满足上限。GPT 的首张参考图与蒙版会绑定缩放，确保尺寸继续一致。界面会明确提示「可能发生像素偏移」。

生成任务完成后，如果任务查询中的大体积 Base64 因网络中断、内容截断或图片校验失败而不可用，节点会使用原 task_id 自动重新获取结果，不会重新提交生成任务或重复扣费；返回图片 URL 时则使用独立的下载与完整性校验重试。正常任务查询保持静默；仅在任务查询发生 HTTP 错误、读取中断、长度不一致、JSON 无效或响应任务 ID 不匹配时，ComfyUI 终端才打印不含响应正文、Base64、密钥或结果 URL 的「任务查询传输追踪」，显示请求与响应 task_id、HTTP 版本与状态、服务端 Content-Length、实际接收字节数、内容/传输编码、长度检查和 JSON 解析结果。未压缩且声明长度的响应必须字节数完全一致，否则会明确标记 length_check=mismatch 并重试同一任务；压缩响应会标记 skipped-compressed，避免把解压后字节数与压缩态长度错误比较。

以下错误封装作用于整个「o1key 图片生成」节点，与当前选择的模型无关；GPT Image 2、Nano Banana 2、Nano Banana Pro 及该节点支持的其他模型都会使用相同规则。上游返回 content rejected: the image was flagged as unsafe by the content safety system 时显示“内容被拒绝：该图像被内容安全系统标记为不安全。”；返回 Your request was rejected by the safety system 时显示“您的请求已被安全系统拒绝”；返回 insufficient balance 时显示“上游额度不足！”；返回 Image generation returned empty response 时显示“图片生成过程中被内容审查机制拒绝！”；返回 The provided prompt is considered unsafe and it cannot be used to generate content 时显示“提供的提示被认为是不安全的，不能用于生成内容。”。标准工作流执行会直接替换 ComfyUI 持久错误浮层中的通用说明，不再另外弹出一条短暂、重复的错误通知。这些错误不再直接展示上游英文内容。

每次生成前会优先复用已连接且尚无结果的「o1key 保存图像」节点；没有空白结果节点时才自动创建一个。节点内「开始生成」、顶部「运行」和选中输出节点后的蓝色执行按钮遵循同一规则；标准 ComfyUI 执行只把本次结果交给选中的空白结果节点，不会覆盖同一生成节点下已有结果的保存节点。保存节点现在只负责接收、写入和展示图片，不再包含命名、格式或路径参数；这些参数统一由上游「o1key 图片生成」节点提供。后台生成结果先放入 ComfyUI temp，只有「o1key 保存图像」节点会把它们写入设定的永久保存目录（默认为 output）。

每次点击面板内「开始生成」都会独立提交一个批次，按钮始终可继续提交，不会因为已有任务运行而失去并发。批次的排队、运行、完成、失败和取消状态统一显示在 ComfyUI 右上角原生「任务队列」中；队列项右侧使用图层图标和数字显示该批次计划生成的图片总数。最近 200 条终态任务的安全摘要会写入 ComfyUI 用户目录下的 o1key/image_job_history.json，因此重启 ComfyUI 后仍会重新出现在右侧历史；单条删除和清空历史会同步更新该文件。摘要只包含批次/节点 ID、状态、计数、时间、错误摘要和安全的 ComfyUI 图片描述，不保存提示词、参考图内容、Base64、API 密钥或签名 URL。可从对应队列项取消单个批次，也可使用队列的批量取消或清理功能。生成过程中切换到其他工作流不会把完成结果发给已经离开画布的旧节点；返回原工作流时，当前「o1key 保存图像」节点会按批次 ID 自动接回进度或最终图片。浏览器刷新后也会查询服务端保留的批次状态；若图片已经写入 output，恢复过程直接复用同一结果，不会再次保存一份。结果图下载不设置独立的并发上限，已就绪任务会直接并发下载；实际同时下载数由当时活跃的生成任务数自然决定。生成节点本身不再显示任务状态或切换为取消按钮。若付费请求已被上游接受，取消不能保证撤回已经发生的上游计费。

「o1key 图片生成」的通用「命名规则」默认显示为「自定义」，并显示「文件名前缀」，沿用 ComfyUI 的前缀和五位计数器样式。选择「和主图一致」后使用第1张参考图的文件名主干，批次内或重复保存遇到同名时依次追加自然数字；纯文生图没有主图文件名时回退为 o1key。选择「自然数字」后使用 1、2、3… 连续命名。「保存位置」留空时直接写入 ComfyUI 当前配置的 output 根目录；填写相对路径时写入 output 内的对应子文件夹；填写完整绝对路径（例如 D:/图片/项目A）时可保存到任意可写磁盘目录。相对路径不接受 .. 越界，D:图片 这类不完整盘符路径也会被拒绝。所有命名规则都会检查目标文件且绝不覆盖；外部目录的结果会在 ComfyUI temp 中保留一份预览副本，不影响节点和批量结果预览。

本地「格式」只在 Banana 模型下显示，默认「原始」，也可选 PNG / JPEG / WebP；它控制保存时是否转换容器。Nano Banana 不接收 output_format，所以模型返回 PNG 就保留 PNG，返回 JPEG 就保留 JPEG，除非这里显式转换。GPT Image 2 不使用这个本地参数，而使用独立的 API「输出格式」；可选 JPEG / PNG / WebP，默认 JPEG，实际请求值为小写 jpeg。Seedream 同样使用 API「输出格式」，只提供 PNG / JPEG，并按所选值保存上游原始容器。透明背景仍只支持 GPT Image 的 PNG 或 WebP。保存节点写入可恢复工作流时遵循 ComfyUI 原生图片元数据约定：PNG 保存 prompt 和 workflow 文本块；由于 ComfyUI 不从 JPEG 读取工作流且 JPEG EXIF 容量有限，带工作流的 JPEG 来源或 JPEG 保存选项会自动落盘为 PNG。将该 PNG 拖回或载入 ComfyUI 即可恢复工作流；关闭 ComfyUI 全局元数据写入时仍按所选 JPEG 保存，但不会附带工作流。

生成参数使用适合中英文与数字混排的字体、字距和垂直居中的下拉箭头；模型列表会显示用途说明。新建节点默认尺寸为 560 × 1035，提示词框约显示 5 行内容；开启批量出图或切换到参数较多的 GPT Image 2 时，节点会增加高度以容纳额外控件。Nano Banana 2 提供 1K / 2K / 4K 分辨率，不再提供 512。批次提交后，「o1key 保存图像」会立即按实际任务展开顺序排列固定图片槽位；每张图片完整下载到 ComfyUI temp 后会立即显示在对应槽位，无需等待整批完成，全部成功后再切回 ComfyUI 原生图片预览并按设置永久保存。拖动保存节点改变宽度或高度时，原生单图和多图预览会同步使用全部可用区域重新排布并等比缩放，不裁切图片，也不保留旧节点尺寸产生的固定空白。若部分图片失败，成功图仍保留在原序号位置，失败槽位显示独立重试按钮；不同失败槽位可以连续点击并行重试，每个槽位只重新提交自己的原提示词和原素材组合，先完成的重试不会结束或覆盖仍在运行的其他槽位。槽位状态和安全的结果描述会随工作流保存、刷新恢复，且槽位视图与原生预览不会同时叠加。原生下载按钮会替换为白底黑色的重新生成图标；在全成功的多图结果中先选中目标图片，再点击该图标，即可沿用当前参数和新的随机种子只生成 1 张新图，且不会修改生成面板中原来选择的生图数量。生成过程中仍保留顶部细进度条，不显示百分比文案。

旧工作流加载时，会把保存节点原有的「文件名前缀 / 格式 / 保存位置 / 命名规则」迁移到相连的「o1key 图片生成」节点；保存节点自身的旧控件值随后清除。迁移不会改动节点 ID 或图像连线。

Nano Banana / Nano Banana 批量跑图

两个独立 Nano Banana 节点与「o1key 图片生成」复用同一套异步请求、18 MiB 请求体检查、任务查询恢复和结果下载校验。两个节点使用手写提示词，不再提供提示词优化按钮。

「缩放图片」默认为「不缩放」：最终 UTF-8 JSON 请求体超过 18 MiB 时会在付费请求前拒绝；选择「智能缩放」后会使用 Lanczos 等比缩小占用最大的参考图，直至请求体满足限制。两个 Nano Banana 节点均不提供色彩纠正。

任务查询发生 HTTP 错误、读取中断、长度不一致或 JSON 无效时，会继续查询原 task_id，不会重新提交付费生成请求；任务返回的内联 Base64 不完整时同样重取原任务，结果 URL 下载失败或图片不完整时使用独立下载重试。日志不会打印上游结果 URL、完整 Base64 或授权信息。

Nano Banana 支持文生图、图生图、1 / 2 / 4 / 9 张生成和最多 14 张动态参考图；Nano Banana 批量跑图 从最多 5 个图片路径建立同名、同序号、全匹配或不配对任务，并可附加最多 9 张固定参考图。两个节点仅提供 1K / 2K / 4K，已移除 512；旧工作流中的 512 / 512px 会自动迁移为 1K。模型线路与统一节点一样显示为「特价 / 优质 / 企业」，但内部仍保存「畅速 / 直连 / 专线」以兼容已有工作流和请求映射。两个节点的种子、缩放等控件均直接显示。批量节点按「缩放图片 → 图片输出格式 → 图片质量 → 图片保存命名规则 → 图片保存路径 → seed」排列最后六项参数；JPEG 或 WebP 的图片质量为 1–100 的整数，默认 95。旧工作流会恢复字符串图片质量、补齐「不缩放」默认值、移除旧批量节点的「不纠正 / 智能纠正」值，并保留原值迁移到新顺序。

「Nano Banana 批量跑图」已移除「图片随机抽取」。所有已填写的图片路径都按所选配对模式参与组图；旧工作流保存的随机抽取值和连线会在加载时清除。若填写多个图片路径，请选择「相同文件名」「同序号」或「全匹配」。

GPT Image / GPT Image 批量跑图

两个 GPT Image 节点的模型线路显示为「特价 / 优质 / 企业」，内部继续保存兼容值「畅速 / 直连 / 专线」。GPT Image 2.5 的畅速、直连、专线分别使用 -sp、-sd 和无后缀请求模型名。两个节点的新建默认模型均为 GPT Image 2.5 Sunburst；选择 GPT Image 2.5 系列时，「质量」会额外提供「超高」和「最高」，分别向接口传入 xhigh 和 max；切回 GPT Image 2 后恢复为标准质量选项。两个节点都不再提供提示词优化、色彩纠正或内容审查强度。

单图节点的「背景」位于「输出格式」下方；批量节点的「背景」位于「图片输出格式」下方。两个节点的「seed」都位于「缩放图片」下方，缩放默认值为「智能缩放」。单图节点使用与统一图片生成节点相同的 18 MiB 请求体策略；批量节点也会在请求体超限时智能等比缩小参考图。蒙版会与第一张参考图同步缩放。旧工作流会自动移除批量节点已删除的色彩纠正和内容审查值，并迁移背景、缩放和 seed 的控件顺序。

两个 GPT Image 节点的「背景」都显示为「自动 / 透明 / 不透明」，工作流和 API 仍使用 auto / transparent / opaque；透明背景不能搭配 JPEG。GPT Image 批量节点的额外参考图输入端会接续文件夹路径数量编号，例如 1 个路径时从「参考图2」开始，并随路径数量动态调整。seed、输出格式、命名规则、保存路径、缩放和背景参数均直接显示；批量任务默认全并发运行，不提供并发数或图片随机抽取控件。

任务结果查询只重试同一 task_id，不会重新提交生成请求。查询响应读取中断、长度不一致、无效 JSON、内联图片不完整，以及结果图片的临时 HTTP 错误、传输中断或解码失败，都会使用有限退避重试；日志不会输出签名下载地址、完整 Base64 或授权信息。

Omni Flash 视频生成

「Omni Flash 视频生成」沿用 Seedance 全能生成视频的普通节点方式：选择文生视频、参考图视频、首尾帧或视频编辑模式，填写提示词，通过 IMAGE/VIDEO 输入点连接对应素材，再点击「开始生成」将当前节点加入 ComfyUI 原生队列。输入端随生成模式切换：文生视频无媒体输入，参考图视频显示参考图片，首尾帧显示首帧和尾帧图片，视频编辑显示源视频及可选参考图片；切换到不使用某种素材的模式会断开该素材的连线。参考图模式至少连接 1 张图片；首尾帧模式必须连接首帧，尾帧可选，只连接首帧时以单张图生视频方式提交，连接两张时按首尾帧转场提交；编辑模式连接不超过 20 MB 的 MP4/MOV 源视频，可另接最多 5 张参考图。普通生成固定使用 omni_flash_10s，模型参数由后端传入，节点不显示模型控件；分辨率支持 720p 或 1080p，宽高比支持横屏或竖屏。编辑模式自动使用专用模型，并在创建任务时发送 X-No-Watermark: video 请求头。

令牌沿用「o1key 图片生成」的设置：在侧边栏「令牌管理」保存 O1Key API Key，节点执行时从插件配置读取，不写入工作流。素材上传和视频生成都使用所选 O1Key 网络线路。执行期间节点会提交、轮询并下载视频；任务查询兼容嵌套状态、进度和结果地址，未识别的中间状态会继续轮询，接口错误码会显示对应的中文原因。接口返回的 progress 会直接同步到节点进度条，例如 50 显示为一半；视频保存完成后进度条到 100。提交、查询及下载接口的文本响应体会打印到 ComfyUI 终端，令牌、临时链接和大段媒体数据会被遮蔽。普通生成模式固定调用 omni_flash_10s，模型由后端传入且节点不显示模型参数；视频编辑模式仍使用专用编辑模型。完成后返回可连接后续节点的原生 VIDEO，节点本身不显示视频预览。视频保存在 ComfyUI 的 output/omni_flash 目录；无需额外结果节点或后台任务接口。

Grok Video / Grok Video Edit

Grok Video 使用 /grok/v1/videos/generations，支持 grok-imagine-video 和 grok-imagine-video-1.5 两个模型，以及文生、图生和多参考素材三种模式。生成时长为 1～15 秒，分辨率支持 480p / 720p / 1080p；其中 1080p 仅用于 grok-imagine-video-1.5 的文生或图生，多参考素材最高 720p。图生模式只连接「图片1」，提示词可以留空；参考模式必须填写提示词，可连接最多 7 张图片，并使用最多 3 个参考音频。参考音频既可来自 AUDIO 端口，也可在「参考音色ID（逗号分隔）」中填写 voice_id，两类输入合计不超过 3 个。

Grok Video Edit 使用独立的编辑和延长接口，并共用同一任务查询端点。两种操作都可选择上述两个模型。编辑输入视频不能超过 8.7 秒，输出保持原时长和宽高比且最高 720p；延长时长为 2～10 秒，最终总时长等于输入时长加延长时长。节点会先校验模式、模型、素材数量、分辨率和时长，再上传临时素材并提交任务；完成后立即下载结果并输出 ComfyUI 原生 VIDEO。

视频裁剪

「视频裁剪」只需点击节点内的「上传视频」选择文件，也可连接上游 VIDEO；上传后的内部文件路径会随工作流保存，但不显示为用户参数。视频加载后可直接预览并拖动时间轴。固定时长大于 0 时，绿色选区会保持该长度并可整体拖动；固定时长为 0 时使用开始、结束时间自由裁剪。

Google Gemini

Google Gemini 模型节点，支持更多模型选择。

Seedance 视频生成

「Seedance 全能生成视频」和「Seedance 多模态参考生视频」会统一封装生成阶段的版权审查错误。上游响应包含 The request failed because the output video may be related to copyright restriction、其复数 restrictions 形式，或带有 OutputVideoSensitiveContentDetected.PolicyViolation: 前缀时，节点错误框显示“输出视频触发版权审查被拒绝生成！”，不再直接展示英文响应。

「Seedance 创建素材」接受照片、视频或音频三种输入，并沿用已发布的 SeedanceElementCreate 节点 ID。旧工作流中的“真人照片 / 真人视频 / 真人音频”端口会在加载时自动迁移，未经过浏览器加载的 API 工作流也继续兼容旧参数名。

「Seedance 多模态参考生视频」的参考图片、参考视频和参考音频端口会在连接后按需增加，不再一次铺开全部端口。图片、视频和音频素材 ID 也采用渐进填写：每组始终保留一个空输入框，填入当前项后才显示下一项。旧工作流中的编号端口、已填写素材 ID 和“真人素材ID”名称会自动迁移。

「Seedance 全能生成视频」保留“素材创建模式”参数，默认“关闭”：隐藏全部素材 ID，并按线路自动创建连接的素材；改为“打开”后，才显示下方的素材 ID 单行输入并使用已有 ID。输入行与「Seedance 多模态参考生视频」一样按编号渐进展开：每类先显示一行，填写后展开下一空行。切回关闭不会清除已填 ID；旧工作流的“自动创建 / 手动”和三类聚合 ID 会自动迁移。输入端随生成模式动态增删：多模态仅显示参考图片、视频、音频，并随连接渐进增加端口；首尾帧仅显示首帧图片、尾帧图片。切换模式会断开被移除端口的连线，切回后需重新连接。

「Seedance 多模态参考生视频」和「Seedance 全能生成视频」的模型线路均支持“海外”和“国内”；“海外”沿用原“海外HC”线路，旧工作流会自动迁移。国内线路会按所选主模型调用对应的 Seedance 2.0、fast、mini 或 2.5 国内模型，新建节点默认使用“国内”。

两个单节点及「Seedance 全能生成视频（批量）」共用模型能力限制：Seedance 2.0 系列支持 4～15 秒，Seedance 2.5 支持 4～30 秒；2.5 支持 480p / 720p / 1080p / 4k，并允许最多 30 个图片类、10 个视频类和 10 个音频类参考内容。多模态节点中的直接媒体与对应素材 ID 共用这组数量额度。fast 和 mini 模型仍只支持 480p / 720p。宽高比统一为智能、16:9 / 9:16 / 4:3 / 3:4 / 1:1 / 21:9。

「Seedance 全能生成视频」现与「o1key 视频生成」共用参数标准、素材限制、content 请求体构造和 Seedance 提交/轮询/下载客户端。生成模式简化为“多模态”和“首尾帧”：新节点默认多模态，无参考素材而仅填写提示词时自动按文生视频提交；首尾帧需要一个首帧素材，尾帧可选，没有尾帧时自动按仅首帧提交。“素材创建模式”默认关闭，此时上传连接素材并按线路创建 HC/Doubao Asset；打开后显示编号式素材 ID 输入并跳过上传，使用已有图片、视频和音频素材 ID，其中首尾帧模式填写一个或两个图片素材 ID。连接的图片会按 PNG 上传且单项不超过 30MB，宽高各为 300～6000px、比例为 0.4～2.5；视频仅支持 MP4/MOV，单项不超过 512MB，并额外要求总像素为 407,696～8,295,044；音频支持 WAV/MP3/M4A/AAC/FLAC/OGG，单项不超过 100MB。所有素材在上传和创建素材前完成校验，准备阶段最多并发处理三个素材并保持输入顺序。seed 保留在普通参数区最下方；“联网搜索”和“返回末帧图片”暂时隐藏，不提供用户设置，但保留旧工作流中的值及参数顺序。联网搜索仅为旧工作流保留，当前统一的 content 请求不会发送该参数。旧的四种生成模式、参数顺序和“海外HC”线路会在加载时自动迁移。

「o1key 视频生成」是面板式统一入口，新建节点默认使用“多模态参考”，并支持 Seedance 2.0、2.0 Fast、2.0 Mini 和 2.5，以及文生视频、首帧、首尾帧和多模态参考四种模式。切换到其他工作流再返回时，节点会恢复离开前的生成模式、提示词、参数、素材 ID 和已上传图片/视频/音频。直接上传的首帧、尾帧和多模态参考图片遵循火山方舟官方输入限制：宽、高各为 300～6000px，宽高比为 0.4～2.5；官方没有为参考图片另设总像素下限。参考视频除相同的宽高及比例限制外，总像素必须在 407,696～8,295,044 之间。校验在上传前提示，并在后端素材快照阶段再次强制执行；浏览器无法读取受支持的 MOV/H.265 元数据时会交由后端 PyAV 校验，不会仅因浏览器解码能力不足而误拒绝。使用需要参考素材的 Seedance 模式时，还可选择“素材创建”：默认“自动创建”并显示对应的上传区；多模态区右上角使用一个统一的“上传”按钮，可一次选择图片、视频和音频并自动分类。自动模式会复用「Seedance 创建素材」的统一服务，海外线路创建 HC 素材，国内线路创建 Doubao 素材，素材进入可用状态后才提交视频。相同内容会复用已验证可用的素材 ID，视频提交失败后的重新生成也会直接复用本次已创建的 ID。选择“手动”后上传区会切换为素材 ID 输入，首帧模式需要一个图片素材 ID，首尾帧模式需要两个图片素材 ID，多模态模式可填写图片、视频和音频素材 ID。手动 ID 可通过「Seedance 创建素材」节点提前获取。面板沿用「o1key 图片生成」的视觉语言：提示词卡片、自定义下拉、素材缩略图、状态条和主操作按钮保持一致；视频参数仍采用单列布局，切换生成模式或素材创建方式时，只展示当前模式需要的素材区并同步调整节点高度。提示词右下角的「✨ AI帮写」使用独立视频默认预设，根据当前模式、时长、宽高比和音频开关组织连续的动作与镜头；首帧、尾帧及参考图按当前角色和顺序参与视觉分析，参考视频和音频只提供数量与顺序语义，不会把媒体内容上传给帮写模型。参考视频缩略图直接使用浏览器原生视频解码显示首个可用画面，不生成额外封面文件；若当前浏览器无法解码该格式，才回退为播放图标和文件名。上传图片后可通过缩略图左上角按钮打开与图片生成节点相同的编辑器；多张参考图片、视频和音频都可拖拽调整提交顺序，编号角标会同步更新。它不使用 ComfyUI 原生任务队列：每点一次「开始生成」都会创建并连线原生「保存视频」节点，开启「返回尾帧」时再同时创建原生「保存图像」节点，然后提交一个可并行运行的后台任务。插件不限制独立视频任务的并行数量；每个任务的素材准备阶段最多同时处理三个素材，避免瞬间冲击上传和素材接口。生成按钮只在本次上传或提交期间短暂禁用。上游服务仍可能依据账户配额或服务状态限流。

该统一视频节点会为当前及后续新增的视频模型共用友好审查提示。错误中出现 copyright 时优先按版权限制处理，并结合 audio / video / content / real 字段或关键词分别提示输出音频、输出视频、提示词或真人内容触发限制；例如 The request failed because the output audio may be related to copyright restrictions 会显示“请求失败，输出视频中音频触发版权限制！”。其他安全、内容审查或策略拒绝错误也会按同样对象给出中文提示；普通网络和参数错误仍保留原诊断信息。

首帧和尾帧图片的“上传”按钮旁提供“画布取图”。它直接复用图片生成节点的画布结果发现、选择器和 /view 读取逻辑；选中后仍通过 ComfyUI 原生上传写入 input，并执行相同的 Seedance 图片限制校验。多模态参考区只保留统一的“上传”按钮，以减少重复入口。

点击“开始生成”会从生成节点的 VIDEO 输出自动创建并连接原生“保存视频”节点，不再创建“o1key 视频结果”节点；打开“返回尾帧”时，还会从 LAST_FRAME 输出同时创建并连接原生“保存图像”节点。生成进度和错误显示在生成节点状态栏，完成后结果直接出现在对应的原生保存节点中。旧工作流中的“o1key 视频结果”仍可加载，但已标记为兼容节点，新任务不会再创建它。参考文件先通过 ComfyUI 原生上传接口写入 input，任务启动时再复制到批次隔离的临时目录。工作流和任务历史只保存安全的文件描述，不保存 API Key、Base64、绝对输入路径或签名临时 URL。

MiniMax H3 / H3 Max 视频生成

通过 New API 网关调用 MiniMax-H3 或 MiniMax-H3-MAX。两者均支持文生视频、 首帧、尾帧和首尾帧生视频；MiniMax-H3 另外支持多图片、多视频、多音频参考素材生成。 节点完成后会立即下载临时 CDN 视频并输出 ComfyUI 原生 VIDEO，可连接内置保存视频节点。

• MiniMax-H3：768P / 2K，4～15 秒，支持最多 9 张参考图、3 个参考视频、3 个参考音频，参考素材合计最多 12 个
• MiniMax-H3-MAX：480P / 768P，5～15 秒，不支持参考素材模式
• 查询任务按接口建议每 10 秒轮询；短暂的 unknown 状态按排队中处理，总等待上限为 2000 秒
• seed 为原生生成参数，支持固定、递增、递减和每次随机化
• 文生视频比例：21:9、16:9、4:3、1:1、3:4、9:16
• 首帧、尾帧、首尾帧模式自动使用 adaptive
• 参考素材：最多 9 张图片、3 个视频、3 段音频；默认 adaptive，也可指定具体输出比例
• API Token 从插件配置读取，不会保存在工作流中

---

📝 更新日志

查看 CHANGELOG.md 了解详细的版本更新记录。

---

📄 许可证

本项目采用 Apache License 2.0 许可证。

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开始开发前请阅读 AGENTS.md 和 维护者文档。

---

⚠️ 开发者注意事项

维护者：发布流程与镜像同步

代码先提交并推送到 GitHub，再同步到 Gitee 镜像，国内用户通过 Gitee 拉取以解决网络问题。

首次配置（仅需一次）：

git remote add gitee https://gitee.com/resonLzy/comfyui_o1key.git

每次发布：

git push origin main    # 先更新 GitHub
git push gitee main     # 再同步到 Gitee 镜像

文件编码要求

所有文本文件必须使用 UTF-8 编码（无 BOM）！

如果出现中文乱码，请确认编辑器按 UTF-8（无 BOM）读取和保存文件。

---

📮 联系方式

• GitHub: @lizhongyi1209
• 项目地址: https://git.o1key.com/publisher/comfyui_o1key

---

当前版本：v1.10.1