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 为是时，使用 next_cursor。 参数 响应

​

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

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

​

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

通过规范化模型 ID 同步运行合作伙伴模型。 运行模型并在同一响应中接收其已完成的结果。 参数 请求体 application/json — RouterModelInput（必填） 合作伙伴模型的原生 JSON 输入。在没有 model_provider 时，或在 strict_mode=true 时，原样转发给提供商；在 strict_mode=true 下，请求体必须已经是备用提供商自己的真实 schema，而不是此模型的原生 schema（参见 strict_mode）。当 model_provider 选择了备用提供商且 strict_mode=false（默认值）时，请求体会在发送前被转换为该提供商的真实 schema；任何无法精确表达的原生字段都会被丢弃，并通过响应的 X-Comfy-Router-Dropped-Params 头予以披露，绝不会静默处理。 响应

​

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 输入，与此模型的同步路由所接受的请求体完全相同。在接纳该次运行之前，会依据模型自身的输入 schema 进行校验，因此模型会拒绝的请求体在这里会得到 422，而不是变成几分钟后才失败的已排队请求。 响应

​

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；有关响应头行为，请参阅响应头。

​

错误分类桶

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

​

请求级分类桶

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

​

传输级分类桶

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

​

响应头

​

结果资产

模型可以返回资产 URL、内联字节，或两者兼有。下面的提供商会将已选择的资产复制到 Comfy 存储上并替换其 URL。此行为取决于模型；没有任何请求头能选择它。 这些有效期从 URL 签名时开始计算，而不是从你打开它时开始。缓存或重放的 URL 可能剩余时间更少；重放不会为其续期。请及时下载资产。只有每一行中列出的资产会被复制：byteplus/seedream-* 和 byteplus/seededit-* 图像不在 BytePlus 视频行的覆盖范围内。 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 可读取每个模型的字段。该操作的 requestBody 描述了输入验证；在已编写的情况下，其 200 响应描述了输出形状和媒体类型。当 x-comfy-input-schema-authored 为否时，Router 接受任意 JSON 对象，而不进行特定于模型的预验证。提供商依赖项仍然适用。输出架构描述的是结果；Router 不会依据它们验证提供商返回的载荷。未编写的输出可能使用 */* 而非 application/json；在解码之前，请检查响应的内容类型。

​

模式

​

RouterChargesOnPolicyRejection

内容策略拒绝是否会对此模型收费。将未知值视为可能收费。 类型：string

​

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 和 400。两者共用一个响应体形状，而不是成功信封加错误信封，因为二者表达的是同一个陈述，即取消操作发现了什么；而一个必须按状态码解析不同类型的客户端，从这种拆分中得不到任何好处。 字段

​

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，因此客户端永远不需要自行拼接队列 URL。 字段

​

RouterValidationErrorContext

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

​

RouterValidationErrorDetail

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

​

RouterValidationErrorInput

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

​

RouterValidationErrorResponse

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