# 41｜把 Atlas 生成素材接入 ComfyUI

本教程把 Atlas 返回的素材接入 ComfyUI，重点在云端任务与本地节点之间的类型边界。无需本地模型权重才能调用云端生成，不代表整个后处理图不需要本地算力或其他插件。

## 在正确环境安装

使用你的 ComfyUI 实际 `custom_nodes` 目录与运行它的 Python 环境。不要把某台机器的 `~/Documents/...` 当作所有桌面安装路径。先审阅官方节点代码与依赖，再在获授权环境安装，重启后确认节点列表中出现 AtlasCloud Client 和所需生成/预览节点。

> 在我的 ComfyUI 中接入 Atlas，先确认运行环境、节点版本和现有图，不覆盖其他节点或凭据。先完成导入与参数检查，不点 Run；模型可用、费用与素材范围确认后，只跑一次批准任务。保留 prediction ID，预览节点失败不重新生成；分享图之前去掉密钥和私人素材信息。

## 导入教学图并核对能力

[comfyui-image.json](../examples/workflows/comfyui-image.json) 使用官方公开示例中的三个节点类型：AtlasCloud Client、AtlasCloud Nano Banana Pro Text-to-Image、AtlasCloud Image Preview。图内没有 key，不能直接生成。它依赖特定节点和模型，**不是自动兼容全部 Atlas 模型的通用图**。

导入后逐个检查缺失节点、输入输出插槽和参数。模型不可用时，应重新选择当前支持的模型与对应节点，并验证 schema；不要设置允许废弃模型的开关来掩盖能力缺失。缺失节点也不意味着应该安装名字相似的第三方包。

## 理解 URL 和 IMAGE 类型

生成节点通常返回 image URL 与 prediction ID，Image Preview 节点再取得素材并输出 ComfyUI 的 IMAGE 数据。URL 字符串不能直接当成张量接入所有图像处理节点。连接前看实际插槽类型；需要字幕、拼接或增强时，检查对应节点真的接受何种媒体。

得到 IMAGE 后，可以进入你已安装并验证的本地处理链。新增一个后处理分支之前先保存原始产物和任务 ID，避免图中某个非确定节点被全图重跑时再次花钱。

## 凭据与可分享文件

官方 Client 示例会在 widget 中填写 API key。若本地使用该方式，保存与导出工作流前检查凭据是否被序列化；截图、工作流 JSON 和图像内嵌元数据都可能携带敏感内容。优先采用节点实际支持的安全配置方式，不能凭空声称某环境变量会被它读取。

对外分享前，使用去除 key 的图、公开授权输入与不含客户信息的预览；不能只遮截图中的几位字符，却把完整 key 留在附件 JSON 里。最小样例只需要结构和无效占位，不需要真实令牌。

## 故障从具体节点恢复

生成已成功但预览下载失败：先保存 URL 和 ID，在同账户查询已有结果，单独重做下载/预览；不要直接从生成节点再跑整图。自定义节点缓存行为依版本而定，不能把“输入没变”当成一定不再请求的保证。

交付时既给工作流，也给真实媒体产物和所用节点版本。图可以导入不代表模型当前有权限、参数正确或成品符合要求；这些需要分开验证。本包尚未在你的 ComfyUI 实例进行联调。

## 依据与复现范围

依据：[S3、S12](../SOURCES.md)。本文使用本包约定的教学文件；模型能力与价格以执行时实际目录为准。线上付费步骤未代用户执行，离线验证结果见 [测试报告](../verification/REPORT.md)。通用路径、授权和状态约定见 [执行约定](../common/EXECUTION.md)。
