Comfy Router API 参考

Comfy Router 的规范路由，以模型 ID 寻址。 基础 URL：https://api.comfy.org 以下每个端点都需要身份验证。请发送 X-API-Key: <api-key> 或 Authorization: Bearer <jwt>。 Comfy API 密钥也可以作为 Bearer token 发送。当同时提供两个凭证请求头时，以 X-API-Key 为准。有关 API 密钥与 JWT 的区别，请参阅身份验证请求头；有关访问要求，请参阅快速入门。

​

端点

​

GET /v2/models

列出 Comfy Router 可运行的模型。 列出可用的模型 ID 和计费信息。当 has_more 为 true 时使用 next_cursor。 参数 响应

​

GET /v2/models/{provider}/{model}

按规范模型 ID 读取单个合作伙伴模型的目录条目。 无需列出完整目录即可读取单个模型的详情。 参数 响应

​

POST /v2/models/{provider}/{model}

按规范模型 ID 同步运行合作伙伴模型。 运行模型，并在同一个响应中收到已完成的结果。 参数 请求体 application/json —— RouterModelInput（必填） 合作伙伴模型的原生 JSON 输入。没有 model_provider 时，请求会在模型的默认提供商上执行原生分发，此请求体即为模型自身的原生 schema，原样转发（strict_mode 在此处无意义，不会改变任何内容）。当 model_provider 选择替代提供商且 strict_mode=false（默认值）时，请求体会在发送前被转换为该提供商的实际 schema：任何无法精确表达的原生字段都会被丢弃，并通过响应的 X-Comfy-Router-Dropped-Params 头披露，绝不会静默丢弃。当 model_provider 选择替代提供商且 strict_mode=true 时，不会执行任何转换：请求体必须已经是该替代提供商自身的实际 schema，而不是此模型的原生 schema（参见 strict_mode），并会被原样转发。请求体自身的字段也决定 Router 在支持多种操作的模型上运行哪种操作：对于可编辑的图像模型，包含输入图像会将其从文生图切换为图生图（编辑）操作，该操作可能按其自身的费率计费；对于 Seedance 视频模型，content[].role 决定操作（首帧图像选择图生视频，参考图像或片段选择参考生视频）。在原生分发下，Seedance 计费依据 content 中的媒体类型而非角色：含任何视频输入的请求按视频转视频计费，否则含任何图像的按图生视频计费，否则按文生视频计费，但由 draft_task 项产生的最终渲染会按其渲染的 Draft 的操作计费；有些模型对文生视频和图生视频收取相同费率。当 model_provider 选择替代提供商时，每种带条件的操作可能会按该提供商自身的费率计费。 响应

​

POST /v2/models/{provider}/{model}/estimate

在运行模型调用之前估算其价格，而无需实际运行。 返回一份以美元计的预检估算，说明在此模型上运行该请求体会产生多少费用，其定价依据与实际运行计费所依据的同一份费率卡片。这是估算值，而非最终费用：你实际支付的是工作区用量与账单记录中的结算费用。请求体会先按模型的输入 schema 进行校验，与默认运行（不带 strict_mode、不带 reject_unknown_fields）的校验方式一致，因此不符合模型 schema 的请求体在这里与在运行时一样返回 422；不会向提供商派发任何请求，也不会产生任何费用。该结果并非价格锁定：它按 pricing_as_of 时点生效的费率计价，而实际运行按其计费定价时生效的费率收费。在该功能逐步推出期间，该路由会返回 403，并带有 error_type: not_enabled。 参数 请求体 application/json：RouterModelInput（必填） 合作伙伴模型的原生 JSON 输入，与此模型的同步路由所接受的请求体完全相同。它会按模型自身的输入 schema 进行校验，与默认运行的校验方式一致（此路由不接受 strict_mode 或 reject_unknown_fields），并由其自身字段（输出数量、输入图像所选的操作）决定计价内容。 响应

​

GET /v2/models/{provider}/{model}/openapi.json

以 OpenAPI 文档的形式读取单个合作伙伴模型的输入和输出 Schema。 以独立的 OpenAPI 文档形式读取单个模型的输入和输出 Schema。 参数 响应

​

POST /v2/models/{provider}/{model}/requests

将合作伙伴模型运行提交到队列并立即返回。 Comfy Router 的排队交付模式。请求体与 POST /v2/models/{provider}/{model} 为此模型接受的合作伙伴原生 JSON 输入相同：一个请求体形状、一个按模型定义的 schema、两种交付模式。但此路由不会为结果保持连接。它接纳运行，用句柄返回 201，调用方稍后通过下面三个读取操作收集结果。 参数 请求体 application/json：RouterModelInput（必填） 合作伙伴模型的原生 JSON 输入，与同步路由为此模型接受的请求体相同；它选择操作，并以相同方式计量：请求体自身的字段决定 Router 在支持多个操作的模型上运行哪个操作（输入图像会将可编辑图像模型切换为图生图，图生图可能按其自身费率计量；Seedance 首帧图像选择图生视频，参考图像或片段选择参考生视频）。在原生调度时，Seedance 请求按 content 中的媒体类型计费，而不是按角色计费：任何视频输入都按视频转视频计费，否则任何图像都按图生视频计费，再否则按文生视频计费；例外情况是，来自 draft_task 项的最终渲染按其渲染的 Draft 的操作计费，某些模型对文生视频和图生视频收取相同费率；当 model_provider 选择备用提供商时，每个带条件的操作可能按该提供商自己的费率计量。相同的提供商选择约定在调度时适用：不提供 model_provider，或提供 model_provider 且 strict_mode=false（默认值）时，请求体是模型的原生文档，并在接纳运行之前根据模型自己的输入 schema 进行验证，因此模型会拒绝的请求体在这里会返回 422，而不是一个几分钟后才失败的排队请求；非严格的备用提供商请求体还会在调度时被转换为该提供商的真实 schema。使用 strict_mode=true 时，请求体必须已经是备用提供商自己的 schema，并会原样转发：跳过原生 schema 验证，与同步路由完全一样（参见 model_provider 和 strict_mode）。 响应

​

GET /v2/models/{provider}/{model}/requests/{request_id}

收集一次已提交请求的结果。 收集端点。对于已成功完成的请求，它返回合作伙伴模型自身的原生输出，与同步路由针对同一模型、同一输入在 200 中返回的内容逐字节相同，因此两种交付方式产生同一种结果形状，调用方无需再写一套解析器即可在两者之间切换。 参数 响应

​

PUT /v2/models/{provider}/{model}/requests/{request_id}/cancel

请求取消某个已提交的请求。 请求 Comfy 停止一个尚未完成的请求。这只是一次请求，并不构成保证，而 202 正是在表达这一点：CANCELLATION_REQUESTED 表示该请求已被接受，并不表示运行已经停止。已经发往合作伙伴处执行的运行仍可能照常完成；而合作伙伴侧完成的生成会被计费，无论是否有人取用其结果。因此，需要知道实际发生了什么情况的调用方，应在此之后读取状态端点。在那里，已生效的取消会表现为 COMPLETED，并和其他所有终态结果一样携带一个 error_type。 参数 响应

​

GET /v2/models/{provider}/{model}/requests/{request_id}/status

读取单个已提交请求的队列状态。 轮询端点。它只返回请求的当前状态，从不返回结果，因此客户端可以持续观察一次长时间生成，而不必在每次轮询时传输其输出：当该端点返回 COMPLETED 时，再从下面的读取中一次性获取结果。 参数 响应 此处描述较为简短。模型选择、验证、重试和计费请参阅使用 Comfy Router API，Header 行为请参阅 Headers。

​

错误分类桶

Router 错误的机器可读类别，同时也会在 X-Comfy-Error-Type 响应头中发送。

​

请求级分类桶

针对 Router 已接受但随后无法完成的请求抛出。

​

传输级分类桶

由 Router 自身抛出，发生在调用模型之前或调用过程之中。

​

响应头

​

预检费用预估

POST /v2/models/{provider}/{model}/estimate 可以在不运行请求体的情况下为其定价，而排队提交（POST /v2/models/{provider}/{model}/requests）会在其 201 响应中返回与 estimate 相同的 RouterCostEstimate。两者都按 Comfy 对该次运行计费所依据的费率卡片来定价。两者返回的任何数值都是预估，并非最终收费：工作区的用量与账单记录中的已结算费用才是最终结果。使用你自己的提供商密钥运行不会由 Comfy 计费（见下文）。在预估功能逐步开放期间，该路由会返回 403 以及 error_type: not_enabled，并且提交响应会省略 estimate。目录中仍然不包含任何价格。 在读取任何金额之前，先读取 source。缺失的数值绝不意味着免费。 unknown 预估的 reason 是以下之一：

• not_quotable：Router 无法在调用运行之前为其定价，因为它按提供商回传的、而请求体未给出界限的数量计费，或者请求体无法按其发送时的状态定价。任何无法识别的 reason 都按 not_quotable 处理。
• unpriced_model：费率卡片未为此请求定价。
• byok（仅排队提交）：该次运行使用你自己的提供商密钥，因此 Comfy 不收取任何费用。
• pricing_unavailable（仅排队提交）：请求被接收时无法读取费率卡片。提交仍会被接受，运行照常计费。

Router 在运行之前尚无法定价的模型列在没有预检预估的模型中。未列在该处的模型对于特定请求体仍可能返回 unknown，因此请对每个预估都读取 source。 预估在以下情况下会采用保守失败策略：

• 当某个数值需要费率卡片，而该卡片未加载或已过期时，/estimate 会返回 503，而不是给出猜测。排队提交绝不会因为其预估而被拒绝；它改为携带 source: unknown 和 reason: pricing_unavailable。对于根本不能在运行前定价的调用（not_quotable），或使用你自己的提供商密钥的排队提交（byok），应答时不会读取费率卡片，因此该 200 并不说明卡片是否是最新的。
• /estimate 会像默认运行那样，依据模型自身的输入 schema 校验请求体，因此未通过模型 schema 的请求体会得到与该次运行相同的 422，以及相同的 detail[] 结构。此时不会进行任何定价或派发。
• 排队提交的幂等重放（Idempotent-Replayed: true）会省略 estimate，因为原始报价不会被存储。

预估的局限性。200 返回的数值并不承诺该次运行会被接受，也不承诺实际收费正好是这个数值：

• /estimate 不接受 strict_mode 或 reject_unknown_fields，因此它只检查模型的原生契约：一个在备用提供商自身的 schema 下会被 strict_mode=true 的运行接受的请求体，在这里可能得到 422；而一个会被 reject_unknown_fields=true 的运行拒绝的未声明顶层字段，在这里却会被定价。
• pricing_as_of 是费率卡片被获取的时间（若未读取任何卡片，则为预估被应答的时间）。它不是价格锁定：运行按其被计价时生效的费率收费。
• /estimate 报价的是 model_provider 指定的那一段，或原生提供商。它不接受 fallback_provider 或 strict_mode 参数。同步运行如果其 fallback 重试落到另一个提供商上，就按该提供商的费率收费，而预估并未对该费率报价；运行响应中的 X-Comfy-Router-Fallback-Provider 表明发生了这种情况。排队提交没有 fallback，因此其 estimate 报价的就是实际运行的那一段。
• 对于同一个请求体，在 model_provider 这一段上，或对于会在同级操作上运行的请求体，/estimate 与排队提交的 estimate 可能为略微不同的文档定价。提交的 estimate 按运行实际发送的文档定价。
• /estimate 始终报价平台费用。使用你自己的提供商密钥运行不会由 Comfy 计费，但 /estimate 不会检测到这一点，仍会返回一个数值；只有排队提交会返回 reason: byok。
• 美元金额由未取整的美分换算而来，最多保留 8 位小数，可计费的不足一美分的 amount 绝不会显示为 0。credits 为 round(amount × 211, 2)，与 X-Comfy-Credits-Used 对收费所用的换算相同，因此对于极小的非零价格，credits 可能取整为 0；在这一点重要时，请以 amount 或 amount_cents 而非 credits 来做预算。该响应头仍是运行事后的数值；余额位于 Comfy 平台上。

​

结果资产

模型可以返回资产 URL、内联字节，或两者兼有。下面的提供商会将已选择的资产复制到 Comfy 存储上并替换其 URL。此行为取决于模型；没有任何请求头能选择它。 这些有效期从 URL 签名时开始计算，而不是从你打开它时开始。缓存或重放的 URL 可能剩余时间更少；重放不会为其续期。请及时下载资产。只有每一行中列出的资产会被复制：byteplus/seedream-* 和 byteplus/seededit-* 图像不在 BytePlus 视频行的覆盖范围内。 复制只由模型的原生提供商执行。由替代提供商提供服务的运行（model_provider 指定了某个替代提供商，或原生运行的回退重试落到了替代提供商上，并通过 X-Comfy-Router-Fallback-Provider 披露）会返回该提供商自己的 URL，这些 URL 遵循提供商的过期时间，不会被复制。model_provider 取值 default、comfy 和 comfyui 时不指定替代提供商，因此这些运行属于原生运行并按上述方式复制；model_provider 运行的回退重试落回原生提供商时也同样如此。 Veo（veo/*）有单独的存储路径。 在 response.videos[] 中，读取其中存在的成员：bytesBase64Encoded 内联包含视频片段，而当环境配置为提供商直接写入 Comfy 存储时，gcsUri 包含一个 Comfy 签名的 HTTPS 链接。该链接自响应起 24 小时内有效。后一种情况是直接写入资产而非复制，因此 Veo 不在重新托管表中。 其他模型返回提供商资产引用或内联字节。提供商 URL 遵循提供商的过期时间，这可能比上述有效期短得多，且 Router 契约未对此作出规定。 复制是按资产尽力而为的。如果某个复制失败，该条目会保留其提供商引用；响应可以同时包含 Comfy 和提供商 URL，且没有明确的按资产复制状态字段。生成仍会成功并计费。不要根据一个成功重新托管的资产来推断每个 URL 的有效期。 结果是否由 Comfy 托管也决定了已完成的调用以后是否仍能从其 Idempotency-Key 记录中重放；上面的 Idempotency-Key 参数说明了无法重放时重试会得到怎样的回应。

​

各模型的输入和输出架构

每个模型的字段可通过 GET /v2/models/{provider}/{model}/openapi.json 读取。该调用需要 API 密钥。对于每个具有已编写架构的模型，同一文档也在本站点上公开发布，无需密钥，地址为 /router-schemas/{provider}/{model}.json。该副本是上次文档更新时生成的快照，因此当两者不一致时，以端点为准。该操作的 requestBody 描述输入验证；在已编写的情况下，其 200 响应描述输出形状和媒体类型。当 x-comfy-input-schema-authored 为 false 时，Router 接受任意 JSON 对象，而不进行特定于模型的预验证。提供商依赖项仍然适用。输出架构描述的是结果；Router 不会依据它们验证提供商返回的载荷。未编写的输出可能使用 */* 而非 application/json；在解码之前，请检查响应的内容类型。

​

Schemas

​

RouterChargesOnPolicyRejection

内容政策拒绝是否会对该模型计费。请将未知值视为可能计费。 类型：string

​

RouterCostEstimate

对本次调用费用的预估值，以美元计，在派发之前依据该次运行实际计费所用的同一费率卡片定价。它不是最终收费：你实际支付的是工作区用量与账单记录中的结算费用。运行结束后返回的 X-Comfy-Credits-Used 是一个取整的事后数值，不是收据。source 说明该数字的可信程度：exact 带有 amount；estimated 带有 min_amount 和 max_amount，不带 amount；unknown 两者都不带，并带有一个 reason。绝不要把缺失的 amount 理解为免费。这不是价格锁定：请参见 pricing_as_of。 字段

​

RouterErrorResponse

用于认证、访问、模型查找、配额以及提供商传输失败的错误响应体。 字段

​

RouterErrorType

机器可读的 Router 错误类别，同时也会在 X-Comfy-Error-Type 标头中发送。 类型：string

​

RouterModelBilling

调用模型之前需要检查的计费行为。它不包含价格或用量信息。 字段

​

RouterModelDetail

单个 Comfy Router 模型的逐模型详细信息：目录列表为该模型报告的全部内容，外加只有单模型路由才会携带的逐模型字段。 组合了 RouterModelListEntry、RouterModelDetailFields。 类型：object

​

RouterModelDetailFields

模型详情端点返回的可选字段。 字段

​

RouterModelId

用于 POST /v2/models/{provider}/{model} 的模型 ID。 类型：string。模型 ID，例如 anthropic/claude-opus-4-6，最多 193 个字符。

​

RouterModelInput

模型输入对象。请阅读已选择模型的 OpenAPI 文档，了解字段与验证规则。 类型：object

​

RouterModelInputSchemaDocument

一份独立描述单个模型输入与输出的 OpenAPI 文档。 类型：object

​

RouterModelListEntry

模型的 ID 与计费信息。 字段

​

RouterModelListResponse

Router 模型目录的一页。 字段

​

RouterModelOutput

模型结果对象。请阅读已选择模型的输出 Schema，以了解其确切的形状。 类型：object

​

RouterModelSegment

{provider}/{model} 模型 ID 中的模型部分。 类型：string，字母数字组成的 slug，例如 claude-opus-4-6，最多 128 个字符

​

RouterPageCursor

一个不透明的目录游标。请原样传回，作为 cursor。 类型：string，即作为 next_cursor 返回的不透明游标，1–512 个字符

​

RouterProviderSegment

{provider}/{model} 模型 ID 中表示提供商的部分。 类型：string。字母数字 slug，例如 anthropic，最多 64 个字符

​

RouterQueueCancelResponse

针对描述本路由已处理请求的两种状态（202 和 409）的取消询问所作的应答。两者共用同一种响应体形状，而不是一个成功信封加一个错误信封，因为两者陈述的是同一件事：取消操作发现了什么；而且，如果客户端必须按状态码解析不同的类型，这种拆分并不能带来任何好处。 字段

​

RouterQueueCancelStatus

取消请求所得到的结果，针对的是该路由实际已处理请求的两种结果。两者都会同步反映到 HTTP 状态码上，因此客户端可以任选其一进行分支判断。 类型：string

​

RouterQueuePosition

在响应生成的那一刻，队列中排在此请求前面的请求有多少个。零表示此请求位于队首。 类型：integer — 至少为 0

​

RouterQueueRequestId

排队中的一个 Router 请求的标识符：调用方通过该句柄进行轮询、取消并收集结果。 类型：string — pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$，uuid，最多 36 个字符

​

RouterQueueStatus

已执行的 Router 请求的状态。它恰好有三个取值，并且与 RouterErrorType 不同，它是一个封闭的 enum，因为这两个 schema 是刻意朝相反方向封闭的。RouterErrorType 对失败进行分类，其集合预期会不断扩展，因此，如果一个已生成的客户端硬性拒绝某个无法识别的分类，那么它恰恰会在已经出问题的时候失败得最严重。而这一类型描述的是生命周期，而日后新增第四个状态的生命周期，无论它是否被声明为 enum，对每一个针对它编写的轮询循环而言都是破坏性变更，因此它被声明为 enum，并且这一约束被写在客户端能够看到的地方。 类型：string

​

RouterQueueStatusFields

RouterQueueStatusResponse 中不属于 URL 块的那一半：一个排队中请求的身份、它当前的状态，以及在该状态为终端状态且运行未成功时，说明失败原因所属的粗粒度分类桶。 字段

​

RouterQueueStatusResponse

一个已执行请求的当前状态，由提交时返回的相同三个 URL 组合而成。 组合了 RouterQueueUrls、RouterQueueStatusFields。 类型：object

​

RouterQueueSubmitFields

RouterQueueSubmitResponse 中除 URL 区块之外的另一半：新请求的身份，以及它被接纳那一刻的状态。 字段

​

RouterQueueSubmitResponse

当运行被接纳进入队列时返回的句柄：包含请求的身份与状态，并组合了用于访问其生命周期其余部分的三个 URL。 组合了 RouterQueueUrls、RouterQueueSubmitFields。 类型：object

​

RouterQueueUrls

这三条 URL 指向一个已入队请求剩余的生命周期，凡是携带有效句柄的响应都会返回它们，因此客户端无需自行拼接队列 URL。 字段

​

RouterValidationErrorContext

提供商提供的关于未通过验证的规则的详情。 类型：object

​

RouterValidationErrorDetail

一个字段级验证失败。 字段

​

RouterValidationErrorInput

提供商包含该值时，被拒绝的输入值。

​

RouterValidationErrorResponse

422 验证错误的响应体。读取 X-Comfy-Error-Type 以获取其类别。 字段