Comfy Router 的能力与限制

选择 Comfy Router 还是合作伙伴代理，为长时间运行的调用做好规划，并了解恢复、速率限制与资产存储。

Router 通过一次同步 HTTP 调用运行合作伙伴模型，或通过一个已排队的请求运行：你提交请求，稍后再收集结果。当你的应用能够等待一个已完成的结果，或稍后收集结果，并且能够处理模型自身的输入和输出字段时，就使用它。

Router 支持的功能

队列提交

同步路由在模型运行期间会一直保持连接；对于异步提供商，Router 会提交任务并在内部轮询。排队式投递（提交、获取 request_id、轮询、收集）则是另一种选择：参见队列投递。它的作用域限定在凭据所属的工作区内，因此需要使用在你的 Comfy 工作区中创建的密钥。没有工作区的传统密钥、自带密钥的请求，或队列无法运行的模型，都会在提交路由上返回 403 和 not_enabled。两种模式都不提供回调或 webhook。

如果你的请求无法保持打开足够长的时间，就把它放入队列。当你需要使用提供商自己的提交与轮询控制时，请使用合作伙伴代理。

目前有四个模型仅支持同步方式，若将它们提交到队列，会被以 403 / not_enabled 拒绝：elevenlabs/eleven_sfx_v2、elevenlabs/eleven_v3、elevenlabs/eleven_v4 和 elevenlabs/eleven_v4_turbo。它们返回的是原始音频字节，而不是 JSON 结果文档，队列投递无处存储这些内容。请在同步路由上运行它们，该路由会正常返回这些字节。

LTX v1 的文生视频和图生视频操作出于同样的原因返回原始视频字节，队列投递同样无法存储它们，但它们只能通过位于 /proxy/ltx/v1/… 的合作伙伴代理访问，而不能通过 Router 模型 ID 访问：每个 ltx/* 目录模型都会解析为可排队的 v2 提交与轮询操作。

调用会在服务器截止时间被中断

Router 的默认截止时间是 10 分钟，具体可由部署方配置。该时间从请求到达时开始计算，因此请求上传也计入其中：如果请求体届时尚未完全到达，Router 会在向提供商发起任何调用之前返回 504 / deadline_exceeded；剩余时间不足以完成调用时也会以同样方式拒绝。请将客户端超时设置为大于该值，这样 Router 才能先返回它自己的错误和请求 ID。

504 / deadline_exceeded 表示 Router 停止了等待；504 / provider_timeout 表示提供商超时。超时或连接中断并不能证明某次生成未被计费，也不会取消提供商已接受的工作。在重试之前，请先阅读超时与收集。

恢复取决于提供商

只要提供商接受了提交，Router 就会为“提交并轮询”式生成保留提供商句柄。如果在此之后连接中断，使用相同的 Idempotency-Key 和相同的请求体重新发送，会取回原始生成的结果，而不是启动第二次生成，也不会再次计费。当 Router 结束调用时（自身的截止时间，或你的客户端挂断）这一行为成立；在几乎所有情况下，处理该调用的 Router 服务器在调用中途重新启动时也同样成立。例外情况是：在提供商接受提交与 Router 记录该提交之间的短暂瞬间发生重新启动，此时该 key 会被保留最多 15 分钟，超过之后重新发送就会启动一次新的生成并产生费用。重新启动之后，在 Router 确认原始处理程序已消失的过程中，重新发送可能会在最长约一分钟内收到 409 / concurrency_limit_exceeded 以及 Retry-After；持续用同一个 key 重新发送，即可取回结果。已完成且可重放的响应也可以来自该 key 记录。

并非每个已断开连接的调用都可恢复。请在发送之前保存请求和 key，然后查阅重试结果表。使用新的 key 会创建新的调用，并可能产生额外费用。

请求正文设有上限

Router 会拒绝正文大于 100 MiB（104,857,600 字节） 的请求。该上限针对你发送的原始字节，在 Router 解析任何内容之前测量，因此适用于所有路由，也适用于同步投递与队列投递。

调用方通常会在内联媒体上遇到这一限制。Base64 编码会将二进制数据膨胀约 4/3，因此，携带编码媒体的正文在实际图像、音频或视频字节约为 75 MB 时仍能通过上限。要按编码后的字符串计算大小，而不是按磁盘上的文件，并统计一次调用中的所有输入：一个携带两张参考图像的请求会同时在两者上消耗额度，提示词、参数和 JSON 结构也计入其中。

拒绝的形态。 返回 413，并在 X-Comfy-Error-Type 上带有 invalid_input，X-Comfy-Request-Id 也像其他任何响应一样设置。正文是一个 RouterErrorResponse，其 detail 描述被超出的是哪项上限。应根据 error_type 进行分支处理，而不是解析 detail；如果 API 返回值与本文在数值上出现分歧，以 API 返回值为准。Router 在分发任何内容之前就抛出拒绝，因此没有运行生成，也没有产生费用。

该上限适用于每个请求，无论其是否携带 Idempotency-Key。它不是幂等性限制，重新发送相同的键不会改变结果：过大的正文在每次尝试时都过大。

提供商可能会施加自己的更低限制，而在这一上限处通常正是如此。 提供商发布各自对内联媒体的上限，具有约束力的限制取两者中较小者。例如，Google 的模型最多接受 20 MB（十进制，20,000,000 字节）的内联负载，Google 模型页面上的 Size limit: 20MB 一行，就是引自 Google 自身规范的 Google 逐字段限制，而不是 Router 对整个请求正文的限制。Router 的上限被有意设在其所对接的每一项合作伙伴限制之上，因此对于单个内联资产，通常你先碰到的是提供商自己的限制；而 Router 的上限在单次正文包含多个资产时才会起作用。能通过 Router 的上限但超出提供商自身限制的正文，会被提供商而非 Router 拒绝，并会作为提供商错误返回，而不是 413。

请求按调用方进行速率限制

请求速率限制适用于 Router 的每一项操作：调用、目录和 schema 读取、成本估算，以及排队请求的提交、状态查询、结果读取和取消调用，还包括在生成之前即被拒绝的请求。它依据经过身份验证的调用方计算，而不是按来源 IP 计算。使用调用方自己的提供商密钥发起的调用不受此限制；提供商侧的限制仍然适用。轮询排队中的请求会像其他任何调用一样消耗相同的额度，因此应按状态读取所建议的间隔进行轮询，而不是以紧凑循环的方式轮询。rate_limited 拒绝不会改变排队中请求的任何状态：该请求会继续运行，而被拒绝的取消调用没有取消任何内容，因此请在 Retry-After 之后再次发送取消请求。

缓存目录和 schema 读取结果。使用 ETag 和 If-None-Match 重新验证这些结果。有关重试和承诺支出字段的说明，请参阅响应头。

调用运行期间没有进度更新

Router 只返回最终响应，不提供流式 token、服务器发送事件、百分比更新或中间预览帧。在请求过程中，提供商的内部轮询状态不会被转发。

请显示一个不确定进度的指示器。如果你需要进度或流式输出，请使用能够暴露这些信息的合作伙伴代理操作。

Comfy 费用与用量

响应中可能包含提供商的用量或成本字段，但它们并不代表通用的 Comfy 收费。X-Comfy-Credits-Used 是可选响应头：缺失该响应头意味着成本未被报告，而不是该次运行免费。重放的响应（Idempotent-Replayed: true）不会再次计费，但可能重复给出原始运行的数字，因此不要将同一个 Idempotency-Key 的多次重试中的该响应头累加。请使用 Comfy 平台查询余额、用量和发票。

模型目录提供计费事实，包括 billing.charges_on_policy_rejection，但不提供价格。请显式处理 yes、no 和 unknown。当该值为 yes 时，同步的 content_policy_violation 错误可能带有 X-Comfy-Credits-Used：当提供商拒绝了模型已生成的输出、且 Comfy 为该被拒绝的生成记录了用量时，就会带上该响应头，并包含该数量。输入端拒绝、同一密钥的重放，以及金额过小、无法在响应头的两位小数中显示的收费，都不会带有该响应头；没有该响应头的拒绝表示未报告，而不是免费。参见计费。

要在运行之前了解价格，可以调用 POST /v2/models/{provider}/{model}/estimate，或读取已排队提交的 201 响应中的 estimate 对象。如果某个部署关闭了估算功能，该路由会返回 403，并附带 error_type: not_enabled，同时提交响应中会省略 estimate。两者的价格都取 Comfy 的标准目录价（对按供应商报告的成本计费的模型，则改为依据供应商公布的价格表定价：当该价格表完全决定了金额时，对一小批选择加入的模型标记为 exact，否则标记为 estimated，其中也包括部分本可由该价格表完全确定金额的报价），且不反映合同价格或客户特定费率：拥有议定价格的工作区会按目录价给出报价，但按合同费率计费。该数字只是估算值，并非最终收费；你工作区的用量与计费记录中的结算金额才是最终结果。它也不是价格锁定。使用你自己的提供商密钥运行不会被 Comfy 计费，即使 /estimate 为其返回了数字；而 unknown 估算不包含任何数字，这并不意味着免费。X-Comfy-Credits-Used 仍然只是一次运行的事后四舍五入数字，而不是收据。关于如何解读 exact、estimated 和 unknown，参见预检成本估算。无法在运行前定价的模型列在没有预检估算的模型中。

无法预先估算的模型

Router 目前还无法在运行前可靠地为对以下模型的调用定价，因此对于这些模型，/estimate 以及排队提交的 estimate 都会返回 source: unknown，不过其中一些模型针对特定请求体可能会返回具体数额。unknown 表示未给出数额，而不是说明该次运行免费。Comfy 计费与用量 规则仍然适用：使用你自己的提供商密钥运行不会由 Comfy 计费，并且 X-Comfy-Credits-Used 是可选的，因此缺少该响应头意味着费用未被报告。未列在此处的模型针对特定请求体同样可能返回 unknown，所以请对每次估算都查看 source。

随着估算覆盖范围不断扩大，这个列表会逐渐缩短。它由 Router 自身的定价代码生成，且未公开提供的模型永远不会被列出。

• bfl: bfl/erase-v1, bfl/video-edit-v1, bfl/video-upscale-v1, bfl/vto-v1
• fal: fal/fal-seedance-2.0, fal/fal-seedance-2.5
• freepik: freepik/ai-image-upscaler-precision-v2, freepik/ai-skin-enhancer-creative, freepik/ai-skin-enhancer-faithful, freepik/ai-skin-enhancer-flexible
• heygen: heygen/starfish
• ideogram: ideogram/ideogram-v3, ideogram/ideogram-v4
• kling: kling/kling-4.0, kling/kling-image-o1, kling/videos-avatar-image2video, kling/videos-lip-sync
• moonvalley: moonvalley/image-to-video, moonvalley/text-to-video, moonvalley/video-to-video
• openai: openai/gpt-image-1.5
• openrouter: openrouter/chat-completions
• pika: pika/pika-gpt-image-2, pika/pika-nano-banana-2, pika/pika-nano-banana-pro
• runware: runware/runware-gpt-image-2, runware/runware-gpt-image-2.5-flare, runware/runware-gpt-image-2.5-sunburst, runware/runware-nano-banana-2, runware/runware-nano-banana-pro, runware/runware-seedance-2.0, runware/runware-seedance-2.5
• synclabs: synclabs/sync-3
• wavespeed: wavespeed/wavespeed-gpt-image-2, wavespeed/wavespeed-gpt-image-2.5-flare, wavespeed/wavespeed-gpt-image-2.5-sunburst

对 openai/gpt-image-2、openai/gpt-image-2.5-flare、openai/gpt-image-2.5-sunburst、openai/gpt-image-2.6-flare 和 openai/gpt-image-2.6-sunburst 的编辑操作同样没有预先估算。对这些模型发起编辑调用，或发起携带输入图像的生成调用，都会返回 source: unknown。对它们发起仅含文本的生成调用则可以估算，这就是它们未出现在上述列表中的原因。

Router 并不覆盖每一项合作伙伴操作

Router 负责运行模型。文件上传、账户读取、资产管理、流式传输以及提供商任务控制可能需要位于 /proxy/… 下的合作伙伴代理路由，这些路由处在 Router 之外，Router 的契约也不涵盖它们。Router 自身对外提供的接口以 Comfy Router 规范 为准；支持情况因提供商而异。

Krea 3 参考图像：先上传，或使用公共 https URL

在 krea/krea-3 的 image_urls 中，由 POST /proxy/krea/assets 返回的 image_url（即 https://app-uploads.krea.ai/... 形式的 URL）始终会被接受。其他链接是否被接受取决于环境；在 api.comfy.org 上，目前是接受的。

• 在接受其他链接的环境中，任何公共 https 图片网址都可以使用。Router 会在模型运行前读取每张图像的尺寸：主机无法公开访问或不存在、返回除 408 或 429 之外的 4xx、或者本身并非图像的链接，会被拒绝并返回 400 invalid_input，同时指出其主机名。临时的 DNS、TLS 或连接故障、超时，或源站返回 408 或 429，会以 502 错误失败。并非有效上传的 app-uploads.krea.ai 链接，会像其他任何无法访问的引用一样被拒绝并返回 400。服务器刚启动之后、尚未确定适用哪条规则之前，不是 app-uploads.krea.ai 链接的公共 https URL 可能会失败并返回 503，该错误可以安全重试。
• 在不接受其他链接的环境中，每一项都必须是某次上传得到的 image_url。Router 只检查该链接能否解析为 https URL，且其主机名恰好是 app-uploads.krea.ai（不能是其他主机，也不能带显式端口）：任何其他链接，包括你自己托管的公共 https URL，都会在模型运行前被拒绝并返回 400 invalid_input。通过了该检查但并非有效上传（已过期、已删除或输入有误）的链接仍会通过，随后 Router 无法读取图像尺寸，并返回 5xx 错误，而不是 400。

上传在所有环境中都可用，因此是可移植的选择；请始终原样传入上传返回的 image_url。

1. 将每张参考图像以 multipart/form-data 上传，图像放在表单字段 file 中（JPEG、PNG 或 WebP，最大 75 MB）。使用与 Router 相同的方式进行身份验证，即使用 X-API-Key 或 Authorization: Bearer。

``bash theme={null} curl -X POST https://api.comfy.org/proxy/krea/assets \ -H "X-API-Key: $COMFY_API_KEY" \ -F "file=@reference.png" ``

1. 从 JSON 响应中读取 image_url，并将其传入 image_urls：

``json theme={null} { "prompt": "Place the product on a clean studio background", "resolution": "1k", "image_urls": ["<image_url from step 1>"] } ``

文生图调用会省略 image_urls，无需上传。

模型输出与存储资产

输入和输出字段因模型而异。从提供商 SDK 或代理迁移时，路由方式以及结果读取方式都可能发生变化。

部分资产会重新托管到 Comfy 存储上，其他资产则是提供商 URL 或内联字节。关于生命周期和重放行为，请参阅结果资产。

下一步

[card] 快速入门 通过 Comfy Router 生成你的第一张图像。

[card] 使用 Router API 选择一个模型、查看其 schema，并处理结果与重试。