Comfy Router API 参考

每个 Comfy Router 端点、参数、响应体和错误分类，均由 Comfy 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。

参数

cursor RouterPageCursor

不透明的分页游标。

类型：RouterPageCursor -- 作为 next_cursor 返回的不透明游标，1–512 个字符

limit integer

每页返回的模型数量。

最多 100，默认值：20

If-None-Match string

调用方从先前的 200 响应中持有的 ETag。

响应

200 RouterModelListResponse

OK - 模型目录中的一页。

响应体：RouterModelListResponse -- 响应头：X-Comfy-Request-Id、ETag、Cache-Control

304 no body

Not Modified - 自调用方在 If-None-Match 中发送的 ETag 以来，该页面没有变化。

响应头：X-Comfy-Request-Id、ETag、Cache-Control

400 RouterErrorResponse

请求无效。请检查错误类型和请求体。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

401 RouterErrorResponse

凭据缺失或无效。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

403 RouterErrorResponse

该调用方或模型不允许发起此请求。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

429 RouterErrorResponse

rate_limited：当前调用方的请求配额已用尽。请等待 Retry-After 后再发送下一次请求。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After

503 RouterErrorResponse

Router 暂时不可用。请退避后重试。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

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

按规范模型 ID 读取单个合作伙伴模型的产品目录条目。

无需列出完整目录即可读取单个模型的详情。

参数

provider RouterProviderSegment required

规范 {provider}/{model} 模型 ID 中的提供商部分。

类型：RouterProviderSegment —— 字母数字标识符，例如 anthropic，最多 64 个字符

model RouterModelSegment required

规范 {provider}/{model} 模型 ID 中的模型部分。

类型：RouterModelSegment —— 字母数字标识符，例如 claude-opus-4-6，最多 128 个字符

If-None-Match string

调用方从之前的 200 响应中持有的 ETag。

响应

200 RouterModelDetail

OK —— 该模型的产品目录条目。

响应体：RouterModelDetail —— 响应头：X-Comfy-Request-Id、ETag、Cache-Control

304 no body

Not Modified —— 自调用方在 If-None-Match 中发送的 ETag 对应版本以来，该条目未发生更改。

响应头：X-Comfy-Request-Id、ETag、Cache-Control

401 RouterErrorResponse

凭据缺失或无效。

响应体：RouterErrorResponse —— 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

403 RouterErrorResponse

该调用方或该模型无权执行此请求。

响应体：RouterErrorResponse —— 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

404 RouterErrorResponse

未找到该模型 ID。

响应体：RouterErrorResponse —— 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

429 RouterErrorResponse

rate_limited：当前调用方的请求配额已用尽。请等待 Retry-After 后再发送下一次请求。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After

503 RouterErrorResponse

Router 暂时不可用。请退避重试。

响应体：RouterErrorResponse —— 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

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

按规范模型 ID 同步运行合作伙伴模型。

运行模型，并在同一个响应中收到其已完成的结果。

参数

provider RouterProviderSegment required

规范 {provider}/{model} 模型 ID 中表示提供商的部分。

类型：RouterProviderSegment -- 字母数字 slug，例如 anthropic，最长 64 个字符

model RouterModelSegment required

规范 {provider}/{model} 模型 ID 中表示模型的部分。

类型：RouterModelSegment -- 字母数字 slug，例如 claude-opus-4-6，最长 128 个字符

Idempotency-Key string

由调用方生成的密钥，使重试一次逻辑调用变得安全。

1–255 个字符

model\_provider string

选择另一个提供商来服务此模型，而不是其当前默认提供商；fal、wavespeed、runware 和 higgsfield 是备选提供商，GET /v2/models/{provider}/{model} 会报告某个模型支持其中哪些。它的各种拒绝按固定顺序检查，靠前的拒绝无论靠后的拒绝是否成立都会生效：无法识别的值（根本不是已注册的提供商）会被拒绝并返回 400；随后，若请求体选择了 multipart 操作（编辑）而指定了备选提供商，则会被拒绝并返回 409，其 detail 以“this request's image selects the edit operation”开头，但仅当该提供商针对此模型的转换器无法服务该操作时才会如此，若某条 leg 的转换器确实携带该媒体，则会正常继续；接下来，若请求解析出了自带密钥（bring-your-own-key）凭据，则任何备选提供商都会被拒绝并返回 409，其 detail 以 this request resolved a BYOK credential 开头（见该响应），无论该提供商是否服务此模型；再接下来是该具名提供商自身的准入检查：当该提供商未为你开启时，会拒绝并返回 403 与 error_type: not_enabled，当无法评估该检查时，会拒绝并返回 503 与 error_type: service_unavailable；只有通过以上全部四项之后，真实提供商若对此模型没有 leg，才会被拒绝并返回 400 与 error_type: invalid_input，与无法识别的值得到相同的应答。在自带密钥请求上、在请求体选择 multipart 操作的请求上以及在 strict_mode=true 下，fallback_provider 是不生效，而不是被拒绝。

strict\_mode boolean

只有与 model_provider 一起使用时才有意义。

默认值：否

fallback\_provider string

控制当首次尝试因归因于 Router 或所尝试提供商的原因而失败时，Router 是否针对该模型的另一个已注册提供商重试此调用。省略该参数，或使用除 false 之外的任何值，都会保持回退开启；false 会将其关闭。成功回退的响应会带有 X-Comfy-Router-Fallback-Provider。在解析出了自带密钥凭据的请求上，无论此参数说什么，回退都不可用：根本不会进行该尝试，首次失败会原样返回给你，这属于不生效，而不是被拒绝：这里不会产生任何 409。出于同样的原因，在请求体选择 multipart 操作的请求上以及在 strict_mode=true 下也是如此：每一种情况都会把调用绑定到一个无法在另一个提供商上忠实重放的提供商，因此回退只是被跳过，而不是被拒绝。只有显式指定 model_provider 才会被以该 409 拒绝，而且与这种无条件跳过不同，其 multipart 的 409 仅适用于转换器无法服务该操作的 leg。

reject\_unknown\_fields boolean

选择拒绝此模型输入 schema 未声明的顶层请求体字段，而不是接受它；嵌套字段不会被检查，对于 schema 允许未声明字段或没有编写 schema 的模型，以及在以 strict_mode=true 发送的已执行提交上，都不会拒绝任何内容。

默认值：否

请求体

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 选择备选提供商时，每种带条件的操作可能会按该提供商自己的费率计费。

响应

200 RouterModelOutput

OK - 不带 model_provider，或带 model_provider 且 strict_mode=false（默认值，在可能时转换回本模型的原生契约，转换失败时回退到备用提供商自己的原始响应，会记录日志，绝不静默）时，形状是本模型自己的原生输出；当 strict_mode=true 时，则原样返回备用提供商的响应。对于由合作伙伴直接以字节形式返回生成结果的模型，响应体就是这些字节，使用合作伙伴自己的 Content-Type 而不是 application/json；请根据响应的 Content-Type 分支处理，不要假定它是一个 JSON 文档。

响应体：RouterModelOutput 或原始字节（*/*） -- 响应头：X-Comfy-Request-Id、X-Content-Type-Options、X-Comfy-Router-Fallback-Provider、X-Comfy-Router-Provider、X-Comfy-Router-Dropped-Params、X-Comfy-Credits-Used、Idempotent-Replayed、X-Committed-Spend-Limit、X-Committed-Spend-Current、X-Committed-Spend-Remaining

400 RouterErrorResponse

请求无效。请检查错误类型和请求体。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、X-Comfy-Upstream-Status、X-Comfy-Upstream-Detail、X-Comfy-Refusal-Subject、X-Comfy-Credits-Used、Idempotent-Replayed

401 RouterErrorResponse

凭据缺失或无效。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

402 RouterErrorResponse

Router 请求级别的失败：请求从未到达模型，或者因模型自身未反馈的原因而失败。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

403 RouterErrorResponse

该调用方或模型不允许执行此请求。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

404 RouterErrorResponse

未找到该模型 ID。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

409 RouterErrorResponse

检查 X-Comfy-Error-Type：concurrency_limit_exceeded 表示原始调用仍在运行，因此请等待 Retry-After 并复用同一个 key；invalid_input 则要求使用新的 key。此路由上有两种 invalid_input 冲突与 key 完全无关，任何新 key 都无法消除：当请求体选择的是该提供商针对此模型的转换器无法处理的多部分操作（编辑）时，用 model_provider 指定备用提供商会遭到拒绝，其 detail 以 "this request's image selects the edit operation" 开头；之后还会检查另一种情况：请求已经为路径中的提供商解析出自带密钥（BYOK）凭据，其 detail 以 this request resolved a BYOK credential 开头。请去掉 model_provider，或在发送请求时不带 BYOK 凭据，并且（针对多部分的情况）不带编辑操作。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After（当 concurrency_limit_exceeded 时）

413 RouterErrorResponse

请求体过大。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

422 RouterValidationErrorResponse

请求的内容依据模型 schema 被拒绝。

响应体：RouterValidationErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、Idempotent-Replayed

429 RouterErrorResponse

检查 X-Comfy-Error-Type：concurrency_limit_exceeded 表示应减少在途调用；rate_limited 表示应等待 Retry-After 指定的时间。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、X-Committed-Spend-Limit、X-Committed-Spend-Current、X-Committed-Spend-Remaining、X-Model-Concurrency-Limit、X-Model-Concurrency-Current、X-Model-Concurrency-Remaining、Retry-After（rate_limited 时）

502 RouterErrorResponse

提供商自己的响应无法转换为结果（provider_error）。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、X-Comfy-Upstream-Status

503 RouterErrorResponse

Router 暂时不可用。请退避后重试。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After（仅容量拒绝时）

504 RouterErrorResponse

请求超过了截止期限。重试前请检查错误类型。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、X-Comfy-Upstream-Status、Retry-After

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

在运行模型调用之前先为它定价，而无需实际运行。

返回预检估算值，以美元为单位，表示在指定模型上运行此请求体将产生的费用，按 Comfy 的标准标价计算（对于按提供商上报成本计费的模型，则改为根据提供商公布的价目表估算）。它不反映合同费率或客户特定费率：有协商定价的工作区会按标价报价、按合同费率收费，此时 source: exact 表示按标价精确，而不是该工作区的实际收费。这是估算值，不是最终费用：你实际支付的是工作区用量与账单记录中的结算费用。请求体会先按模型的输入 schema 校验，校验方式与默认运行（不启用 strict_mode，不启用 reject_unknown_fields）相同，因此不符合模型 schema 的请求体在这里会得到与运行接口相同的 422；不会向提供商派发任何内容，也不会产生任何费用。该结果不是价格锁定：它按 pricing_as_of 时生效的费率计价，而运行会按计费时生效的费率收费。如果某个部署关闭了估算，该路由会返回 403，并带有 error_type: not_enabled；Router 尚不能运行的模型会返回相同的 403，但带有运行路由自己的 detail，因此要读取 detail 来区分两者。请求体按 Router 实际派发它的方式计价：为其指定的 model_provider 环节进行转换，并重定向到它实际运行的操作，顺序与已执行提交的 201 响应中的 estimate 相同。不过，那个 estimate 并不是预检价格：它只有在运行被接纳并进入队列之后才会出现，而且该运行除非在派发之前被取消，否则都会被计费。

参数

provider RouterProviderSegment required

规范 {provider}/{model} 模型 ID 中的小写提供商段，即被运行模型所属的合作伙伴。

类型：RouterProviderSegment -- 字母数字 slug，例如 anthropic，最长 64 个字符

model RouterModelSegment required

规范 {provider}/{model} 模型 ID 中的小写模型段，即在该提供商内要运行的模型。

类型：RouterModelSegment -- 字母数字 slug，例如 claude-opus-4-6，最长 128 个字符

model\_provider string

选择用于提供此模型的备用提供商，以替代其当前的默认提供商。

请求体

application/json -- RouterModelInput（必填）

合作伙伴模型的原生 JSON 输入，与此模型的同步路由所接受的请求体完全相同。它会按模型自身的输入 schema 进行校验，与默认运行的校验方式一致（此路由不接受 strict_mode 或 reject_unknown_fields），并由其自身的字段（输出数量、输入图像所选择的操作）决定计价内容。

响应

200 RouterCostEstimate

报价。

响应体：RouterCostEstimate -- 响应头：X-Comfy-Request-Id

400 RouterErrorResponse

请求无效。请检查错误类型和请求体。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

401 RouterErrorResponse

凭据缺失或无效。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

403 RouterErrorResponse

此调用方或此模型不允许该请求。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

404 RouterErrorResponse

未找到该模型 ID。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

413 RouterErrorResponse

请求体过大。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

422 RouterValidationErrorResponse

估算请求的请求体未通过模型的 schema 校验，或指定的模型与路径中的模型不一致。

响应体：RouterValidationErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

429 RouterErrorResponse

rate_limited：当前调用方的请求配额已用尽。请等待 Retry-After 后再发送下一次请求。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After

503 RouterErrorResponse

Router 暂时不可用。请以退避方式重试。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After（仅限容量拒绝时）

504 RouterErrorResponse

请求超过了截止时间。重试前请检查错误类型。

响应体：RouterErrorResponse；响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

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

以 OpenAPI 文档形式读取单个合作伙伴模型的输入和输出 Schema。

以独立的 OpenAPI 文档形式读取单个模型的输入和输出 Schema。

参数

provider RouterProviderSegment required

规范 {provider}/{model} 模型 ID 中的提供商部分。

类型：RouterProviderSegment，字母数字短标识，例如 anthropic，最多 64 个字符

model RouterModelSegment required

规范 {provider}/{model} 模型 ID 中的模型部分。

类型：RouterModelSegment，字母数字短标识，例如 claude-opus-4-6，最多 128 个字符

If-None-Match string

调用方此前从 200 响应中获取的 ETag。

响应

200 RouterModelInputSchemaDocument

OK - 该模型的输入和输出 Schema，以独立的 OpenAPI 文档形式呈现。

响应体：RouterModelInputSchemaDocument - 响应头：X-Comfy-Request-Id、ETag、Cache-Control

304 no body

Not Modified - 自调用方在 If-None-Match 中发送的 ETag 以来，文档未发生变化。

响应头：X-Comfy-Request-Id、ETag、Cache-Control

401 RouterErrorResponse

凭据缺失或无效。

响应体：RouterErrorResponse - 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

403 RouterErrorResponse

该调用方或该模型不允许发起此请求。

响应体：RouterErrorResponse - 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

404 RouterErrorResponse

未找到该模型 ID。

响应体：RouterErrorResponse - 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

500 RouterErrorResponse

Router 无法完成该请求。

响应体：RouterErrorResponse - 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

429 RouterErrorResponse

rate_limited：当前调用方的请求配额已用尽。请等待 Retry-After 后再发送下一次请求。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After

503 RouterErrorResponse

Router 暂时不可用。请使用退避策略重试。

响应体：RouterErrorResponse - 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

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

将合作伙伴模型运行任务提交到队列并立即返回。

Comfy Router 的队列投递模式。请求体与该模型的 POST /v2/models/{provider}/{model} 所接受的合作伙伴原生 JSON 输入相同：同一请求体形状、同一套按模型定义的 schema、两种投递模式，但此路由不会保持连接来等待结果。它会接纳该运行任务，返回 201 和一个句柄，调用方随后通过下文所述的三个读取操作获取结果。

参数

provider RouterProviderSegment required

规范 {provider}/{model} 模型 ID 中的小写提供商段，即运行其模型的合作伙伴。

类型：RouterProviderSegment：字母数字 slug，例如 anthropic，最多 64 个字符

model RouterModelSegment required

规范 {provider}/{model} 模型 ID 中的小写模型段，即在该提供商内要运行的模型。

类型：RouterModelSegment：字母数字 slug，例如 claude-opus-4-6，最多 128 个字符

model\_provider string

选择用于服务此模型的备用提供商，而不是其当前默认提供商。

strict\_mode boolean

仅在与 model_provider 一起使用时才有意义。

默认值：False

Idempotency-Key string

调用方生成的键，可确保重试同一次逻辑调用是安全的。

1–255 个字符

reject\_unknown\_fields boolean

选择拒绝此模型输入 schema 未声明的顶层请求体字段，而不是接受该字段；不会检查嵌套字段，并且对于其 schema 允许未声明字段或没有已编写 schema 的模型，或者对于使用 strict_mode=true 发送的队列提交，不会拒绝任何字段。

默认值：False

请求体

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）。

响应

201 RouterQueueSubmitResponse

已创建：运行任务已获准进入队列。

响应体：RouterQueueSubmitResponse：响应头：X-Comfy-Request-Id、Idempotent-Replayed

401 RouterErrorResponse

凭证缺失或无效。

响应体：RouterErrorResponse：响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

400 RouterErrorResponse

请求无效。请检查错误类型和请求体。

响应体：RouterErrorResponse：响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

413 RouterErrorResponse

请求体过大。

响应体：RouterErrorResponse：响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

402 RouterErrorResponse

Router 请求级失败：请求从未到达模型，或由于模型自身未反馈的原因而失败。

响应体：RouterErrorResponse：响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

403 RouterErrorResponse

此调用方或模型不允许该请求。对于合作伙伴直接以字节形式返回生成结果的模型，目前尚不能排队，并会以 not_enabled 拒绝；请改为在同步路由上运行。

响应体：RouterErrorResponse：响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

404 RouterErrorResponse

未找到模型 ID。

响应体：RouterErrorResponse：响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

409 RouterErrorResponse

Check X-Comfy-Error-Type：concurrency_limit_exceeded 表示原始调用仍在运行，因此请等待 Retry-After 并复用同一个 key；invalid_input 则需要使用新 key。此路由上的两个 invalid_input 冲突与 key 完全无关，且任何新 key 都无法消除其中任何一个：当请求正文选择该提供商针对此模型的转换器无法处理的多部分操作（编辑）时，指定备用提供商的 model_provider 会被拒绝，其 detail 以 "this request's image selects the edit operation" 开头；之后还会检查另一种情况，即当请求已经为路径中的提供商解析出自带密钥（BYOK）凭证时，其 detail 以 this request resolved a BYOK credential 开头。请去掉 model_provider，或在发送请求时不带 BYOK 凭证，并且（对于多部分情形）不带编辑操作。

正文：RouterErrorResponse。头部：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After（当 concurrency_limit_exceeded 时）

422 RouterValidationErrorResponse

请求内容未通过模型的 schema 校验。

正文：RouterValidationErrorResponse。头部：X-Comfy-Error-Type、X-Comfy-Request-Id、Idempotent-Replayed

429 RouterErrorResponse

检查 X-Comfy-Error-Type：queue_backlog_full 表示你持有的未完成排队请求已达到允许的上限，因此请在其中一个完成后再次提交；rate_limited 表示需要等待 Retry-After 指定的时间。

正文：RouterErrorResponse。头部：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After（rate_limited 时）

503 RouterErrorResponse

Router 暂时不可用。请使用退避策略重试。

正文：RouterErrorResponse。头部：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After（仅容量拒绝时）

504 RouterErrorResponse

请求超过了截止时间。重试前请检查错误类型。

响应体：RouterErrorResponse；响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

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

收集一个已提交请求的结果。

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

参数

provider RouterProviderSegment required

规范 {provider}/{model} 模型 ID 的小写提供商段，即正在运行其模型的合作伙伴。

类型：RouterProviderSegment，字母数字 slug，例如 anthropic，最多 64 个字符

model RouterModelSegment required

规范 {provider}/{model} 模型 ID 的小写模型段，即在该提供商内运行的模型。

类型：RouterModelSegment，字母数字 slug，例如 claude-opus-4-6，最多 128 个字符

request\_id RouterQueueRequestId required

要处理的已排队请求，即提交时在响应体中返回的 request_id。

类型：RouterQueueRequestId，pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$，uuid，最多 36 个字符

响应

200 RouterModelOutput

OK：为产生了结果的请求存储的结果。该请求已成功完成，或是同时带有记录扣费和存储结果的终端请求。它按合作伙伴自己的媒体类型原样返回，与同步路由的 200 返回它的方式完全一致，并遵循提交时接受的相同提供商选择约定：未提供 model_provider，或提供 model_provider 且 strict_mode=false（默认值，在可能时转换回此模型的原生约定，转换失败时回退到备用提供商自己的原始响应，并记录日志，绝不静默），形状为此模型自身的原生输出；使用 strict_mode=true 时，则是备用提供商的响应原样返回。对于合作伙伴直接以字节返回生成结果的模型，响应体是这些字节，使用合作伙伴自己的 Content-Type 而非 application/json；请根据响应的 Content-Type 进行分支，不要假定它是 JSON 文档。

响应体：RouterModelOutput 或原始字节（*/*）；响应头：X-Comfy-Request-Id、X-Content-Type-Options、X-Comfy-Credits-Used

202 RouterQueueStatusResponse

已接受：请求尚未完成。

响应体：RouterQueueStatusResponse；响应头：X-Comfy-Request-Id、Retry-After

401 RouterErrorResponse

缺失或无效的凭据。

响应体：RouterErrorResponse；响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

403 RouterErrorResponse

此调用方或模型不允许该请求。

响应体：RouterErrorResponse；响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

404 RouterErrorResponse

未找到该模型 ID。

响应体：RouterErrorResponse；响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

410 RouterErrorResponse

Router 请求级失败：请求从未到达模型，或由于模型本身未报告的原因而失败。

响应体：RouterErrorResponse；响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

429 RouterErrorResponse

rate_limited：当前调用方的请求配额已用尽。请等待 Retry-After 后再发送下一次请求。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After

503 RouterErrorResponse

Router 暂时不可用。请使用退避策略重试。

响应体：RouterErrorResponse；响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

409 RouterErrorResponse

请求处于与操作冲突的状态。请检查错误类型。

响应体：RouterErrorResponse；响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

504 RouterErrorResponse

请求超过了截止时间。重试前请检查错误类型。

响应体：RouterErrorResponse；响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

default RouterErrorResponse

Router 请求级失败：请求从未到达模型，或由于模型本身未报告的原因而失败。

响应体：RouterErrorResponse；响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

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

请求取消一个已提交的请求。

请求 Comfy 停止一个尚未完成的请求。这是一项请求，而不是保证，202 正说明了这一点：CANCELLATION_REQUESTED 表示该请求已被接受，并不表示运行已经停止。已经发送给合作伙伴的运行仍可能完成；而合作伙伴完成的生成会被计费，无论是否有人获取结果。因此，需要了解实际结果的调用方应随后读取状态端点，在状态端点中，已生效的取消会显示为 COMPLETED，并像其他所有终端结果一样带有 error_type。

参数

provider RouterProviderSegment required

规范 {provider}/{model} 模型 ID 中的小写提供商段，即正在运行其模型的合作伙伴。

类型：RouterProviderSegment，字母数字 slug，例如 anthropic，最多 64 个字符

model RouterModelSegment required

规范 {provider}/{model} 模型 ID 中的小写模型段，即要在该提供商内运行的模型。

类型：RouterModelSegment，字母数字 slug，例如 claude-opus-4-6，最多 128 个字符

request\_id RouterQueueRequestId required

要处理的排队请求，即提交操作在响应正文中返回的 request_id。

类型：RouterQueueRequestId，pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$，uuid，最多 36 个字符

响应

202 RouterQueueCancelResponse

已接受：CANCELLATION_REQUESTED。

正文：RouterQueueCancelResponse，响应头：X-Comfy-Request-Id

409 RouterQueueCancelResponse

冲突：ALREADY_COMPLETED。

正文：RouterQueueCancelResponse，响应头：X-Comfy-Request-Id

400 RouterErrorResponse

无效请求。请检查错误类型和请求正文。

正文：RouterErrorResponse，响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

401 RouterErrorResponse

凭据缺失或无效。

正文：RouterErrorResponse，响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

403 RouterErrorResponse

该调用方或模型不允许此请求。

正文：RouterErrorResponse，响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

404 RouterErrorResponse

未找到该模型 ID。

正文：RouterErrorResponse，响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

429 RouterErrorResponse

rate_limited：当前调用方的请求配额已用尽。请等待 Retry-After 后再发送下一次请求。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After

503 RouterErrorResponse

Router 暂时不可用。请使用退避策略重试。

正文：RouterErrorResponse，响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

default RouterErrorResponse

Router 请求级失败：请求从未到达模型，或由于模型本身未反馈的原因而失败。

正文：RouterErrorResponse，响应头：X-Comfy-Error-Type、X-Comfy-Request-Id

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

读取一个已提交请求的队列状态。

轮询端点。它返回的是请求当前的状态，而非结果，因此客户端可以持续观察一次长时间生成，而无须在每次轮询时都传输其输出。当此端点返回 COMPLETED 时，再从下方的读取接口一次性获取结果。

参数

provider RouterProviderSegment required

规范 {provider}/{model} 模型 ID 中的小写提供商标识段，即正在运行其模型的合作伙伴。

类型：RouterProviderSegment。字母数字标识，例如 anthropic，最多 64 个字符

model RouterModelSegment required

规范 {provider}/{model} 模型 ID 中的小写模型标识段，即在该提供商下要运行的模型。

类型：RouterModelSegment。字母数字标识，例如 claude-opus-4-6，最多 128 个字符

request\_id RouterQueueRequestId required

要查询的排队请求，即提交时在响应体中返回的 request_id。

类型：RouterQueueRequestId。pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$，uuid，最多 36 个字符

响应

200 RouterQueueStatusResponse

OK，请求当前的队列状态。

正文：RouterQueueStatusResponse。请求头：X-Comfy-Request-Id、Retry-After、X-Comfy-Credits-Used、X-Comfy-Estimated-Duration-Seconds、X-Comfy-Estimated-Duration-P90-Seconds、X-Comfy-Estimate-Source

401 RouterErrorResponse

凭据缺失或无效。

正文：RouterErrorResponse。请求头：X-Comfy-Error-Type、X-Comfy-Request-Id

403 RouterErrorResponse

该调用方或模型无权执行此请求。

正文：RouterErrorResponse。请求头：X-Comfy-Error-Type、X-Comfy-Request-Id

404 RouterErrorResponse

未找到该模型 ID。

正文：RouterErrorResponse。请求头：X-Comfy-Error-Type、X-Comfy-Request-Id

410 RouterErrorResponse

Router 请求级失败：请求从未到达模型，或因模型自身未反馈的原因而失败。

正文：RouterErrorResponse。请求头：X-Comfy-Error-Type、X-Comfy-Request-Id

429 RouterErrorResponse

rate_limited：当前调用方的请求配额已用尽。请等待 Retry-After 后再发送下一次请求。

响应体：RouterErrorResponse -- 响应头：X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After

503 RouterErrorResponse

Router 暂时不可用。请以退避方式重试。

正文：RouterErrorResponse。请求头：X-Comfy-Error-Type、X-Comfy-Request-Id

default RouterErrorResponse

Router 请求级失败：请求从未到达模型，或因模型自身未反馈的原因而失败。

正文：RouterErrorResponse。请求头：X-Comfy-Error-Type、X-Comfy-Request-Id

此处的描述较为简短。有关模型选择、验证、重试和计费，请参阅使用 Comfy Router API；有关请求头行为，请参阅请求头。

错误分类桶

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

请求级分类桶

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

传输级分类桶

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

响应头

Cache-Control string

用于目录页面或条目的新鲜度指令。

发送条件：200、304

Cache-Control string

用于所提供架构文档的新鲜度指令。

发送条件：200、304

ETag string

针对所提供响应体字节的强实体标签，用于 GET /v2/models 和 GET /v2/models/{provider}/{model}。

发送条件：200、304

ETag string

针对所提供文档字节的强实体标签，用于 GET /v2/models/{provider}/{model}/openapi.json。

发送条件：200、304

Idempotent-Replayed boolean

当此响应来自某条 Idempotency-Key 的记录，而不是通过再次运行模型产生时，该响应头会出现并且值为 true。

Retry-After integer

收到带 error_type: rate_limited 的 429 后，发送下一个请求前需要等待的秒数：即调用方每分钟请求配额恢复到足以再接纳一个请求所需的时间。

发送条件：429

Retry-After integer

原样重新发送同一请求前需要等待的秒数。

发送条件：503

Retry-After integer

下一次轮询这个已排队的请求前需要等待的秒数。

发送条件：200、202

Retry-After integer

使用同一个 Idempotency-Key 重试同一请求之前需要等待的秒数。

发送条件：409、504

X-Comfy-Credits-Used string

本次运行的费用，以 Comfy 积分计，按照扣费本身所依据的同一价目表定价。因此调用方无需自备价格表；当一次运行经由不止一个计费调用抵达提供商时，该值是这些调用的总和，而不是最后一次调用的值。

X-Comfy-Error-Type RouterErrorType

失败的粗粒度、机器可读分类，由 Router 在每个错误响应上设置。

类型：RouterErrorType

X-Comfy-Estimate-Source string

仅在 status 为 IN_PROGRESS 的状态读取时发送，位于 X-Comfy-Estimated-Duration-Seconds 旁边：说明该生成时长估计来自哪里（不是费用估计中的 source），取值为 historical（依据近期运行实测）或 default（按媒体类型设置的兜底值，在记录的近期运行太少时使用）。

X-Comfy-Estimated-Duration-P90-Seconds integer

仅在 status 为 IN_PROGRESS 的状态读取时发送，位于 X-Comfy-Estimated-Duration-Seconds 旁边：该生成时长估计的第 90 百分位，以整秒为单位。

X-Comfy-Estimated-Duration-Seconds integer

仅在 status 为 IN_PROGRESS 的状态读取时发送：Router 对这次生成在提供商接受之后整个运行耗时的估计，以整秒为单位（不是剩余时间，也从不包含 IN_QUEUE 中度过的时间）。

X-Comfy-Refusal-Subject string

内容策略拒绝所针对的是哪个输入或输出，采用 Router 层面的封闭词表：input、output、input_text、input_image、input_video、input_audio、output_text、output_image、output_video、output_audio。

X-Comfy-Request-Id string

服务器为此次调用生成的标识符，存在于每一个 Router 响应中：成功、4xx 和 5xx 响应均如此，因为错误响应恰恰是用户需要在支持请求中引用某个 ID 的时候。

X-Comfy-Router-Dropped-Params string

一个 JSON 编码的字符串，内含一个字符串数组。请使用 JSON 解析器来解码，而不要按逗号对其分割，因为它在传输时是单个字符串，而不是逗号分隔的 OpenAPI 数组，并且每个条目本身就是一个自带逗号的句子。当一次转换生成了本次调用的请求体，却无法在所服务的提供商上精确表达一个或多个原生字段时，该响应头就会出现，并逐一列出每个被丢弃的字段及其原因；无论调用方是通过 model_provider（strict_mode=false，默认值）请求该转换，还是由自动的 fallback_provider 重试执行了该转换，都是如此。

X-Comfy-Router-Fallback-Provider string

仅当 fallback_provider 确实针对第二个提供商重试了此调用，并且该重试成功时，该响应头才会出现并指明该提供商：即最终服务此调用的提供商，绝不是被尝试过但也失败了的那个。

X-Comfy-Router-Provider string

服务此次调用的 Router 链路的提供商，出现在每个成功运行的响应中：原生运行时为模型自身的提供商，也可能是 model_provider 指定的备用提供商，或者是 fallback_provider 重试最终落在的提供商（仅在这种情况下 X-Comfy-Router-Fallback-Provider 也会指明它）。它代表的是 Router 派发到的链路，而不一定是产生输出的厂商，因为原生链路内部的代理级联（例如 vertexai 的 Gemini 图像链）可能把调用交给另一个厂商，而没有任何响应头会指明它。

X-Comfy-Upstream-Detail string

模型提供商给出的、有长度限制且已脱敏的拒绝该请求的原因。

X-Comfy-Upstream-Status integer

模型提供商在此次调用中自身的 HTTP 状态。

X-Committed-Spend-Current integer

调用方当前已承诺给仍在途调用的美分数。

X-Committed-Spend-Limit integer

调用方可承诺给仍在途调用的合作伙伴支出上限，单位为美分。这笔资金从调用被接纳的那一刻起即被保留，并在该调用结束时释放。

X-Committed-Spend-Remaining integer

上限之下剩余的可用额度，单位为美分，最低为零。

X-Content-Type-Options string

在 Router 模型的每次成功运行中都始终为 nosniff。

X-Model-Concurrency-Current integer

调用方对归为昂贵的模型的并发调用数，由拒绝此次调用的闸门统计得出。

X-Model-Concurrency-Limit integer

调用方一次可持有的、对归为昂贵的模型的并发调用上限，为并发调用限额的四分之一，与合作伙伴节点调用共享。

X-Model-Concurrency-Remaining integer

调用方仍可启动的昂贵模型调用数；在 429 时为 0。

预检成本估算

POST /v2/models/{provider}/{model}/estimate 可在不运行请求体的情况下为其定价，而已排队的提交（POST /v2/models/{provider}/{model}/requests）会在其 201 响应中返回与 estimate 相同的 RouterCostEstimate。两者均按 Comfy 的标准标价定价，但按供应商报告的成本计费的模型除外，该成本会根据供应商公布的价格表估算（estimated）。两者都不反映合同费率或客户特定费率：具有协商定价的工作区会按标价报价，但按其合同费率收费，此时 source: exact 表示在标价上精确，而不是该工作区的实际收费。两个接口返回的每个数字都是估算值，而不是最终费用：工作区使用情况和账单记录中的结算费用才是最终费用。使用自己的提供商密钥进行的运行不会由 Comfy 计费（见下文）。如果某个部署关闭了估算功能，该路由会返回 403，并带有 error_type: not_enabled，且提交响应会省略 estimate。两者都会按照 Router 分发请求体的方式为其定价（针对 model_provider 分支进行转换，并重定向到其实际运行的操作），但提交响应中的 estimate 不是预检价格：它只有在运行被接纳并排队后才会出现，而且除非在分发前被取消，否则该运行会被计费。目录仍然不包含价格。

在关注任何金额之前，请先读取 source。缺失的数值绝不意味着免费。

unknown 估算的 reason 为以下之一：

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

Router 尚无法在运行前定价的模型列在没有预检估算的模型中。未列在该处的模型针对特定请求体仍可能返回 unknown，因此请对每个估算都读取 source。

估算采用失败关闭（fail closed）的情形：

• 当某个数值需要费率卡，而费率卡未加载或已过期时，/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，因此只校验模型的原生约定：一个在 strict_mode=true 运行中按备用提供商自身 schema 可以接受的请求体，在这里可能得到 422；而某个未声明的顶层字段，在 reject_unknown_fields=true 的运行中会被拒绝，在这里却会被定价。Anthropic Messages 模型是例外：其 schema 允许未声明字段，因此 reject_unknown_fields=true 的运行不会拒绝任何字段，而估算只会为未声明的顶层字段 tools、tool_choice、temperature、top_p、top_k、stop_sequences、metadata、thinking 以及空的 mcp_servers 定价。任何其他未声明的顶层字段都会使其返回 unknown，并带有 reason: not_quotable。
• pricing_as_of 是费率卡的获取时间。取自供应商公布价格表的 estimated 报价携带的是读取该价格表的日期。计费数量由供应商公布的调度表预测、再按费率卡定价的 exact 或 estimated 报价，在该调度表的读取日期早于费率卡时携带该调度表的读取日期。费率卡与调度表都未读取时，它则是估算作答的时间。它不是价格锁定：运行按其被计费评级时生效的费率收费。
• /estimate 为 model_provider 指定的分支报价，或为原生提供商报价。它不接受 fallback_provider 或 strict_mode 参数。同步运行的回退重试落到另一个提供商时，按该提供商的费率计费，而该费率并非估算所报的费率；运行响应上的 X-Comfy-Router-Fallback-Provider 表明发生了这种情况。排队提交没有回退，因此其 estimate 报的就是实际运行的分支。
• /estimate 始终报出平台费用。使用自有提供商密钥的运行不由 Comfy 计费，但 /estimate 不会检测这一点，仍会返回一个数值；只有排队提交才会返回 reason: byok。
• 美元金额由未舍入的美分渲染，最多保留 8 位小数，可计费的不足 1 美分的 amount 绝不会显示为 0。credits 为 round(amount × 211, 2)，这与 X-Comfy-Credits-Used 对一次收费所采用的换算相同，因此对于极小的非零价格，credits 可能舍入为 0；在这一点很重要时，请按 amount 或 amount_cents 编制预算，而不是按 credits。该响应头仍是某次运行结束后的事后数值；余额保存在 Comfy 平台上。

结果资产

模型可以返回资产 URL、内联字节，或两者兼有。下面的提供商会将已选择的资产复制到 Comfy 存储上并替换其 URL。此行为取决于模型；没有任何请求头能选择它。

这些有效期从 URL 签名时开始计算，而不是从你打开它时开始。缓存或重放的 URL 可能剩余时间更少；重放不会为其续期。一条 Idempotency-Key 记录的有效期可能长于它所保存的 URL，因此在这样的 URL 到期前一小时起，使用同一键重试会得到 409 invalid_input，而不是记录中的响应；若某条响应在送达时就已如此接近到期，则它在 5 分钟内仍可重放。请及时下载资产。只有每一行中列出的资产会被复制：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 契约未对此作出规定。

原始 BytePlus URL（Seedance 2.x，需选择启用）。 对于 Comfy 已在服务器端选择启用的工作区，Seedance 2.x 的结果还会在已复制的 URL 之外，于 content.upstream_video_url 和 content.upstream_last_frame_url 中携带 BytePlus 自己的 URL，以及 content.upstream_expires_at。没有请求参数，且默认没有任何工作区被选择启用。这些 URL 在生成后 24 小时过期，一旦 BytePlus 清除它们便不再出现；在 Seedance 2.5 上，BytePlus 将每个 URL 的上限设为 100 次下载，而 Router 自己的副本会占用其中一次。每个 URL 都是其对象的持有者凭证：任何持有者在过期前都可以下载该资产。

零数据保留的工作区。 对于 Comfy 配置为零数据保留的工作区，BytePlus 的结果不会复制到 Comfy 存储：上文中的 byteplus/* 视频行不适用，content.video_url 和 content.last_frame_url 就是 BytePlus 自己的提供商 URL，按 BytePlus 发送时的原样返回。这些 URL 有效期为 24 小时，并且在 Seedance 2.5 上 BytePlus 将每个 URL 限制为 100 次下载，因此请尽快下载资产。此类结果不会从其 Idempotency-Key 记录重放。

复制是按资产尽力而为的。如果某个复制失败，该条目会保留其提供商引用；响应可以同时包含 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

RouterBilledWorkspace

被拒绝的调用原本会扣费的钱包，位于 RouterErrorResponse.billed_workspace 上。它回答的是“哪个钱包是空的？”这个问题，并不一定就是调用方 UI 当前已选择的工作区；而且，即使当前打开的是一个有充足余额的团队，团队成员使用个人凭据时，这里命名的仍是其个人钱包。仅在同时存在 denied_reason 时才会出现。

字段

id string

云端工作区 id。在传统通道上不存在。

type string required

personal 或 team。这是一个开放字符串：其他任何值都应按个人处理。

rail string

当调用计费到调用方在工作区出现之前的 Metronome 客户，而不是计费到某个云端工作区时，为 legacy；该客户没有工作区 id。对于云端工作区则不存在。

RouterChargesOnPolicyRejection

该模型的内容策略拒绝是否计费。将未知值视为可能计费。

类型：string

RouterCostEstimate

这是对本次调用将要产生费用的预先估算，单位为美元。它在分发之前定价：按 Comfy 的标准列表价格，或者对于按供应商报告的费用计费的模型，则依据供应商公布的价格表。对于这种由供应商报告的情况，source: exact 仅针对一小部分选择加入的模型返回，且仅当公布的价格表完全确定该数字时才返回（每个影响价格的字段都已明确给出，或保留在无法改变该数字的默认值上）；其他所有由供应商报告的报价都是 estimated，包括其中一些价格表本可完全确定的情况。无论哪种情况，运行结束后仍按供应商报告的金额计费，绝不会原样按报价金额收费。它不反映合同价格或客户特定费率：已协商定价的工作区会按列表价格报价，并按合同费率收费，此时 source: exact 表示在列表价格上是精确的，而不是该工作区的实际收费。它不是最终收费：你工作区用量和账单记录中的结算收费才是你实际支付的费用。运行后报告的 X-Comfy-Credits-Used 是四舍五入的事后数字，不是收据。source 表示该数字的可信度：exact 携带 amount；free 携带 amount "0"（费率卡将本次请求定价为零）；estimated 携带 min_amount 和 max_amount，不带 amount；unknown 两者都不带，并带一个 reason。切勿将缺失的 amount 理解为免费。它不是价格锁定：请参阅 pricing_as_of。

字段

source string required

exact | estimated | free | unknown；其他任何值都按 unknown 读取。exact 和 estimated 标记的都是估算值；两者都不是最终扣费。free 表示费率卡将本次请求定价为零，因此 amount 为 "0"。unknown 不带任何数字。

currency string required

始终为 USD。

amount string

估算费用，以美元计的十进制字符串，例如 "0.04"，最多 8 位小数且不含指数。可计费的不足一美分的价格绝不会渲染为 "0"；只有 free 的报价才读作 "0"。仅当 source 为 exact 或 free 时出现。它不是最终扣费：工作区用量与账单记录中的结算金额才是。

min\_amount string

估算值的下限，以美元计的十进制字符串。它是估算值，不是保证的下限：调用可能被计费更少，例如当提供商返回的内容少于请求所需（比如没有返回任何图像）、当估算值是根据过往调用学到的典型价格，或当价格不随请求的数量稳定上升时。仅当 source 为 estimated 时出现。

max\_amount string

估算值的上限，以美元计的十进制字符串。它是估算值，不是保证的上限：调用可能被计费更多，例如当提供商返回的内容多于请求所需（比如返回的图像多于请求数量）、当估算值是根据过往调用学到的，或当价格不随请求的数量稳定上升时。仅当 source 为 estimated 时出现。

amount\_cents number

同一数字以美分表示，不取整，用于算术运算。与 amount 一同出现。

double

min\_amount\_cents number

min_amount 以美分表示，不取整。与 min_amount 一同出现。

double

max\_amount\_cents number

max_amount 以美分表示。与 max_amount 一同出现。

double

credits number

amount 按平台换算（\$1 = 211 积分）折算为 Comfy 积分，四舍五入到 2 位小数，即 exact 报价下 X-Comfy-Credits-Used 预期携带的数字。该响应头是四舍五入的事后数字，不是收据；工作区用量与账单记录中的结算金额才是最终结果。

double

provider string required

本报价对应的提供商分支。在排队提交中，它就是要运行的那个分支。

model RouterModelId required

规范的 Comfy Router 模型 ID，格式为 {provider}/{model}，正是用于在 POST /v2/models/{provider}/{model} 上寻址该模型的那个值，因此调用方可以直接把它插入该路径，而无需从任何其他内容重新推导。它的 pattern 由 RouterProviderSegment 和 RouterModelSegment 以单个 / 连接而成，maxLength 为两者长度之和再加上这个分隔符。

类型：RouterModelId：模型 ID，例如 anthropic/claude-opus-4-6，最多 193 个字符

pricing\_as\_of string required

本报价所依据的费率卡的获取时间。估算值不是价格锁定：运行按计费时生效的费率收费，而不是按这一时刻的费率。从供应商公布的价格表取得的 estimated 报价（按供应商报告的费用计费的模型）改为携带读取该价格表的日期；而计费数量由供应商公布的调度表预测、再按费率卡定价的报价，无论给出的是 exact 还是 estimated 答案，都携带该调度表的读取日期与费率卡获取时间中较早的一个（按供应商报告的积分计费的模型属于 estimated 情形）。只要没有读取任何费率卡（reason: pricing_unavailable、byok，或无法从任何卡定价的 not_quotable 调用），它就是回答该报价的时间。

date-time

reason string

仅当 source 为 unknown 时出现：not_quotable（Router 无法在运行前为本次调用定价：其价格取决于提供商回报的内容，或者请求体没有界定出计费数量）、unpriced_model（费率卡未对本次请求定价）、byok（仅排队提交：运行使用你自己的提供商密钥，因此 Comfy 不为其计费），或 pricing_unavailable（仅排队提交：请求被准入时无法读取费率卡；这是暂时性的，运行仍照常计费）。其他任何值都按 not_quotable 读取。

RouterErrorResponse

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

字段

detail string required

人类可读的失败描述，可以安全地展示给最终用户。不要对其做机器解析，而应改为根据 error_type 分支。对于已停用模型上的 model_not_found，当记录了后继模型且对调用方可见时，detail 会显示 <id> was retired on <YYYY-MM-DD>; use <successor>；否则只显示 <id> was retired on <YYYY-MM-DD>，而不是通常的建议列表。此处指定的后继模型始终是一个有效目录 ID，调用可以重新指向它。停用日期尚在未来的模型不算已停用：在到达该日期之前，它仍会出现在 GET /v2/models 中并可继续运行。与 detail 的其余内容一样，这段停用措辞仅用于展示，不附带任何兼容性保证。不对其做机器解析这一规则有两个有文档记录的例外：在 POST /v2/models/{provider}/{model} 上，409 会因三种互不相关但同属 invalid_input 分类的情况而返回，且只有 detail 能区分它们。以“this request's image selects the edit operation”开头的 detail 是 multipart model_provider 拒绝，以 this request resolved a BYOK credential 开头的 detail 是 BYOK model_provider 拒绝；两者都无法通过新的 Idempotency-Key 消除。该路由上任何其他 invalid_input 的 409 都是密钥冲突。这两个前缀都是稳定的合约术语，可以进行匹配。在其他任何地方，基于 detail 分支都不提供兼容性保证。

error\_type RouterErrorType required

Router 故障的粗粒度、机器可读分类，会同步到 X-Comfy-Error-Type 响应头，以便调用方无需解析响应体即可分支。该集合封闭为二十个值：六个请求级分类 invalid_input、content_policy_violation、provider_error、provider_timeout、insufficient_credits 和 model_not_found，以及传输级的 unauthorized、forbidden、concurrency_limit_exceeded、client_disconnected、internal_error、deadline_exceeded、not_enabled、service_unavailable、rate_limited、cancelled、queue_timeout、request_not_found、queue_backlog_full 和 result_expired。“封闭”描述的是当前文档所记录的状态，而不是一个永远成立的限制：该集合预计会增长，因此这里特意使用普通字符串而非 enum，客户端必须将无法识别的值视为 internal_error，而不是对上述列表做穷举式 switch 并在下一次新增时出错。

类型：RouterErrorType

upstream\_detail string

模型提供商给出的、有长度限制且经过脱敏的拒绝请求原因，仅在 error_type 为 invalid_input 且 X-Comfy-Upstream-Status 为提供商的 4xx 或 2xx 时出现，即提供商以请求格式错误为由拒绝请求并说明了原因。通常该状态是 4xx；对于在成功信封内报告生成被拒绝的提供商，则为 2xx（BytePlus 的失败任务轮询是 HTTP 200，原因位于响应体中）。在其他所有失败情形中均不出现，包括提供商 5xx、传输失败、内容策略拒绝以及 Router 自身提出的任何拒绝。它与 X-Comfy-Upstream-Detail 头对应。

refusal\_subject string

内容策略拒绝所针对的输入或输出，采用 Router 层面的封闭词汇表：input、output、input_text、input_image、input_video、input_audio、output_text、output_image、output_video、output_audio。当提供商未指明模态时，仅用 input / output 值来表示是哪一侧。仅当 error_type 为 content_policy_violation 且提供商使用机器可读代码指明了被拒绝的对象时出现；否则不出现。绝不是提供商文本。目前会为 BytePlus、Runway、BFL、Gemini、Veo、Vertex、xAI 和 Wan 的拒绝给出该字段，也会为 MiniMax Router 的 Nano Banana 链路中的 Gemini 拒绝给出该字段；如果提供商的拒绝未说明涉及哪一侧，则该字段不出现。它与 X-Comfy-Refusal-Subject 头对应。

denied\_reason string

计费系统针对合作伙伴节点支出拒绝的策略分支：当被计费钱包为空时为 no_funds，当调用被拒绝但没有资金读取结果说明原因时为 unspecified。仅当 error_type 为 insufficient_credits 且部署上报钱包相关信息时出现；否则不出现。它是机器可读代码，而非展示文本：请展示 detail，并基于此字段分支。

billed\_workspace RouterBilledWorkspace

被拒绝调用原本会扣款的钱包，位于 RouterErrorResponse.billed_workspace。它回答“哪个钱包为空？”这个问题：它不一定是调用方 UI 当前选择的工作区，而且即使当前打开的是资金充足的团队，团队成员的个人凭证在这里也会指向其个人钱包。仅与 denied_reason 一同出现。

类型：RouterBilledWorkspace

credential\_kind string

被拒绝请求的身份验证方式：personal_api_key、team_api_key、personal_session 或 team_session。它回答“我应该切换到哪个凭证，才能向另一个钱包计费？”这个问题。它不是权限，也不授予任何权限。仅与 denied_reason 一同出现。

RouterErrorType

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

类型：string

RouterModelBilling

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

字段

charges\_on\_policy\_rejection RouterChargesOnPolicyRejection required

该模型因内容政策原因拒绝的调用，是否仍向调用方计费。不同提供商的处理方式不同，而这种差异在调用时是不可见的，用户如果同一次调用既看到错误又看到扣费，根本无从预先得知。因此这里按模型逐个说明，而不是留待各提供商自行口口相传。当值为 yes 时，同步路由上的 content_policy_violation 错误可能会携带 X-Comfy-Credits-Used：当提供商拒绝了模型生成的输出，且 Comfy 为该次被拒绝的生成记录了用量时，就会携带该响应头，并给出相应的数量。输入端拒绝、同键重放（Idempotent-Replayed: true）以及金额过小、无法在响应头的两位小数中显示的扣费都不会携带它；没有该响应头的拒绝不会被报告，但这并不能证明它是免费的。

类型：RouterChargesOnPolicyRejection

RouterModelDetail

单个 Comfy Router 模型的逐模型详情：既包含目录列表为该模型报告的全部内容，也包含只有单模型路由才会携带的逐模型字段。

组合了 RouterModelListEntry 与 RouterModelDetailFields。

类型：object

RouterModelDetailFields

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

字段

input\_schema\_url string

此模型的 OpenAPI 文档 URL，包括其输入和输出 schema。

HTTPS URL，例如 https://api.comfy.org/v2/models/bfl/flux-2-pro/openapi.json，最多 2048 个字符

RouterModelId

在 POST /v2/models/{provider}/{model} 中使用的模型 ID。

类型：string，模型 ID，例如 anthropic/claude-opus-4-6，最多 193 个字符。

RouterModelInput

模型输入对象。请阅读已选择模型的 OpenAPI 文档以了解字段和验证。

类型: object

RouterModelInputSchemaDocument

描述单个模型输入与输出的独立 OpenAPI 文档。

类型：object

RouterModelListEntry

模型的 ID 与计费信息。

字段

id RouterModelId required

规范的 Comfy Router 模型 ID，格式为 {provider}/{model}，其值正是在 POST /v2/models/{provider}/{model} 上寻址该模型时所使用的值，因此调用方可以把它直接插入该路径，而无需从其他信息重新推导。它的 pattern 由 RouterProviderSegment 与 RouterModelSegment 以单个 / 连接而成，maxLength 为两者长度之和再加上该分隔符。

类型：RouterModelId，模型 ID，例如 anthropic/claude-opus-4-6，最多 193 个字符

provider RouterProviderSegment required

规范 {provider}/{model} 模型 ID 中的小写 provider 段，即被寻址模型所属的合作伙伴。调用路由的 provider 路径参数与目录条目的 provider 字段都引用这同一个 schema，这正是所列出的 ID 与所接受的 ID 不会彼此偏离的原因。

类型：RouterProviderSegment，字母数字短标识，例如 anthropic，最多 64 个字符

model RouterModelSegment required

规范 {provider}/{model} 模型 ID 中的小写 model 段，即在该提供商下要运行的模型。调用路由的 model 路径参数与目录条目的 model 字段共用它，原因与 RouterProviderSegment 相同，同样是为了避免偏离。

类型：RouterModelSegment，字母数字短标识，例如 claude-opus-4-6，最多 128 个字符

billing RouterModelBilling required

调用方在调用之前需要了解的按模型计费信息，而不是价格。用量与费用数字绝不会出现在这里。

类型：RouterModelBilling

schema\_etag string

该模型 GET /v2/models/{provider}/{model}/openapi.json 文档当前的强 ETag。在该读取请求中把它作为 If-None-Match 发送，若 schema 未变即可得到 304；也可以把它与上一次看到的值比较，从而无需抓取每个文档就能得知哪些模型的 schema 发生了变化。当此刻该读取对该调用方不会返回 200 时，该字段缺省：schema 服务不可用、该模型的文档无法渲染，或该模型在响应构建期间对此调用方变为不可用。标签缺省并不代表 schema 发生了变化；重新读取该模型的文档即可获知其当前标签。

RouterModelListResponse

Router 模型目录中的一页。

字段

data array of RouterModelListEntry required

本页包含的模型，最多 limit 个。

类型：由 RouterModelListEntry 组成的数组

has\_more boolean required

本页之后是否还有下一页。只要该值仍为 true 就继续遍历；不要因为 data 很短或为空就推断目录已经结束。

next\_cursor RouterPageCursor

指向 Router 列表的不透明游标。它由服务器生成，只用于原样回传：它不是偏移量，不是模型 ID，没有顺序，也不会在目录重建后保持稳定，因此解析它、对它做自增，或在产生它的那次遍历之外持久化它，都属于约定之外的做法。之所以使用游标而不是偏移量，是因为目录是一个不断变化的列表。当遍历过程中有条目被添加或删除时，偏移量遍历会静默地跳过或重复条目，而调用方无法察觉这一点。

类型：RouterPageCursor。以 next_cursor 返回的不透明游标，长度为 1–512 个字符

limit integer required

实际提供的分页大小。若请求的 limit 超过上限，会被限制为上限值而不是被拒绝，因此该值可能小于所请求的值。请用这个数字而不是你发送的数字来分页，否则你会以为收到了实际上并未返回的行。

1–100

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）所发起的取消请求。两种状态共用同一种响应体形状，而不是分别使用成功信封和错误信封，因为两者表达的是同一件事：取消操作发现了什么。让客户端必须按不同状态码解析不同类型，并不能从这种拆分中获得任何好处。

字段

request\_id RouterQueueRequestId required

一个已排队 Router 请求的标识符：调用方通过该句柄轮询、取消并获取结果。

类型：RouterQueueRequestId -- pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$，uuid，最多 36 个字符

status RouterQueueCancelStatus required

取消请求所发现的结果，适用于描述此路由实际处理过的请求的两种结果。两者都会反映在 HTTP 状态中，因此客户端可依据任一者进行分支。

类型：RouterQueueCancelStatus

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 块的那另一半：一个已入队请求的身份标识、它当前的状态，以及（当该状态为终端且本次运行未成功时）说明原因的粗粒度分类。

字段

request\_id RouterQueueRequestId required

一个已入队 Router 请求的标识符：调用方通过它来轮询、取消并获取结果。

类型：RouterQueueRequestId -- pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$，uuid，最多 36 个字符

status RouterQueueStatus required

一个已入队 Router 请求的状态。它恰好有三个值，并且与 RouterErrorType 不同，这个类型是封闭的 enum，因为这两个 schema 是被有意设计成朝相反方向封闭的。RouterErrorType 用于对失败进行分类，其取值集合预期会增长，因此一个会硬性拒绝无法识别分类的已生成客户端，恰恰会在已经出问题时失败得最严重。而这个是生命周期，日后若为其添加第四种状态，无论是否声明为 enum，都会构成对基于它编写的每一个轮询循环的破坏性变更。因此它被声明为 enum，并把这一约束写在客户端能看到的地方。

类型：RouterQueueStatus

queue\_position RouterQueuePosition

在响应组装完成的那一刻，队列中有多少个请求排在该请求之前。零表示该请求位于队首。

类型：RouterQueuePosition -- 至少为 0

error\_type RouterErrorType

仅出现在未成功的 COMPLETED 请求上，携带的粗粒度分类与读取结果在返回该失败时写入 X-Comfy-Error-Type 的分类相同。它正是用来把成功的终端请求与失败或已取消的终端请求区分开来的：这两种情况都没有单独的终端状态。成功时该字段是缺失的而非 null，因此应依据它是否存在来分支。

类型：RouterErrorType

RouterQueueStatusResponse

一个已排队请求的当前状态，与提交时返回的同样三个 URL 组合在一起。

组合了 RouterQueueUrls 和 RouterQueueStatusFields。

类型：object

RouterQueueSubmitFields

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

字段

request\_id RouterQueueRequestId required

一个已排队的 Router 请求的标识符，也是调用方用来轮询、取消和获取结果的句柄。

Type: RouterQueueRequestId -- pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$, uuid, 最多 36 个字符

status RouterQueueStatus required

已排队的 Router 请求的状态。它恰好有三个取值，并且与 RouterErrorType 不同，这一个采用封闭的 enum，因为这两个 schema 是刻意朝相反方向封闭的。RouterErrorType 用于对失败进行分类，其取值集合预期会增长，所以，如果一个生成的客户端硬性拒绝无法识别的类别，那么它恰恰会在已经有东西出错时失败得最严重。而这一个描述的是一段生命周期，日后若为它增加第四个状态，对每一个基于它编写的轮询循环来说都是破坏性变更，无论它是否被声明为 enum 都是如此。因此它被声明为 enum，并且把这一约束写在客户端能看到的地方。

Type: RouterQueueStatus

queue\_position RouterQueuePosition

在响应生成的那一刻，队列中有多少个请求排在这一个之前。零表示此请求位于队首。

Type: RouterQueuePosition -- 至少为 0

estimate RouterCostEstimate

此请求的预检成本估算。当调用方启用了成本估算时，新请求被接纳时会带上该字段。它报出的是此请求所固定到的提供商分支（队列没有回退循环，因此 fallback_provider 永远不会改变实际运行的分支）。当无法给出数值时，该字段依然存在，其值为 source: unknown；提交绝不会因为估算而失败。在幂等重放（Idempotent-Replayed: true）时省略，因为原始报价不会被存储。它是估算值，不是最终收费，也不是价格锁定：运行会按计费时生效的费率计费，而你工作区用量与账单记录中的结算金额才是最终结果。

Type: RouterCostEstimate

RouterQueueSubmitResponse

当一次运行被接纳进入队列时返回的句柄：包含该请求的身份与状态，并与另外三个用于访问其生命周期其余部分的 URL 组合在一起。

组合了 RouterQueueUrls 与 RouterQueueSubmitFields。

类型：object

RouterQueueUrls

这三个 URL 用于访问某个排队请求剩余生命周期中的其他资源，凡是携带有效句柄的响应都会返回它们，这样客户端就无需自行拼接队列 URL。

字段

status\_url string required

读取此请求状态的绝对 URL。

URI

response\_url string required

获取此请求结果的绝对 URL。

URI

cancel\_url string required

请求取消操作所使用的绝对 URL。

URI

RouterValidationErrorContext

提供商提供的关于验证规则失败原因的详情。

类型：object

RouterValidationErrorDetail

单个字段级验证失败。

字段

loc array of any required

出错字段的路径，最外层片段在前。例如 ["body", "image_url"]，或 ["body", "images", 0]，其中整数用于索引数组。

msg string required

对本次单个失败的可读描述。

type string required

本次失败的具体、机器可读的原因，由提供商原样透传。类型化 SDK 异常层级正是依据该值进行分支判断；响应头中的 error_type 只是它的粗略分类。

ctx RouterValidationErrorContext

针对单个 RouterValidationErrorDetail 的受限值，由提供商逐字传递。例如与 greater_than 一同出现的 {"limit_value": 8}，与 image_too_small 一同出现的 {"min_width": 512}，或与 file_too_large 一同出现的 {"max_size_bytes": 10485760}。键集合取决于具体的提供商和错误类型，因此这里刻意设计为开放对象：把它收窄为固定字段列表，或将其并入 msg 字符串，恰恰是移植集成在编译通过后悄然丢失读取该限制值分支的典型原因。当错误类型不携带限制值时，该字段不存在。

类型：RouterValidationErrorContext

input RouterValidationErrorInput

出错的输入值，逐字回显，使调用方无需从 loc 重新推导即可看到被拒绝的内容。可为任意 JSON 类型，包括字符串、数字、布尔、数组、对象或 null，因此该 schema 刻意不限定类型，而非收窄为对象。当提供商不回显输入时，该字段不存在。

类型：RouterValidationErrorInput

RouterValidationErrorInput

被拒绝的输入值，前提是提供商提供了该值。

RouterValidationErrorResponse

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

字段

detail array of RouterValidationErrorDetail required

请求中发现的每一个验证失败，每个违规字段对应一个条目。

类型：数组，元素为 RouterValidationErrorDetail