Z-Image-ComfyUI API接口怎么用？初探开发能力

Z-Image-ComfyUI API接口怎么用？初探开发能力

你是不是也遇到过这些情况：
在 ComfyUI 网页里反复点击“Queue Prompt”，等图生成完再手动下载，想批量跑50个提示词却得点50次？
想把AI绘图嵌入公司内部设计系统，却发现网页界面没法调用；
或者刚写好一个Python脚本，一运行就报错“Connection refused”——根本连不上后端？

别急。Z-Image-ComfyUI 镜像不只是给你一个漂亮的可视化界面，它默认已启用完整、稳定、无需额外配置的 ComfyUI API 服务。这个API不是隐藏功能，也不是需要手动开启的实验选项，而是从你点击“1键启动.sh”的那一刻起，就已经在后台安静运行着了。

本文不讲概念、不堆术语，只聚焦一件事：手把手带你用最短路径，把 Z-Image-ComfyUI 变成你代码里的一个函数调用。你会学到：
如何确认API服务是否正常运行
怎样用Python发送第一个文生图请求（含完整可运行代码）
如何加载Z-Image-Turbo模型、控制采样步数、设置种子、指定分辨率
怎样复用ComfyUI工作流JSON，避免重复造轮子
常见报错原因与快速排查方法（附真实错误日志对照）

全程基于你已部署好的镜像环境，无需安装新包、无需修改配置文件、无需重启服务——打开Jupyter就能开干。

1. API服务就绪状态验证：三步确认它真的在跑

很多开发者卡在第一步：不确定API有没有起来。其实判断非常简单，不需要查日志、不用敲命令，三步即可闭环验证。

1.1 检查服务监听端口（最直接）

在Jupyter终端中执行：

netstat -tuln | grep :8188

如果看到类似输出，说明ComfyUI API服务已在监听：

tcp6 0 0 :::8188 :::* LISTEN

关键信号：:::8188表示服务正监听所有IPv6地址的8188端口（同时兼容IPv4）。这是ComfyUI默认API端口，Z-Image-ComfyUI镜像未做任何改动。

1.2 访问健康检查接口（最可靠）

直接在浏览器或curl中访问：

http://<你的实例IP>:8188/health

返回{"status":"success"}即表示API核心服务健康。
如果返回404，说明你访问的是WebUI前端地址（如/），请确认URL末尾是/health而非/。

1.3 查看工作流列表（最实用）

访问：

http://<你的实例IP>:8188/object_info

你会看到一个完整的JSON响应，包含所有可用节点名称，例如：

{ "KSampler": { "input": { "required": { "model": ["MODEL"], "positive": ["CONDITIONING"] ... } }, "CLIPTextEncode": { "input": { "required": { "clip": ["CLIP"], "text": ["STRING"] } } }, ... }

这个响应意味着：API不仅活着，而且已加载全部Z-Image专用节点（如ZImageTurboLoader、ZImageEditLoader等），随时可调用。

注意：以上三个地址均使用HTTP协议，无需HTTPS或认证Token。Z-Image-ComfyUI镜像默认关闭身份验证，专为内网开发调试优化。

2. 发送第一个API请求：用Python生成一张图（零依赖）

我们跳过所有中间环节，直接上最简可行代码。这段代码在你镜像的Jupyter中复制粘贴即运行，无需pip install任何包（requests已预装）。

2.1 准备基础请求体（Minimal Workflow）

ComfyUI API不接受自然语言提示词，而是接收一个结构化的工作流JSON。但你完全不必从零写。Z-Image-ComfyUI镜像自带预置工作流，我们只需加载并微调。

在Jupyter中新建Python单元格，运行以下代码：

import requests import json import base64 from PIL import Image from io import BytesIO # 替换为你的实例IP（可在控制台“实例详情”页找到） INSTANCE_IP = "127.0.0.1" # 本地调用用127.0.0.1；跨机器调用填公网IP # 步骤1：读取预置的Z-Image-Turbo工作流（镜像内置） with open("/root/comfyui/workflows/z-image-turbo-text-to-image.json", "r", encoding="utf-8") as f: workflow = json.load(f) # 步骤2：修改提示词和参数（直接改JSON，无需懂节点逻辑） workflow["6"]["inputs"]["text"] = "一只橘猫坐在窗台上，阳光洒落，写实风格，高清细节" workflow["3"]["inputs"]["width"] = 1024 workflow["3"]["inputs"]["height"] = 1024 workflow["3"]["inputs"]["batch_size"] = 1 workflow["7"]["inputs"]["seed"] = 42 # 固定种子便于复现 # 步骤3：发送请求 response = requests.post( f"http://{INSTANCE_IP}:8188/prompt", json={"prompt": workflow}, timeout=120 ) if response.status_code == 200: print(" 请求已提交！任务ID：", response.json().get("prompt_id")) else: print(" 请求失败，状态码：", response.status_code) print("错误信息：", response.text)

运行成功后，你会看到类似输出：
请求已提交！任务ID： 9a3b7c1d-2e4f-5a6b-8c9d-0e1f2a3b4c5d

这表示你的请求已被ComfyUI接收，并进入队列等待执行。

2.2 获取生成结果（同步等待版）

上面只是提交任务，还没拿到图。继续在同一Jupyter中运行：

import time prompt_id = response.json().get("prompt_id") # 轮询获取结果（最大等待120秒） for _ in range(120): history_response = requests.get(f"http://{INSTANCE_IP}:8188/history/{prompt_id}") if history_response.status_code == 200: history_data = history_response.json() if prompt_id in history_data and "outputs" in history_data[prompt_id]: # 找到第一张输出图 image_data = list(history_data[prompt_id]["outputs"].values())[0]["images"][0] filename = image_data["filename"] # 下载图片 image_response = requests.get(f"http://{INSTANCE_IP}:8188/view?filename={filename}&subfolder=&type=output") if image_response.status_code == 200: img = Image.open(BytesIO(image_response.content)) display(img) # Jupyter中直接显示 img.save("z-image-output.png") print(" 图片已保存为 z-image-output.png") break time.sleep(1) else: print(" 超时未获取到结果，请检查ComfyUI日志")

通常3~8秒内即可显示生成图像（Z-Image-Turbo特性：亚秒级推理+快速返回）。

小技巧：/view接口返回的是原始二进制图片流，可直接用PIL处理、转base64嵌入HTML，或上传至云存储。

3. 深度控制：如何精准调用Z-Image三大变体？

Z-Image-ComfyUI镜像预置了三个核心工作流，对应Turbo/ Base/ Edit三种能力。它们不是靠“切换模型按钮”实现，而是通过加载不同节点来区分。API调用时，你只需替换工作流JSON中的模型加载节点即可。

3.1 Turbo版：极速出图（推荐日常开发首选）

路径：/root/comfyui/workflows/z-image-turbo-text-to-image.json
关键节点名：ZImageTurboLoader
特点：固定8 NFEs，延迟<1秒，16G显存友好

调用时确保工作流中存在该节点，且其输出连接至KSampler的model输入。无需额外参数，开箱即快。

3.2 Base版：高质可控（适合微调与精细生成）

路径：/root/comfyui/workflows/z-image-base-text-to-image.json
关键节点名：ZImageBaseLoader
特点：6B全参数，支持30+步采样，中文语义理解更强

若需更高画质，修改KSampler节点的steps字段（如设为35），并确保cfg值在7.0~9.0之间平衡保真与创意。

3.3 Edit版：一句话改图（突破传统img2img限制）

路径：/root/comfyui/workflows/z-image-edit-img-to-img.json
关键节点名：ZImageEditLoader+ZImageEditApply
使用流程：

1. 先上传原图到/input目录（可通过Jupyter文件上传，或用APIhttp://IP:8188/upload/image）
2. 在工作流JSON中设置LoadImage节点的image字段为上传后的文件名
3. 修改ZImageEditApply节点的text字段为你想执行的编辑指令，例如：
   "将背景换成星空，添加银河效果"

实测提示：“把西装换成汉服”、“给建筑添加飞檐斗拱”等文化类指令，Z-Image-Edit识别准确率显著高于通用模型。

4. 工作流复用与定制：别再手写JSON，用好预置资产

你可能会想：“每次都要读JSON、改字段，太麻烦”。其实Z-Image-ComfyUI镜像已为你准备好一套可编程工作流模板体系。

4.1 预置工作流位置与命名规则

所有预置工作流均位于：
/root/comfyui/workflows/

命名清晰反映用途：

• z-image-turbo-text-to-image.json→ 文生图（Turbo）
• z-image-base-text-to-image.json→ 文生图（Base）
• z-image-edit-img-to-img.json→ 图生图（Edit）
• z-image-turbo-controlnet-canny.json→ Turbo + Canny边缘控制
• z-image-base-lora-loader.json→ Base + LoRA加载器（用于风格迁移）

4.2 动态注入参数：一行代码切换模型与提示

与其手动修改JSON，不如用Python封装一个通用函数：

def run_zimage_workflow(workflow_name, prompt_text, width=1024, height=1024, seed=1): with open(f"/root/comfyui/workflows/{workflow_name}", "r", encoding="utf-8") as f: wf = json.load(f) # 自动定位文本编码节点（适配不同工作流结构） for node_id, node in wf.items(): if node.get("class_type") == "CLIPTextEncode": if "inputs" in node and "text" in node["inputs"]: node["inputs"]["text"] = prompt_text # 自动定位尺寸节点（EmptyLatentImage 或 ImageScale） for node_id, node in wf.items(): if node.get("class_type") in ["EmptyLatentImage", "ImageScale"]: if "inputs" in node: node["inputs"]["width"] = width node["inputs"]["height"] = height if "batch_size" in node["inputs"]: node["inputs"]["batch_size"] = 1 # 设置随机种子 for node_id, node in wf.items(): if node.get("class_type") == "KSampler": node["inputs"]["seed"] = seed # 提交 resp = requests.post(f"http://127.0.0.1:8188/prompt", json={"prompt": wf}) return resp.json().get("prompt_id") # 使用示例 pid = run_zimage_workflow( "z-image-turbo-text-to-image.json", "敦煌壁画风格的飞天仙女，飘带飞扬，金碧辉煌", width=896, height=1216, seed=123 ) print("任务已提交，ID：", pid)

这段代码能自动适配任意预置工作流，无需关心节点ID编号，真正实现“一次封装，多处复用”。

5. 排查常见问题：从报错信息反推根源

API调用失败？别急着重装。90%的问题都能通过错误信息快速定位。

终极调试法：在Jupyter中运行tail -f /root/comfyui/logs/comfyui.log，实时查看ComfyUI后端日志，错误源头一目了然。

6. 进阶能力：API不止于生成，还能管理与监控

Z-Image-ComfyUI的API远不止/prompt一个接口。它提供了一套轻量但完整的服务管理能力，让开发者能构建生产级应用。

6.1 查询当前队列状态

# 获取排队中和正在运行的任务 queue_resp = requests.get("http://127.0.0.1:8188/queue") print(queue_resp.json()) # 输出示例：{"queue_running": [...], "queue_pending": [...]}

可用于实现“任务进度条”或“并发数限制”。

6.2 清空队列（防阻塞）

requests.post("http://127.0.0.1:8188/queue", json={"clear": True})

当误提交大量任务导致卡顿时，一键清空，比重启服务快10倍。

6.3 获取系统资源信息（显存/负载）

sys_resp = requests.get("http://127.0.0.1:8188/system_stats") print(sys_resp.json()) # 输出：{"system": {"os": "Linux", "python_version": "..."}, "devices": [{"name": "NVIDIA RTX 4090", "vram_total": 24576, "vram_free": 18240}]}

可用于动态降级策略：当显存低于20%时，自动切换至Turbo模型或降低分辨率。

7. 总结：API是Z-Image-ComfyUI真正的生产力开关

回顾本文，我们没有停留在“点点点”的操作层面，而是真正打开了Z-Image-ComfyUI的工程化大门：

• 验证即用：三步确认API服务就绪，拒绝黑盒猜测；
• 开箱调用：基于预置工作流的Python示例，5分钟内跑通首张图；
• 精准控制：Turbo/ Base/ Edit三大变体的API级调用路径，按需选用；
• 高效复用：封装参数注入逻辑，告别手写JSON；
• 自主排障：建立错误-原因-解法映射表，提升调试效率；
• 生产就绪：队列管理、资源监控等接口，支撑业务集成。

Z-Image-ComfyUI的价值，从来不只是“生成一张好看的图”，而在于它把前沿大模型的能力，封装成了标准HTTP接口 + 可编程工作流 + 预置工程资产三位一体的开发范式。当你能把/prompt当作一个函数调用，把z-image-turbo-text-to-image.json当作一个库文件导入时，你就已经站在了AI应用开发的第一梯队。

下一步，你可以尝试：
→ 把API接入Flask/FastAPI，做一个内部绘图SaaS；
→ 用Airflow调度批量生成任务；
→ 结合企业微信机器人，实现“群里发指令，自动回图”。

路已铺好，现在，轮到你写代码了。

--- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。