POST /v2/models/{provider}/{model}，并各自带有 JSON 请求体。本页介绍各模型共用的请求头；API 参考 列出了已生成的契约。
Comfy SDK（Python 版为 comfy-sdk，TypeScript 版为 @comfyorg/sdk）负责处理身份验证并生成幂等键。它们会按下文所述公开选定的响应元数据。原生 HTTP 客户端必须自行发送和读取这些请求头。
请求标头
string
Comfy API 密钥，格式为
comfyui-...，在你的 Comfy 工作区中创建。它使用你工作区的模型访问权限和额度余额。你也可以通过 Authorization: Bearer comfyui-... 发送它；如果两个标头同时存在，X-API-Key 优先。string
Bearer <token>。以 comfyui- 开头的值是 API 密钥。任何其他值都会被当作 Comfy Cloud JWT。string
标识一次逻辑生成。在调用之前生成并存储一个 UUID，然后在重试未发生变化的请求时复用它。该密钥可以在最长 24 小时内重放结果或收集已接受的任务。SDK 会生成密钥，也允许你自行提供（Python 中为
idempotency_key=，TypeScript 中为 idempotencyKey）。关于冲突、过期和不可重放的结果，请参阅重试结果。string
application/json。发送模型的原生 JSON 输入。字段和验证要求因模型而异；请参阅使用 Router API。string
仅用于
GET /v2/models/{provider}/{model}/openapi.json。发送你从先前的 200 响应中保留的 ETag；当它仍然匹配时，响应是带有相同 ETag 的无响应体 304。将模型的模式缓存在进程的整个生命周期内，并以这种方式重新验证，而不是在每次调用之前重新读取它。响应头
字符串
必填
标识此次 HTTP 请求。联系支持时请提供该值。TypeScript 将其暴露为
requestId；Python 在错误中将其暴露为 request_id。字符串
机器可读的错误类别。在
422 响应中请使用此响应头，因为验证响应体包含 detail[] 而没有 error_type。将其与 HTTP 状态码组合，以决定如何处理。在控制流中将未知值视为 internal_error，并保留该值用于诊断。布尔
当 Router 直接返回已存储的结果而不是重新运行模型时，此响应头存在且为
true。全新运行时不存在此响应头。整数
重试之前需要等待的秒数。在
409 / concurrency_limit_exceeded 或 504 / deadline_exceeded 时，请在等待之后使用相同的请求和 key 进行重试。在 429 / rate_limited 时，它告诉你速率限制何时重置。整数
已承诺用于仍在运行的调用的合作伙伴支出上限，单位为美分。处于执行状态的支出闸门可在准入响应及其
429 拒绝响应中返回该值。当闸门未在执行，或由其他控制项拒绝了该请求时，该响应头不存在。整数
当前已承诺用于进行中调用的美分数。准入响应会包含其自身的调用；
429 则不包含被拒绝的调用。与 X-Committed-Spend-Limit 一同发送。整数
距离已承诺支出上限的剩余美分数。当所请求的调用成本超过剩余数量时，它在拒绝响应中也可能为正数。
字符串
出现在
GET /v2/models/{provider}/{model}/openapi.json。请将其存储起来，并作为 If-None-Match 发送回去，以重新验证缓存的 schema。字符串
在 schema 路由上为：
private, must-revalidate。将响应保存在私有缓存中，并使用 ETag 重新验证过期的副本。具有双重含义的状态码
有三种状态码被两个类别共用，而响应头正是区分它们的关键：下一步
- 快速开始：发送请求并读取结果。
- 使用 Comfy Router API：模型发现、schema、错误、重试与计费。
- API 参考：定义了这些请求头的已生成契约。
- 限制：Router 目前尚不支持的功能，以及可以改用哪些方案。