> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tapapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ComfyUI

> 用 Tapapi 调用云端模型或衔接 ComfyUI 工作流

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

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

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

## 当前推荐路径

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

## 外部脚本思路

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

```bash theme={null}
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 图片接口失败时通常返回：

```json theme={null}
{
  "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 路由开发方式、鉴权、部署方式、超时控制           |
| 工作流模板           | 商品图、社媒图、局部修复等真实样例                     |
| 图生图 / 多参考图      | 模型白名单、输入图限制、计费和失败策略                   |
| 视频工作流           | 任务轮询、文件转存、长任务超时、成本上限                  |

## 下一步

| 场景     | 文档                                        |
| ------ | ----------------------------------------- |
| 图片生成主线 | [文生图](/image-generation/text-to-image)    |
| 图片保存   | [输出图片保存](/image-generation/output-images) |
| 图生图状态  | [图生图](/image-generation/image-to-image)   |
| 图片参数   | [参数说明](/image-generation/parameters)      |
| 错误与重试  | [错误码与重试](/errors)                         |
| 成本控制   | [成本控制](/production/cost-control)          |

## 官方参考

* [ComfyUI Server Routes](https://docs.comfy.org/development/comfyui-server/comms_routes)