ComfyPilotComfyPilot
文档 / 开发 / Comfy Router 请求头

Comfy Router 请求头

适用于所有 Comfy Router 模型的请求头与响应头：身份验证、幂等键、请求 ID、错误分桶、重试节奏和支出限额。

开发 headers 更新于 2026-11-12

查看官方原文

Comfy Router 请求头

适用于所有 Comfy Router 模型的请求头与响应头：身份验证、幂等键、请求 ID、错误分桶、重试节奏和支出限额。

每个 Router 模型都使用 POST /v2/models/{provider}/{model}，并各自带有 JSON 请求体。本页介绍各模型共用的请求头；API 参考 列出了已生成的契约。

Comfy SDK（Python 版为 comfy-sdk，TypeScript 版为 @comfyorg/sdk）负责处理身份验证并生成幂等键。它们会按下文所述公开选定的响应元数据。原生 HTTP 客户端必须自行发送和读取这些请求头。

请求标头

X-API-Key string

Comfy API 密钥，格式为 comfyui-...，在你的 Comfy 工作区中创建。它使用你工作区的模型访问权限和额度余额。你也可以通过 Authorization: Bearer comfyui-... 发送它；如果两个标头同时存在，X-API-Key 优先。

Authorization string

Bearer <token>。以 comfyui- 开头的值是 API 密钥。任何其他值都会被当作 Comfy Cloud JWT。

Idempotency-Key string

标识一次逻辑生成。在调用之前生成并存储一个 UUID，然后在重试未发生变化的请求时复用它。该密钥可以在最长 24 小时内重放结果或收集已接受的任务。SDK 会生成密钥，也允许你自行提供（Python 中为 idempotency_key=，TypeScript 中为 idempotencyKey）。关于冲突、过期和不可重放的结果，请参阅重试结果。

Content-Type string

application/json。发送模型的原生 JSON 输入。字段和验证要求因模型而异；请参阅使用 Router API。

If-None-Match string

仅用于 GET /v2/models/{provider}/{model}/openapi.json。发送你从先前的 200 响应中保留的 ETag；当它仍然匹配时，响应是带有相同 ETag 的无响应体 304。将模型的模式缓存在进程的整个生命周期内，并以这种方式重新验证，而不是在每次调用之前重新读取它。

响应头

X-Comfy-Request-Id string required

标识此次 HTTP 请求。联系支持时请提供该值。TypeScript 将其暴露为 requestId；Python 在错误中将其暴露为 request_id。

X-Comfy-Error-Type string

机器可读的错误类别。在 422 响应中请使用此响应头，因为验证响应体包含 detail[] 而没有 error_type。将其与 HTTP 状态码组合，以决定如何处理。在控制流中将未知值视为 internal_error，并保留该值用于诊断。

Idempotent-Replayed boolean

当 Router 直接返回已存储的结果而不是重新运行模型时，此响应头存在且为 true。全新运行时不存在此响应头。 在排队提交路由上，重放的 201 会返回原始请求句柄，而不是再次排队执行。

Retry-After integer

重试之前需要等待的秒数。在 409 / concurrency_limit_exceeded 或 504 / deadline_exceeded 时，请在等待之后使用相同的请求和 key 进行重试。在 429 / rate_limited 时，它告诉你速率限制何时重置。 对于排队请求的状态读取及其 202 结果读取，这是 Router 给出的关于何时值得再次轮询的提示。

X-Committed-Spend-Limit integer

已承诺用于仍在运行的调用的合作伙伴支出上限，单位为美分。处于执行状态的支出闸门可在准入响应及其 429 拒绝响应中返回该值。当闸门未在执行，或由其他控制项拒绝了该请求时，该响应头不存在。

X-Committed-Spend-Current integer

当前已承诺用于进行中调用的美分数。准入响应会包含其自身的调用；429 则不包含被拒绝的调用。与 X-Committed-Spend-Limit 一同发送。

X-Committed-Spend-Remaining integer

距离已承诺支出上限的剩余美分数。当所请求的调用成本超过剩余数量时，它在拒绝响应中也可能为正数。

ETag string

出现在 GET /v2/models/{provider}/{model}/openapi.json。请将其存储起来，并作为 If-None-Match 发送回去，以重新验证缓存的 schema。

Cache-Control string

在 schema 路由上为：private, must-revalidate。将响应保存在私有缓存中，并使用 ETag 重新验证过期的副本。

具有双重含义的状态码

有三种状态码被两个类别共用，而响应头正是区分它们的关键：

状态X-Comfy-Error-Type应对措施
409concurrency_limit_exceeded该 key 的原始调用仍在运行。请等待 Retry-After，然后重新发送相同的 key。
409invalid_input检查该冲突。如果你修改过原始请求，请将其还原。已消耗、不可重放的 key 无法恢复结果；只有在你打算发起一次新的、可能计费的生成时，才使用新的 key。
429concurrency_limit_exceeded同时在途的调用过多，或触达了承诺支出上限（见 X-Committed-Spend-* 响应头）。当你自己的某个调用完成后，该限制会自动解除。
429rate_limited在重试之前等待 Retry-After。
504deadline_exceededRouter 自身的 10 分钟上限。收到 Retry-After 后，重新发送相同的 key 以取回正在运行的生成结果。
504provider_timeout合作伙伴超时。请遵循重试与计费引导；不要把这种情况当作不收费的保证。

下一步

  • 快速开始：发送请求并读取结果。
  • 使用 Comfy Router API：模型发现、schema、错误、重试与计费。
  • API 参考：定义了这些请求头的已生成契约。
  • 限制：Router 目前尚不支持的功能，以及可以改用哪些方案。