跳转到主要内容
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。 参数
RouterPageCursor
不透明的分页游标。类型:RouterPageCursor。作为 next_cursor 返回的不透明游标,长度为 1–512 个字符
integer
每页返回的模型数量。最多 100,默认值:20
string
调用方从先前的 200 响应中持有的 ETag。
响应
RouterModelListResponse
OK:模型目录中的一页。响应体:RouterModelListResponse。响应头:X-Comfy-Request-Id、ETag、Cache-Control
no body
Not Modified:自调用方在 If-None-Match 中发送的 ETag 以来,该页面未发生变化。响应头:X-Comfy-Request-Id、ETag、Cache-Control
RouterErrorResponse
请求无效。请检查错误类型和请求体。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
凭证缺失或无效。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
该调用方或模型不允许此请求。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
rate_limited:该调用方的请求配额已用尽。请等待 Retry-After 之后再发送下一个请求。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After
RouterErrorResponse
Router 暂时不可用。请使用退避策略重试。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id

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

按规范模型 ID 读取一个合作伙伴模型的目录条目。 无需列出完整目录,即可读取单个模型的详情。 参数
RouterProviderSegment
必填
规范 {provider}/{model} 模型 ID 中的提供商部分。类型:RouterProviderSegment,字母数字 slug,例如 anthropic,最多 64 个字符
RouterModelSegment
必填
规范 {provider}/{model} 模型 ID 中的模型部分。类型:RouterModelSegment,字母数字 slug,例如 claude-opus-4-6,最多 128 个字符
string
调用方从先前的 200 响应中持有的 ETag。
响应
RouterModelDetail
OK:该模型的目录条目。响应体:RouterModelDetail,响应头:X-Comfy-Request-Id、ETag、Cache-Control
no body
未修改:自调用方在 If-None-Match 中发送的 ETag 以来,该条目未发生变化。响应头:X-Comfy-Request-Id、ETag、Cache-Control
RouterErrorResponse
凭据缺失或无效。响应体:RouterErrorResponse,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
该请求对此调用方或模型不被允许。响应体:RouterErrorResponse,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
未找到该模型 ID。响应体:RouterErrorResponse,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
rate_limited:每个调用方的请求额度已用完。请等待 Retry-After 后再发送下一个请求。响应体:RouterErrorResponse,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After
RouterErrorResponse
Router 暂时不可用。请以退避方式重试。响应体:RouterErrorResponse,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id

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

按规范模型 ID 同步运行合作伙伴模型。 运行一个模型,并在同一个响应中收到其已完成的结果。 参数
RouterProviderSegment
必填
规范 {provider}/{model} 模型 ID 中的提供商部分。类型:RouterProviderSegment — 字母数字 slug,例如 anthropic,最长 64 个字符
RouterModelSegment
必填
规范 {provider}/{model} 模型 ID 中的模型部分。类型:RouterModelSegment — 字母数字 slug,例如 claude-opus-4-6,最长 128 个字符
string
由调用方生成的键,用于让同一次逻辑调用的重试变得安全。1–255 个字符
string
选择另一个提供商来为这个模型提供服务,而不是使用其当前默认提供商;fal、wavespeed、runware 和 higgsfield 是备选提供商,GET /v2/models/{provider}/{model} 会报告某个模型支持其中的哪些。它的各种拒绝按固定顺序检查,靠前的拒绝无论靠后的拒绝是否成立都会给出答复:无法识别的值(根本不是已注册的提供商)会被拒绝 400;接着,在请求体选择了 multipart 操作(编辑)的请求上指定备选提供商会以 409 拒绝,detail 以 “this request’s image selects the edit operation” 开头,但仅当该提供商针对此模型的转换器无法服务该操作时才会如此,若某条链路的转换器确实承载该媒体,则正常继续;接着,在任何解析到自带密钥凭据的请求上指定备选提供商会以 409 拒绝,detail 以 this request resolved a BYOK credential 开头(见该响应),无论该提供商是否服务此模型;接着是被指名提供商自身的门控:当该提供商未对你开启时,它以 403 加 error_type: not_enabled 拒绝,当门控无法评估时,它以 503 加 error_type: service_unavailable 拒绝;只有在通过上述四项之后,一个对此模型没有链路的真实提供商才会以 400 加 error_type: invalid_input 被拒绝,这与无法识别的值得到的是同一个答复。在自带密钥请求上、在请求体选择了 multipart 操作的请求上以及在 strict_mode=true 下,fallback_provider 是惰性的,而不是被拒绝。
boolean
仅在与 model_provider 一起使用时才有意义。默认值:False
string
控制当首次尝试因可归因于 Router 或所尝试提供商的原因而失败时,Router 是否针对该模型的另一个已注册提供商重试此调用。省略该参数,或传入 false 以外的任何值,都会保持回退开启;false 会将其关闭。成功的回退响应会带有 X-Comfy-Router-Fallback-Provider。在解析到自带密钥凭据的请求上,无论此参数说什么,回退都不可用:该尝试根本不会发起,首次失败会原样返回给你,这属于惰性而非拒绝:不会由此产生 409。出于同样的原因,在请求体选择了 multipart 操作的请求上以及在 strict_mode=true 下也是如此:这两种情况都把该调用绑定到某一个提供商,无法忠实地在另一个提供商上重放,因此回退只是被跳过,而不是被拒绝。只有显式指定 model_provider 才会以那个 409 被拒绝,而且与这种无条件的跳过不同,它的 multipart 409 只适用于转换器无法服务该操作的链路。
boolean
选择拒绝此模型的输入 schema 未声明的顶层请求体字段,而不是接受它;嵌套字段不会被检查,对于其 schema 允许未声明字段或没有编写 schema 的模型,或在以 strict_mode=true 发送的排队提交上,都不会拒绝任何内容。默认值:False
请求体 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 选择了备选提供商时,每一种带条件的操作都可能按该提供商自身的费率计费。 响应
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
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
RouterErrorResponse
凭据缺失或无效。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
Router 请求级失败:请求从未到达模型,或因模型自身未反馈的原因而失败。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
该调用方或该模型不允许发起此请求。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
未找到该模型 ID。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
请检查 X-Comfy-Error-Type:concurrency_limit_exceeded 表示原始调用仍在运行,因此请等待 Retry-After 并复用同一个键;invalid_input 则需要使用新的键。此路由上有两种 invalid_input 冲突与键完全无关,换用新键也无法解决:当请求体选择的多部分操作(编辑)是该提供商针对此模型的转换器无法处理的时,指定备用提供商的 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 时)
RouterErrorResponse
请求体过大。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterValidationErrorResponse
请求的内容未通过模型 schema 的校验。响应体:RouterValidationErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、Idempotent-Replayed
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 时)
RouterErrorResponse
无法将提供商自身的响应转换为结果(provider_error)。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、X-Comfy-Upstream-Status
RouterErrorResponse
Router 暂时不可用。请退避重试。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After(仅限容量拒绝)
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 并不是预检价格:它只有在运行被接纳并排队之后才会出现,且该运行除非在分发前被取消,否则都会被计费。 参数
RouterProviderSegment
必填
规范模型 ID {provider}/{model} 中的小写提供商段,即正在运行其模型的合作伙伴。类型:RouterProviderSegment — 字母数字短标识,例如 anthropic,最多 64 个字符
RouterModelSegment
必填
规范模型 ID {provider}/{model} 中的小写模型段,即在该提供商下要运行的模型。类型:RouterModelSegment — 字母数字短标识,例如 claude-opus-4-6,最多 128 个字符
string
选择一个替代提供商来提供此模型,而不是使用其当前默认提供商。
请求体 application/json — RouterModelInput(必填) 合作伙伴模型的原生 JSON 输入,与此模型的同步路由所接受的请求体完全相同。它按模型自身的输入 schema 进行校验,校验方式与默认运行相同(此路由不接受 strict_mode 或 reject_unknown_fields),其自身的字段(输出数量、输入图像所选定的操作)决定计价内容。 响应
RouterCostEstimate
报价。响应体:RouterCostEstimate — 响应头:X-Comfy-Request-Id
RouterErrorResponse
请求无效。请检查错误类型和请求体。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
凭证缺失或无效。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
该调用方或模型不允许发起此请求。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
未找到该模型 ID。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
请求体过大。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterValidationErrorResponse
估算的请求体未通过模型 schema 校验,或指定的模型与路径中的模型不一致。响应体:RouterValidationErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
rate_limited:按调用方计算的请求额度已用尽。请等待 Retry-After 后再发送下一个请求。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After
RouterErrorResponse
Router 暂时不可用。请退避重试。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After(仅容量拒绝时)
RouterErrorResponse
请求超出了截止时间。重试前请检查错误类型。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id

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

以 OpenAPI 文档形式读取单个合作伙伴模型的输入和输出 schema。 以独立的 OpenAPI 文档形式读取单个模型的输入和输出 schema。 参数
RouterProviderSegment
必填
规范模型 ID {provider}/{model} 中的提供商部分。类型:RouterProviderSegment — 字母数字 slug,例如 anthropic,最多 64 个字符
RouterModelSegment
必填
规范模型 ID {provider}/{model} 中的模型部分。类型:RouterModelSegment — 字母数字 slug,例如 claude-opus-4-6,最多 128 个字符
string
调用方此前从 200 响应中持有的 ETag。
响应
RouterModelInputSchemaDocument
OK - 该模型的输入和输出 schema,以独立的 OpenAPI 文档形式返回。响应体:RouterModelInputSchemaDocument — 响应头:X-Comfy-Request-Id、ETag、Cache-Control
no body
Not Modified - 自调用方在 If-None-Match 中发送的 ETag 以来,该文档未发生变化。响应头:X-Comfy-Request-Id、ETag、Cache-Control
RouterErrorResponse
凭证缺失或无效。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
该调用方或该模型不允许此请求。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
未找到该模型 ID。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
Router 无法完成该请求。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
rate_limited:该调用方的请求配额已用尽。请等待 Retry-After 后再发送下一个请求。响应体:RouterErrorResponse — 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After
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 和一个句柄,调用方稍后通过下面的三个读取接口获取结果。 参数
RouterProviderSegment
必填
规范 {provider}/{model} 模型 ID 中的小写提供商段,即正在运行其模型的合作伙伴。类型:RouterProviderSegment;字母数字 slug,例如 anthropic,最多 64 个字符
RouterModelSegment
必填
规范 {provider}/{model} 模型 ID 中的小写模型段,即在该提供商内要运行的模型。类型:RouterModelSegment;字母数字 slug,例如 claude-opus-4-6,最多 128 个字符
string
选择一个备用提供商来提供此模型,而不是其当前默认提供商。
boolean
仅在配合 model_provider 时有意义。默认:False
string
调用方生成的键,使重试同一次逻辑调用变得安全。1–255 个字符
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)。 响应
RouterQueueSubmitResponse
已创建:运行已接纳进入队列。响应体:RouterQueueSubmitResponse;响应头:X-Comfy-Request-Id、Idempotent-Replayed、X-Comfy-Router-Dropped-Params
RouterErrorResponse
凭据缺失或无效。响应体:RouterErrorResponse;响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
请求无效。请检查错误类型和请求体。响应体:RouterErrorResponse;响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
请求体过大。响应体:RouterErrorResponse;响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
Router 请求级失败:请求从未到达模型,或因模型本身未反馈的原因而失败。响应体:RouterErrorResponse;响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
此调用方或模型不允许该请求。对于合作伙伴直接以字节形式返回生成结果的模型,目前还不能排队,并会以 not_enabled 拒绝;请改用同步路由运行它。响应体:RouterErrorResponse;响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
未找到模型 ID。响应体:RouterErrorResponse;响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
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 时)
RouterValidationErrorResponse
请求内容未通过模型 schema 的校验。响应体:RouterValidationErrorResponse —— 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、Idempotent-Replayed
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 时)
RouterErrorResponse
Router 暂时不可用。请退避后重试。响应体:RouterErrorResponse —— 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After(仅容量拒绝时)
RouterErrorResponse
请求超出了某个截止时间。重试前请先检查错误类型。响应体:RouterErrorResponse —— 响应头:X-Comfy-Error-Type、X-Comfy-Request-Id

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

收集一个已提交请求的结果。 收集端点。对于已成功完成的请求,它返回合作伙伴模型自己的原生输出,与同步路由针对相同模型和相同输入所返回的 200 内容逐字节一致。因此两种投递方式产生同一种结果形状,调用方无需第二个解析器即可在两者之间切换。 参数
RouterProviderSegment
必填
规范 {provider}/{model} 模型 ID 中的小写提供商段,即正在运行其模型的合作伙伴。类型: RouterProviderSegment,字母数字 slug,例如 anthropic,最多 64 个字符
RouterModelSegment
必填
规范 {provider}/{model} 模型 ID 中的小写模型段,即在该提供商内要运行的模型。类型: RouterModelSegment,字母数字 slug,例如 claude-opus-4-6,最多 128 个字符
RouterQueueRequestId
必填
要处理的已执行请求,即提交时在响应正文中返回的 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 个字符
响应
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
RouterQueueStatusResponse
Accepted,请求尚未完成。响应体:RouterQueueStatusResponse。响应头:X-Comfy-Request-Id、Retry-After
RouterErrorResponse
凭据缺失或无效。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
该调用方或模型不允许此请求。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
未找到该模型 ID。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
Router 请求级失败:请求从未到达模型,或因模型本身未反馈的原因而失败。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
rate_limited:每个调用方的请求配额已用尽。请等待 Retry-After 之后再发送下一个请求。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After
RouterErrorResponse
Router 暂时不可用。请使用退避策略重试。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
请求处于与该操作冲突的状态。请检查错误类型。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
请求超出了截止时间。重试前请检查错误类型。响应体:RouterErrorResponse。响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
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。 参数
RouterProviderSegment
必填
规范 {provider}/{model} 模型 ID 中的小写提供商段,即正在运行其模型的合作伙伴。类型:RouterProviderSegment,字母数字短标识,例如 anthropic,最多 64 个字符
RouterModelSegment
必填
规范 {provider}/{model} 模型 ID 中的小写模型段,即在该提供商内要运行的模型。类型:RouterModelSegment,字母数字短标识,例如 claude-opus-4-6,最多 128 个字符
RouterQueueRequestId
必填
要处理的已排队请求,即提交时在响应体中返回的 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 个字符
响应
RouterQueueCancelResponse
已接受:CANCELLATION_REQUESTED。响应体:RouterQueueCancelResponse,响应头:X-Comfy-Request-Id
RouterQueueCancelResponse
冲突:ALREADY_COMPLETED。响应体:RouterQueueCancelResponse,响应头:X-Comfy-Request-Id
RouterErrorResponse
请求无效。请检查错误类型和请求体。响应体:RouterErrorResponse,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
凭据缺失或无效。响应体:RouterErrorResponse,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
该调用方或模型不允许此请求。响应体:RouterErrorResponse,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
未找到该模型 ID。响应体:RouterErrorResponse,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
rate_limited:该调用方的请求配额已用尽。请等待 Retry-After 后再发送下一个请求。响应体:RouterErrorResponse,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After
RouterErrorResponse
Router 暂时不可用。请使用退避策略重试。响应体:RouterErrorResponse,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
Router 请求级失败:请求从未到达模型,或因模型本身未报告的原因而失败。响应体:RouterErrorResponse,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id

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

读取一个已提交请求的队列状态。 这是轮询端点。它只返回请求的当前状态,从不返回结果,因此客户端无需在每次轮询时都传输输出,即可跟踪一次长时间运行的生成任务。当该端点返回 COMPLETED 时,再通过下面的读取端点一次性获取结果。 参数
RouterProviderSegment
必填
标准 {provider}/{model} 模型 ID 中的小写提供商段,即被运行的模型所属的合作伙伴。类型:RouterProviderSegment ,字母数字 slug,例如 anthropic,最多 64 个字符
RouterModelSegment
必填
标准 {provider}/{model} 模型 ID 中的小写模型段,即在该提供商内要运行的模型。类型:RouterModelSegment ,字母数字 slug,例如 claude-opus-4-6,最多 128 个字符
RouterQueueRequestId
必填
要定位的排队请求,即提交时在响应体中返回的 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 个字符
响应
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
RouterErrorResponse
凭证缺失或无效。响应体:RouterErrorResponse ,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
该调用方或模型无权发起此请求。响应体:RouterErrorResponse ,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
未找到该模型 ID。响应体:RouterErrorResponse ,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
Router 请求级别的失败:请求从未到达模型,或由于模型自身未反馈的原因而失败。响应体:RouterErrorResponse ,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
rate_limited:该调用方的请求配额已用尽。请等待 Retry-After 之后再发送下一个请求。响应体:RouterErrorResponse ,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id、Retry-After
RouterErrorResponse
Router 暂时不可用。请使用退避策略重试。响应体:RouterErrorResponse ,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
RouterErrorResponse
Router 请求级别的失败:请求从未到达模型,或由于模型自身未反馈的原因而失败。响应体:RouterErrorResponse ,响应头:X-Comfy-Error-Type、X-Comfy-Request-Id
此处的描述较为简短。模型选择、验证、重试和计费请参阅使用 Comfy Router API,请求头行为请参阅请求头。

错误分类桶

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

请求级分类桶

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

传输级分类桶

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

响应头

string
用于目录页面或条目的新鲜度指令。发送条件:200、304
string
用于所提供架构文档的新鲜度指令。发送条件:200、304
string
针对所提供响应体字节的强实体标签,用于 GET /v2/models 和 GET /v2/models/{provider}/{model}。发送条件:200、304
string
针对所提供文档字节的强实体标签,用于 GET /v2/models/{provider}/{model}/openapi.json。发送条件:200、304
boolean
当此响应来自某条 Idempotency-Key 的记录,而不是通过再次运行模型产生时,该响应头会出现并且值为 true。
integer
收到带 error_type: rate_limited 的 429 后,发送下一个请求前需要等待的秒数:即调用方每分钟请求配额恢复到足以再接纳一个请求所需的时间。发送条件:429
integer
原样重新发送同一请求前需要等待的秒数。发送条件:503
integer
下一次轮询这个已排队的请求前需要等待的秒数。发送条件:200、202
integer
使用同一个 Idempotency-Key 重试同一请求之前需要等待的秒数。发送条件:409、504
string
本次运行的费用,以 Comfy 积分计,按照扣费本身所依据的同一价目表定价。因此调用方无需自备价格表;当一次运行经由不止一个计费调用抵达提供商时,该值是这些调用的总和,而不是最后一次调用的值。
RouterErrorType
失败的粗粒度、机器可读分类,由 Router 在每个错误响应上设置。类型:RouterErrorType
string
仅在 status 为 IN_PROGRESS 的状态读取时发送,位于 X-Comfy-Estimated-Duration-Seconds 旁边:说明该生成时长估计来自哪里(不是费用估计中的 source),取值为 historical(依据近期运行实测)或 default(按媒体类型设置的兜底值,在记录的近期运行太少时使用)。
integer
仅在 status 为 IN_PROGRESS 的状态读取时发送,位于 X-Comfy-Estimated-Duration-Seconds 旁边:该生成时长估计的第 90 百分位,以整秒为单位。
integer
仅在 status 为 IN_PROGRESS 的状态读取时发送:Router 对这次生成在提供商接受之后整个运行耗时的估计,以整秒为单位(不是剩余时间,也从不包含 IN_QUEUE 中度过的时间)。
string
内容策略拒绝所针对的是哪个输入或输出,采用 Router 层面的封闭词表:input、output、input_text、input_image、input_video、input_audio、output_text、output_image、output_video、output_audio。
string
服务器为此次调用生成的标识符,存在于每一个 Router 响应中:成功、4xx 和 5xx 响应均如此,因为错误响应恰恰是用户需要在支持请求中引用某个 ID 的时候。
string
一个 JSON 编码的字符串,内含一个字符串数组。请使用 JSON 解析器来解码,而不要按逗号对其分割,因为它在传输时是单个字符串,而不是逗号分隔的 OpenAPI 数组,并且每个条目本身就是一个自带逗号的句子。当一次转换生成了本次调用的请求体,却无法在所服务的提供商上精确表达一个或多个原生字段时,该响应头就会出现,并逐一列出每个被丢弃的字段及其原因;无论调用方是通过 model_provider(strict_mode=false,默认值)请求该转换,还是由自动的 fallback_provider 重试执行了该转换,都是如此。
string
仅当 fallback_provider 确实针对第二个提供商重试了此调用,并且该重试成功时,该响应头才会出现并指明该提供商:即最终服务此调用的提供商,绝不是被尝试过但也失败了的那个。
string
服务此次调用的 Router 链路的提供商,出现在每个成功运行的响应中:原生运行时为模型自身的提供商,也可能是 model_provider 指定的备用提供商,或者是 fallback_provider 重试最终落在的提供商(仅在这种情况下 X-Comfy-Router-Fallback-Provider 也会指明它)。它代表的是 Router 派发到的链路,而不一定是产生输出的厂商,因为原生链路内部的代理级联(例如 vertexai 的 Gemini 图像链)可能把调用交给另一个厂商,而没有任何响应头会指明它。
string
模型提供商给出的、有长度限制且已脱敏的拒绝该请求的原因。
integer
模型提供商在此次调用中自身的 HTTP 状态。
integer
调用方当前已承诺给仍在途调用的美分数。
integer
调用方可承诺给仍在途调用的合作伙伴支出上限,单位为美分。这笔资金从调用被接纳的那一刻起即被保留,并在该调用结束时释放。
integer
上限之下剩余的可用额度,单位为美分,最低为零。
string
在 Router 模型的每次成功运行中都始终为 nosniff。
integer
调用方对归为昂贵的模型的并发调用数,由拒绝此次调用的闸门统计得出。
integer
调用方一次可持有的、对归为昂贵的模型的并发调用上限,为并发调用限额的四分之一,与合作伙伴节点调用共享。
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 一同出现。 字段
string
云端工作区 id。在传统计费轨道上不存在。
string
必填
personal 或 team。这是一个开放字符串:任何其他值都按个人处理。
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。 字段
string
必填
exact | estimated | free | unknown;其他任何值都按 unknown 读取。exact 和 estimated 标注的都是估算值;两者都不是最终费用。free 表示费率卡将本次请求计价为零,因此 amount 为 “0”。unknown 不携带任何数字。
string
必填
始终为 USD。
string
估算费用,以十进制字符串表示的美元金额,例如 “0.04”,最多 8 位小数且不使用指数。可收费的亚分价格绝不会显示为 “0”;只有 free 报价才显示 “0”。仅在 source 为 exact 或 free 时出现。它不是最终费用:最终费用是工作区用量与账单记录中的结算费用。
string
估算区间的下限,以十进制字符串表示的美元金额。它是估算值,不是保底下限:一次调用的计费可能更低,例如提供商返回的内容少于请求(比如没有返回图像)、估算值是根据过往调用学到的典型价格,或价格并不随请求的数量稳步上升。仅在 source 为 estimated 时出现。
string
估算区间的上限,以十进制字符串表示的美元金额。它是估算值,不是保底上限:一次调用的计费可能更高,例如提供商返回的内容多于请求(比如返回的图像多于请求数量)、估算值是根据过往调用学到的,或价格并不随请求的数量稳步上升。仅在 source 为 estimated 时出现。
number
同一数字以美分表示,不四舍五入,便于算术运算。与 amount 一同出现。double
number
min_amount 以美分表示,不四舍五入。与 min_amount 一同出现。double
number
max_amount 以美分表示。与 max_amount 一同出现。double
number
amount 按平台换算($1 = 211 积分)折算成的 Comfy 积分数,四舍五入到 2 位小数,也就是 exact 报价下 X-Comfy-Credits-Used 预期携带的数字。该响应头是四舍五入的事后数字,不是收据;工作区用量与账单记录中的结算费用才是最终结果。double
string
必填
本次报价对应的提供商环节。在已排队的提交中,它就是将要运行的环节。
RouterModelId
必填
规范的 Comfy Router 模型 ID,即 {provider}/{model},它正是用于在 POST /v2/models/{provider}/{model} 上寻址该模型的值,因此调用方可以直接把它插入该路径,无需从其他信息重新推导。其 pattern 由 RouterProviderSegment 和 RouterModelSegment 以单个 / 连接而成,maxLength 为两者长度之和再加上该分隔符。类型:RouterModelId — 模型 ID,例如 anthropic/claude-opus-4-6,最长 193 个字符
string
必填
本次报价所依据的费率卡的获取时间。估算不是价格锁定:运行按计费时生效的费率收费,而不是按这一时刻的费率。取自厂商公布价格表的 estimated 报价(即按厂商上报成本计费的模型)携带的则是读取该价格表的日期。如果一笔报价的计费数量是根据公布的厂商价目表预测、再按费率卡定价的,那么无论最终答案是 exact 还是 estimated(按厂商上报积分计费的模型属于 estimated 情形),它携带的都是该价目表读取日期与费率卡获取时间中较早的那个。如果根本没有读取任何费率卡(reason: pricing_unavailable、byok,或无法从任何费率卡定价的 not_quotable 调用),则此处是给出该报价的时间。date-time
string
仅当 source 为 unknown 时出现:not_quotable(Router 无法在调用运行之前为其定价,价格取决于提供商回传的内容,或者请求体未限定计费数量)、unpriced_model(费率卡片未对该请求定价)、byok(仅适用于已执行提交:该运行使用你自己的提供商密钥,因此 Comfy 不为此计费),或 pricing_unavailable(仅适用于已执行提交:请求被受理时无法读取费率卡片;这是暂时性的,该运行仍照常计费)。读取到任何其他值时,一律视为 not_quotable。

RouterErrorResponse

用于认证、访问、模型查找、配额以及提供商传输失败的错误响应体。 字段
string
必填
人类可读的失败描述,可安全展示给最终用户。它不会被机器解析,请改为根据 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 都是 key 冲突。这两个前缀都是稳定的契约条款,可以被匹配。除此之外,任何其他位置根据 detail 分支都不提供兼容性保证。
RouterErrorType
必填
针对 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
string
invalid_input 拒绝的有界、已脱敏的原因。在同步路由上,它是模型提供商给出的原因,仅当 error_type 为 invalid_input 且 X-Comfy-Upstream-Status 是提供商的 4xx 或 2xx 时存在,即提供商以请求格式错误为由拒绝了请求并说明了原因。通常该状态是 4xx;对于在成功信封内报告生成被拒的提供商,它是 2xx(BytePlus 的失败任务轮询是 HTTP 200,原因在其响应体中)。该字段在其他所有失败中都不存在,包括提供商的 5xx、传输失败、内容策略拒绝以及 Router 就自身提出的任何拒绝,并且它与 X-Comfy-Upstream-Detail 头一致。以 invalid_input 结束的运行,其队列收集(GET /v2/models/{provider}/{model}/requests/{request_id})会在首次收集时在此字段中携带相同原因,随后将其从请求中删除:后续收集通常返回相同的 error_type 和 detail 但不含该字段,因此请从首次收集读取它。那次读取不会发送这两个头。当 Router 在把请求发送给提供商之前就将其拒绝、并能用一句话说明原因时,队列收集也会用此字段承载 Router 自身的原因,而同步路由会在 detail 中返回该原因;指名了各个字段的拒绝则不携带任何内容。
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 头一致。
string
计费针对合作伙伴节点花费拒绝的策略分支:当被计费的钱包为空时为 no_funds,当调用被拒但没有任何资金读数说明原因时为 unspecified。仅当 error_type 为 insufficient_credits 且部署会上报钱包事实时存在;否则不存在。它是机器可读代码,而非展示文本:展示 detail,对此字段分支。
RouterBilledWorkspace
被拒调用本应扣费的钱包,位于 RouterErrorResponse.billed_workspace。它回答“哪个钱包是空的?”:它不一定是调用方 UI 当前选中的工作区;即使打开了资金充足的团队,团队成员的个人凭证也会在此指明其个人钱包。仅与 denied_reason 一同存在。类型:RouterBilledWorkspace
string
被拒绝的请求通过哪种方式完成认证:personal_api_key、team_api_key、personal_session 或 team_session。用于回答“我该切换到哪个凭据,才能向另一个钱包计费?”。它并非权限,也不授予任何权限。仅与 denied_reason 一同出现。

RouterErrorType

机器可读的 Router 错误类别,同时也会随 X-Comfy-Error-Type 响应头一同发送。 类型:string

RouterModelBilling

在调用模型之前需要检查的计费行为。不包含价格或用量。 字段
RouterChargesOnPolicyRejection
必填
当此模型因内容政策原因拒绝某次调用时,该调用是否仍会向调用方收费。各提供商的做法不同,这种差异在调用时不可见,而用户若在同一次调用中既看到错误又看到扣费,也无从事先知晓。因此这里要在调用前按模型明确说明,而不是依赖各提供商各自的惯例。当其值为 yes 时,同步路由上的 content_policy_violation 错误可能会携带 X-Comfy-Credits-Used:当提供商拒绝的是模型生成的输出,且 Comfy 已记录该次被拒绝生成的用量时,它会携带该响应头,并包含相应数量。输入端拒绝、同一密钥的重放(Idempotent-Replayed: true)以及金额过小、无法在响应头的两位小数中显示的收费都不会携带该响应头;未携带该响应头的拒绝不会被报告,但这并不能证明它是免费的。类型:RouterChargesOnPolicyRejection

RouterModelDetail

单个 Comfy Router 模型的按模型详情:目录列表为其报告的全部内容,以及只有单模型路由才会携带的按模型字段。 由 RouterModelListEntry、RouterModelDetailFields 组合而成。 类型:object

RouterModelDetailFields

模型详情端点返回的可选字段。 字段
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 与计费信息。 字段
RouterModelId
必填
规范的 Comfy Router 模型 ID,{provider}/{model},正是用于在 POST /v2/models/{provider}/{model} 上定位该模型的那个值,因此调用方可以直接把它插入该路径,而无需从任何其他来源重新推导。它的 pattern 是由单个 / 连接的 RouterProviderSegment 与 RouterModelSegment,而 maxLength 是两者长度之和再加上该分隔符。类型:RouterModelId,模型 ID,例如 anthropic/claude-opus-4-6,最多 193 个字符
RouterProviderSegment
必填
规范的 {provider}/{model} 模型 ID 中的小写 provider 段,即所调用模型所属的合作伙伴。调用路由的 provider 路径参数与目录条目的 provider 字段都引用这一个 schema,正是这一点使得列出的 ID 与实际接受的 ID 不会彼此漂移。类型:RouterProviderSegment,字母数字 slug,例如 anthropic,最多 64 个字符
RouterModelSegment
必填
规范的 {provider}/{model} 模型 ID 中的小写 model 段,即在该提供商内要运行的模型。与 RouterProviderSegment 出于同样的防漂移原因,它由调用路由的 model 路径参数与目录条目的 model 字段共享。类型:RouterModelSegment,字母数字 slug,例如 claude-opus-4-6,最多 128 个字符
RouterModelBilling
必填
调用方在调用之前所需的按模型计费信息,而非价格。用量与费用数据绝不会出现在这里。类型:RouterModelBilling
string
该模型 GET /v2/models/{provider}/{model}/openapi.json 文档当前的强 ETag。在对该文档的读取中把它作为 If-None-Match 发送,可在 schema 未变更时得到 304;或将它与此前见到的值比较,从而无需抓取每个文档就能得知哪些模型的 schema 发生了变化。当该读取此刻不会对这位调用方返回 200 时,该字段缺失:schema 服务不可用、该模型的文档无法渲染,或在响应构建期间该模型对这位调用方变为不可用。标签缺失并不代表 schema 发生变化;请重新读取该模型的文档以获知其当前标签。

RouterModelListResponse

Router 模型目录中的一页。 字段
array of RouterModelListEntry
必填
本页包含的模型,最多为 limit 个。类型:由 RouterModelListEntry 组成的数组
boolean
必填
本页之后是否还有另一页。只要该值为是,就应继续遍历;不要因为 data 很短或为空就推断目录已结束。
RouterPageCursor
指向 Router 列表的不透明游标。它由服务器生成,且只用于原样往返传递:它不是一个偏移量,不是模型 ID,不保证有序,也不保证在目录重建后保持稳定,因此解析它、对其自增,或在它来源的遍历之外持久化它,均超出约定范围。之所以使用游标而非偏移量,是因为目录是一个不断变化的列表:在遍历过程中添加或删除条目时,基于偏移量的遍历会静默跳过或重复条目,而调用方无法察觉这种情况。类型:RouterPageCursor — 作为 next_cursor 返回的不透明游标,长度为 1–512 个字符
integer
必填
实际提供的分页大小。若请求的 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。两种状态共用同一种响应体形状,而不是一个成功封装加一个错误封装,因为两者表达的是同一项陈述,即取消操作发现了什么;而客户端若必须按每个状态码解析不同类型,也无法从这种拆分中获得任何好处。 字段
RouterQueueRequestId
必填
一个已执行 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 个字符
RouterQueueCancelStatus
必填
取消请求所发现的内容,适用于描述此路由实际处理请求的两种结果。两者都会由 HTTP 状态反映,因此客户端可以基于任意一个进行分支。类型:RouterQueueCancelStatus

RouterQueueCancelStatus

表示取消请求所发现的结果,适用于描述此路由实际已处理请求的两种结果。这两种结果都会由 HTTP 状态码反映,因此客户端可以依据其中任一结果进行分支处理。 类型:string

RouterQueuePosition

在响应组装完成的那一刻,队列中有多少个请求排在本请求之前。值为 0 表示本请求位于队列最前端。 类型: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 块的那一半:一个排队中的请求的身份、其当前状态,以及当该状态为终态且运行未成功时,说明原因的粗粒度分类。 字段
RouterQueueRequestId
必填
一个排队中的 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 个字符
RouterQueueStatus
必填
排队中的 Router 请求的状态。它恰好有三个值,并且与 RouterErrorType 不同,这是一个封闭的 enum,因为这两个 schema 被有意设计成朝相反方向封闭。RouterErrorType 对失败进行分类,其集合预期会增长,因此,如果一个生成的客户端强硬拒绝无法识别的分类,那么恰恰会在已经出错时失败得最严重。而这一项是生命周期,日后新增第四个状态的生命周期,无论是否声明为 enum,都会是对所有针对它编写的轮询循环的破坏性变更,因此它被声明为 enum,并且该约束会在客户端能看到的地方说明。类型:RouterQueueStatus
RouterQueuePosition
在响应组装完成的那一刻,队列中有多少个请求排在此请求之前。零表示此请求位于队首。类型:RouterQueuePosition — 至少为 0
RouterErrorType
仅出现在未成功的 COMPLETED 请求上,携带的粗粒度分类与结果读取在返回该失败时放到 X-Comfy-Error-Type 上的分类相同。它用于区分已成功的终态请求与失败或已取消的请求:这两种情况都没有单独的终态状态;并且它在成功时缺失而不是为 null,因此应根据其是否存在进行分支。类型:RouterErrorType

RouterQueueStatusResponse

单个排队中请求的当前状态,由与提交时返回的相同三个 URL 组合而成。 组合了 RouterQueueUrls、RouterQueueStatusFields。 类型:object

RouterQueueSubmitFields

RouterQueueSubmitResponse 中除 URL 块之外的另一半:新请求的身份,以及它在被接纳那一刻的状态。 字段
RouterQueueRequestId
必填
标识一个已排队的 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 个字符
RouterQueueStatus
必填
排队中的 Router 请求所处的状态。它恰好有三个值,并且与 RouterErrorType 不同,这是一个封闭的 enum,因为这两个 schema 是有意朝相反方向封闭的。RouterErrorType 对失败进行分类,其取值集合预期会增长,因此如果生成的客户端硬性拒绝一个无法识别的分类,它恰恰会在已经出错的时候失败得最严重。而这里描述的是生命周期,一个日后新增第四种状态的生命周期,无论是否声明为 enum,对每一个针对它编写的轮询循环来说都是破坏性变更,因此它被声明为 enum,并把这个约束写在客户端能看到的地方。类型:RouterQueueStatus
RouterQueuePosition
在响应组装完成的那一刻,队列中有多少个请求排在这个请求前面。零表示该请求位于队首。类型:RouterQueuePosition — 至少为 0
RouterCostEstimate
此请求的预检成本估算,当调用方启用了成本估算时,新接纳的请求会带上它。它报出的是此请求所固定到的提供商侧(队列没有回退循环,因此 fallback_provider 永远不会改变实际运行的那一侧)。当无法给出数字时,它依然存在,并带有 source: unknown;提交绝不会因为估算而失败。在幂等重放(Idempotent-Replayed: true)时省略,因为原始报价不会被保存。它是估算值,不是最终费用,也不是价格锁定:运行时按计费时生效的费率收取费用,而工作区用量与账单记录中结算后的费用才是最终结果。类型:RouterCostEstimate

RouterQueueSubmitResponse

当一次运行被接纳进入队列时返回的句柄:包含该请求的标识与状态,并与用于访问其剩余生命周期的三个 URL 组合而成。 由 RouterQueueUrls、RouterQueueSubmitFields 组合而成。 类型:object

RouterQueueUrls

这三个 URL 指向某个排队中请求剩余生命周期的各个部分,会在每个携带有效句柄的响应中返回,因此客户端无需自行拼接队列 URL。 字段
string
必填
此请求状态读取的绝对 URL。URI
string
必填
此请求结果收集所在的绝对 URL。URI
string
必填
发起取消请求所用的绝对 URL。URI

RouterValidationErrorContext

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

RouterValidationErrorDetail

单个字段级验证失败。 字段
array of any
必填
指向出错字段的路径,最外层片段在前,例如 ["body", "image_url"],或 ["body", "images", 0],其中整数用于索引数组。
string
必填
对这一单次失败的人类可读描述。
string
必填
此次失败的具体的、机器可读的原因,由提供商原样透传。类型化 SDK 的异常层级正是基于该值进行分支判断;响应头中的 error_type 只是它的粗粒度分类。
RouterValidationErrorContext
针对单个 RouterValidationErrorDetail 所违反的边界,由提供商原样传递,例如 {"limit_value": 8} 配合 greater_than,{"min_width": 512} 配合 image_too_small,或 {"max_size_bytes": 10485760} 配合 file_too_large。键集合取决于具体的提供商和错误类型,因此这里刻意设计为开放对象:把它收窄为固定的字段列表,或将其并入 msg 字符串,恰恰会导致移植过来的集成在编译通过后,静默丢失了读取该边界的分支。当错误类型不携带边界时,该字段不存在。类型:RouterValidationErrorContext
RouterValidationErrorInput
出错的输入值,原样回显,使调用方无需再从 loc 重新推导即可看到被拒绝的内容。可为任意 JSON 类型,包括字符串、数字、布尔、数组、对象或 null,因此该 schema 刻意不设类型,而不是收窄为对象。当提供商不回显输入时,该字段不存在。类型:RouterValidationErrorInput

RouterValidationErrorInput

被拒绝的输入值,前提是提供商包含该值。

RouterValidationErrorResponse

422 验证错误响应体。读取 X-Comfy-Error-Type 以获取其类别。 字段
array of RouterValidationErrorDetail
必填
请求中发现的每一处验证失败,每个出错的字段对应一条记录。类型:数组,元素为 RouterValidationErrorDetail