ComfyUI

ComfyUI 不是 OpenAI-compatible Provider 配置型工具，不能像 Dify、Open WebUI 那样只填 Base URL 和 Key 就完成接入。Tapapi 当前更适合作为 ComfyUI 工作流外侧的云端图片 API：由外部脚本或业务系统调用 Tapapi，再把结果交给 ComfyUI 后续处理。

当前没有 Tapapi 官方 ComfyUI 节点，也不要把 /v1/tapapi/images/advanced、image_urls、多参考图或 webhook 当成已开放的 ComfyUI 生产接口。需要这些能力时等正式白名单和教程。

不要把 Tapapi API Key 写进公开 ComfyUI workflow、第三方节点配置、截图或共享模板里。多人共用 ComfyUI 时，建议由业务后端统一代理 Tapapi，而不是把 Key 分发到每台机器。

当前推荐路径

路径	说明
外部脚本	脚本调用 Tapapi 生图，下载图片，再交给 ComfyUI
业务系统编排	业务后端负责队列、扣费、转存和 ComfyUI 任务调度
自定义节点	后续可以开发，但当前文档不把它当成已验证路径

外部脚本思路

业务系统或脚本准备 prompt、模型名和业务 task_id。
调用 Tapapi POST /v1/images/generations。
读取 data[0].url 或 data[0].b64_json，并记录 X-Oneapi-Request-Id。
下载并转存图片到本地或对象存储。
把图片路径作为输入交给 ComfyUI 工作流继续处理。

curl https://tapapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "a clean ecommerce product photo of a white ceramic mug",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

返回结果处理

情况	建议
`data[0].url`	下载图片，保存成本地文件或对象存储，再传给 ComfyUI
`data[0].b64_json`	解码为图片文件，再传给 ComfyUI
`data=[]`	当作失败处理，记录 `request_id`、模型和 prompt 摘要
`metadata.tapapi_partial`	按实际返回张数处理，不要假设全部成功
URL 下载失败	优先重试下载和转存，不要立刻重新生成图片

生产流程建议把 ComfyUI 输入图片保存成你自己的稳定路径，例如本地共享目录、S3、R2、OSS、COS 或业务文件服务。不要让 ComfyUI 长期依赖上游临时 URL。

错误和排障

OpenAI-compatible 图片接口失败时通常返回：

{
  "error": {
    "message": "...",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}

脚本或后端至少记录：

字段	用途
`task_id`	你的业务任务 ID
`request_id`	Tapapi 响应头 `X-Oneapi-Request-Id`
`model`	实际调用模型
`status_code`	HTTP 状态码
`error.type` / `error.code` / `error.message`	失败排查
`output_path`	转存后的图片路径
`comfy_workflow_id`	后续 ComfyUI 工作流任务 ID

常见处理：

状态	建议
400	修 prompt、size、response_format 或模型字段
401 / 403	检查 Tapapi Key、余额、权限和模型可见性
429	降低并发，等待后有限重试
临时 5xx / 网络超时	重试 1-2 次，仍失败则进入人工检查
504 / 524	先查业务状态和账单，再决定是否补跑

不建议现在公开承诺的内容

内容	原因
Tapapi 官方 ComfyUI 节点	还未构建和验证
图生图 / 多参考图	当前是预留能力，不能把 `image_urls` 写进生产请求
webhook 回调	图片主线不是 Tapapi 托管任务轮询 / webhook
随机第三方节点	API Key 安全和字段兼容性不可控
视频工作流	视频 API 受控开放，未确认模型、价格和权限前不要放进 ComfyUI 自动流程

后续可做

方向	需要验证
自定义 ComfyUI 节点	Key 存储、错误提示、图片下载、模型列表、`request_id` 记录
Server Route 扩展	ComfyUI 路由开发方式、鉴权、部署方式、超时控制
工作流模板	商品图、社媒图、局部修复等真实样例
图生图 / 多参考图	模型白名单、输入图限制、计费和失败策略
视频工作流	任务轮询、文件转存、长任务超时、成本上限

下一步

场景	文档
图片生成主线	文生图
图片保存	输出图片保存
图生图状态	图生图
图片参数	参数说明
错误与重试	错误码与重试
成本控制	成本控制

官方参考

ComfyUI Server Routes

SDK 与语言

常用工具

当前推荐路径

外部脚本思路

返回结果处理

错误和排障

不建议现在公开承诺的内容

后续可做

下一步

官方参考

​当前推荐路径

​外部脚本思路

​返回结果处理

​错误和排障

​不建议现在公开承诺的内容

​后续可做

​下一步

​官方参考

当前推荐路径

外部脚本思路

返回结果处理

错误和排障

不建议现在公开承诺的内容

后续可做

下一步

官方参考