Skip to main content
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 输入，原样转发给提供商。 响应

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

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

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

将合作伙伴模型运行任务提交到队列并立即返回。 Comfy Router 的 QUEUED 投递模式。请求体与该模型的 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 停止一个尚未完成的请求。这是一个请求（REQUEST），而非保证，202 正是这个含义：CANCELLATION_REQUESTED 表示该请求已被接受，并不代表运行已经停止。已经在合作伙伴处开始执行的运行仍可能照常完成，而合作伙伴生成一旦完成就会计费，无论是否有人取走结果。因此，若调用方需要了解实际发生的情况，应在之后读取状态端点，在那里，已生效的取消会表现为 COMPLETED，并像其他所有终端结果一样携带一个 error_type。 参数 响应

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

读取一个已提交请求的队列状态。 轮询端点。它只返回请求的当前状态，绝不返回结果，因此客户端可以监视长时间生成，而无需在每次轮询时传输输出：当这里返回 COMPLETED 时，结果会在下方的读取操作中一次性获取。 参数 响应 表格中的描述较为简短。关于模型选择、验证、重试和计费，请参阅使用 Comfy Router API；关于请求头行为，请参阅 Headers。

​
错误分类桶

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 以了解其类别。