Skip to main content
Router runs a partner model through one synchronous HTTP call or through a queued request that you submit and collect later. Use it when your application can wait for a finished result or collect one later, and can handle the model’s own input and output fields.

What Router supports

Queued submission

The synchronous route holds the connection while the model runs; for asynchronous providers, Router submits the job and polls internally. Queued delivery (submit, get a request_id, poll, collect) is the alternative: see Queued delivery. It is scoped to the workspace behind the credential, so it needs a key created in your Comfy workspace. A legacy key with no workspace, a bring-your-own-key request, or a model the queue cannot run answers 403 with not_enabled on the submit route. Neither mode offers a callback or webhook. If your request cannot stay open long enough, queue it. Use a partner proxy when you need the provider’s own submit-and-poll controls. Four models are synchronous-only for now and are refused with 403 / not_enabled if you submit them to the queue: elevenlabs/eleven_sfx_v2, elevenlabs/eleven_v3, elevenlabs/eleven_v4 and elevenlabs/eleven_v4_turbo. They answer raw audio bytes rather than a JSON result document, which queued delivery has nowhere to store. Run them on the synchronous route, which returns those bytes normally. Four models are queued-only and are refused with 403 / not_enabled on the synchronous route: ltx/ltx-video-alpha-gen, ltx/ltx-video-to-video-hdr, ltx/ltx-video-to-video-reframe and ltx/ltx-video-upscale. Their jobs can outlast the time a synchronous call is held. Submit the same body to POST /v2/models/ltx/{model}/requests and collect the result from the queue. The LTX v1 text-to-video and image-to-video operations answer raw video bytes for the same reason, and queued delivery cannot store them either — but they are reachable only through the partner proxy at /proxy/ltx/v1/…, not through a Router model id: every ltx/* catalog model resolves to the queueable v2 submit-and-poll operation.

Calls are cut off at a server deadline

Router’s default deadline is 10 minutes, configurable by the deployment. It counts from when the request arrives, so the bound includes the request upload: a body that has not fully arrived by then is answered 504 / deadline_exceeded before any partner call, and a call with too little of the deadline left to finish is refused the same way. Set your client timeout above it so Router can return its error and request ID first. 504 / deadline_exceeded means Router stopped waiting; 504 / provider_timeout means the provider timed out. A timeout or lost connection does not prove that a generation was unbilled, and it does not cancel accepted provider work. Read timeouts and collection before retrying.

Recovery depends on the provider

Router retains the provider handle for a submit-and-poll generation as soon as the provider accepts the submit. If the connection is lost after that point, a resend with the same Idempotency-Key and the same body collects the original generation instead of starting a second one, and is not charged again. This holds when Router ends the call (its deadline, or your client hanging up) and also, in almost every case, when the Router server handling the call restarts mid-call. The exception is a restart in the brief moment between the provider accepting the submit and Router recording it: the key is then held for up to 15 minutes, after which a resend starts and is charged for a new generation. After a restart, a resend can get 409 / concurrency_limit_exceeded with Retry-After for up to about a minute while Router confirms the original handler is gone; keep resending the same key and it collects the result. Completed replayable responses can also come from the key record. Not every disconnected call is recoverable. Preserve the request and key before sending, then use the retry outcome table. A new key creates a new call and may incur another charge.

Request bodies are capped

Router refuses a request whose body is larger than 100 MiB (104,857,600 bytes). The bound is on the raw bytes you send, measured before Router parses anything, so it applies to every route and to both synchronous and queued delivery. Inline media is where callers meet it. Base64 encoding inflates binary data by about 4/3, so a body carrying encoded media clears the cap at roughly 75 MB of actual image, audio, or video bytes. Size the encoded string, not the file on disk, and count every input in one call: a request carrying two reference images spends the allowance on both, and the prompt, parameters, and JSON structure count too. What the refusal looks like. 413, with invalid_input on X-Comfy-Error-Type and X-Comfy-Request-Id set as on any other response. The body is a RouterErrorResponse whose detail describes the bound that was exceeded. Branch on error_type rather than parsing detail, and treat what the API returns as authoritative if it and this page ever disagree about the figure. Router raises the refusal before dispatching anything, so no generation ran and nothing was charged. The cap applies to every request, whether or not it carries an Idempotency-Key. It is not an idempotency limit, and re-sending the same key does not change the outcome: a body that is too large is too large on every attempt. A provider can impose a lower limit of its own, and at this cap it usually does. Providers publish their own bounds on inline media, and the binding constraint is whichever is smaller. Google’s models, for example, accept up to 20 MB (decimal, 20,000,000 bytes) of inline payload, and the Size limit: 20MB line on the Google model pages is that per-field Google bound quoted from Google’s own specification, not Router’s bound on the whole request body. Router’s cap sits above every partner bound it fronts deliberately, so for a single inline asset the provider’s own limit is normally what you meet first; Router’s cap binds across several assets in one body. A body that clears Router’s cap but exceeds a provider’s own limit is refused by the provider rather than by Router, and it comes back as a provider error rather than a 413.

Requests are rate limited per caller

The request-rate limit applies to every Router operation: invocation, catalog and schema reads, cost estimates, and the queued submit, status, result, and cancel calls, including requests refused before generation. It follows the authenticated caller, not the source IP. Calls with the caller’s provider key are exempt; provider limits still apply. Polling a queued request spends the same allowance as any other call, so poll at the interval the status read suggests rather than in a tight loop. A rate_limited refusal changes nothing about a queued request: it keeps running, and a refused cancel cancelled nothing, so send it again after Retry-After. Cache catalog and schema reads. Revalidate them with ETag and If-None-Match. See Headers for retry and committed-spend fields.

No progress while a call runs

Router returns a final response, with no streamed tokens, server-sent events, percentage updates, or intermediate preview frames. A provider’s internal polling state is not forwarded during the request. Show an indeterminate progress indicator. If you need progress or streaming, use a partner-proxy operation that exposes it.

Comfy charges and usage

The response can contain provider usage or cost fields. They do not represent a universal Comfy charge. X-Comfy-Credits-Used is optional: a missing header means the cost was not reported, not that the run was free. A replayed response (Idempotent-Replayed: true) is never charged again but may restate the original run’s figure, so do not add the header up across retries of one Idempotency-Key. Use the Comfy platform for balances, usage, and invoices. The catalog provides billing facts, including billing.charges_on_policy_rejection, but no prices. Handle yes, no, and unknown explicitly. When it is yes, a synchronous content_policy_violation error can carry X-Comfy-Credits-Used: it does when the provider refused the model’s generated output and Comfy recorded usage for that refused generation, and carries that amount. An input-side refusal, a same-key replay, and a charge too small to show in the header’s two decimals do not carry it; a refusal without the header is not reported, not free. See billing. To see a price before a run, call POST /v2/models/{provider}/{model}/estimate, or read the estimate object on a queued submit’s 201. If estimates are switched off for a deployment, the route answers 403 with error_type: not_enabled and the submit omits estimate. Each is priced at Comfy’s standard list price (a model billed the cost its vendor reports is instead priced from the vendor’s published price list — exact for a small opted-in set of models when that list fully determines the figure, estimated otherwise, including some quotes the list would fully determine) and does not reflect contract or customer-specific rates: a workspace with negotiated pricing is quoted the list price and charged its contract rate. The figure is an estimate, not the final charge, and the settled charge in your workspace’s usage and billing records is final. Nor is it a price lock. A run on your own provider key is not billed by Comfy even when /estimate returns a figure for it, and an unknown estimate carries no figure; that does not mean free. X-Comfy-Credits-Used remains a rounded post-hoc figure for a run, not a receipt. See Pre-flight cost estimates for how to read exact, estimated, and unknown. The models that cannot be priced before a run are listed in models without a pre-flight estimate.

Models without a pre-flight estimate

Router cannot yet reliably price a call to the models below before it runs, so expect /estimate and a queued submit’s estimate to answer source: unknown for them, though some may return a figure for a particular body. unknown means no figure was given, not that the run is free. The Comfy charges and usage rules still apply: a run on your own provider key is not billed by Comfy, and X-Comfy-Credits-Used is optional, so a missing header means the cost was not reported. A model not listed here can still answer unknown for a particular body, so read source on every estimate. This list shrinks as estimate coverage grows. It is generated from Router’s own pricing code, and models that are not publicly available are never listed.
  • 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
  • heygen: heygen/starfish
  • ideogram: ideogram/ideogram-v3, ideogram/ideogram-v4
  • kelly: kelly/kelly-seedance-2.0, kelly/kelly-seedance-2.0-fast, kelly/kelly-seedance-2.5
  • kling: kling/kling-4.0, kling/kling-image-4.0, kling/kling-image-o1, kling/kling-long-image-4.0, kling/videos-avatar-image2video, kling/videos-lip-sync
  • ltx: ltx/ltx-video-alpha-gen, ltx/ltx-video-to-video-hdr, ltx/ltx-video-to-video-reframe, ltx/ltx-video-upscale
  • minimax: minimax/minimax-gpt-image-2, minimax/minimax-gpt-image-2.5-flare, minimax/minimax-gpt-image-2.5-sunburst, minimax/minimax-gpt-image-2.6-flare, minimax/minimax-gpt-image-2.6-sunburst, minimax/minimax-h3-image, minimax/minimax-h3-image-highspeed
  • openai: openai/gpt-image-1.5
  • openrouter: openrouter/chat-completions
  • pika: pika/pika-nano-banana-2, pika/pika-nano-banana-pro
  • pixverse: pixverse/v3.5, pixverse/v6, pixverse/v6-max
  • quiver: quiver/arrow-2, quiver/arrow-2-telos
  • 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
  • veed: veed/video-background-removal, veed/video-background-removal-fast, veed/video-background-removal-green-screen
  • wavespeed: wavespeed/wavespeed-gpt-image-2, wavespeed/wavespeed-gpt-image-2.5-flare, wavespeed/wavespeed-gpt-image-2.5-sunburst
Edits on openai/gpt-image-2, openai/gpt-image-2.5-flare, openai/gpt-image-2.5-sunburst, openai/gpt-image-2.6-flare, and openai/gpt-image-2.6-sunburst also have no pre-flight estimate. An edit call to one of these models, or a generation call that carries an input image, answers source: unknown. A text-only generation call to them is estimated, which is why they are not in the list above.

Router does not cover every partner operation

Router runs models. File uploads, account reads, asset management, streaming, and provider job controls can require partner-proxy routes under /proxy/…, which sit outside Router and are not described by its contract. Router’s own surface is the Comfy Router specification; support varies by provider.

Krea 3 reference images: upload first, or use a public https URL

In krea/krea-3’s image_urls, an image_url returned by POST /proxy/krea/assets (an https://app-uploads.krea.ai/... URL) is always accepted. Whether other links are accepted depends on the environment; on api.comfy.org they currently are. More than 8 entries is rejected with 422 before any fetch, by the request’s schema check.
  • Where other links are accepted, any public https image URL works. Router fetches each reference itself to read its size before the model runs. A reference you have to fix is rejected with 400 invalid_input naming its host: a host that does not exist or is not publicly reachable, an origin that answers with a 4xx other than 408 or 429, too many redirects, a redirect to a link that is not https or to a host that is not publicly reachable, content that is not a supported image, a response with no length that ends before the image’s size header, or an image whose size header is not within the first 2 MiB (see below). Any other fetch failure is a 5xx error instead (500 internal_error on Router). Some of those clear on their own (a DNS resolver error, a timeout, a dropped connection, an origin that answers 5xx, 408 or 429, or a host whose DNS answer switches to a non-public address between Router’s host check and its connection, which on retry can succeed or be rejected with the 400 for a non-public host), so retry them later. Others fail the same way every time, for example a TLS certificate the fetch does not trust (self-signed, expired or for the wrong host name), or an origin that answers a 2xx other than 200 or a 3xx the fetch does not follow (such as 204, 206, 300, 304 or 305, or a 301, 302, 303, 307 or 308 with no Location). If a retry fails the same way, upload the image first. A request queued with POST /v2/models/krea/krea-3/requests is not retried on such a 5xx when any of its links is not an app-uploads.krea.ai link, so resubmit it yourself if the cause can clear. An app-uploads.krea.ai link that is not a live upload is rejected with 400 like any other unreachable reference. A queued request’s 400 carries only the generic invalid_input detail, so it does not name the host, and the queue does not retry it. A queued 400 can come from any field, not only image_urls (for example an unsupported resolution or thinking_mode), so check the other fields first. If they are valid, upload each image with POST /proxy/krea/assets and resubmit with those image_url values and a new Idempotency-Key (or none): reusing the key with a changed body is refused with 409 invalid_input, which says nothing about the images, and reusing it with the same body is answered 201 with the original request_id and Idempotent-Replayed: true, so it does not start a new run, and its result URL (GET /v2/models/krea/krea-3/requests/{request_id}) returns the same 400 (its status URL answers 200 with error_type invalid_input). If that resubmit also fails with 400, the image itself is the problem (for example it is not a supported image, or its size header is not within the first 2 MiB).
  • Where other links are not accepted, every entry must be an upload’s image_url. Router checks only that the link parses as an https URL whose host is exactly app-uploads.krea.ai (no other host and no explicit port): any other link, including a public https URL you host yourself, is rejected with 400 invalid_input saying “image_urls must be image_url values returned by POST /proxy/krea/assets” before the model runs, so upload the image instead. A link that passes that check but is not a live upload (expired, deleted or mistyped) still gets past it, and Router then fails to read the image’s size and answers with a 5xx error, not a 400. An uploaded image that Router cannot read (for example it is not a supported image, or its size header is not within the first 2 MiB) also fails with a 5xx (500 internal_error on Router) here rather than a 400, and the image is still the problem, so uploading it again does not help.
  • Right after a server starts, before it has learned which rule applies, any https URL that is not an app-uploads.krea.ai link can fail with a 503 (service_unavailable on Router) that is safe to retry (a queued request is retried on it automatically).
Router reads only the first 2 MiB of each reference to find its size, so an image whose size information it cannot finish reading inside that window (for example a JPEG carrying more than 2 MiB of embedded metadata, or a paletted PNG whose transparency data, or with none the start of its first image-data chunk, sits past 2 MiB, such as after more than 2 MiB of text or color-profile chunks) is rejected with 400 saying its size header is not within the first 2 MiB, and uploading it does not help: re-save it without the large metadata first, or save a paletted PNG as a non-paletted (truecolor) PNG. Send an internationalized host name in its ASCII (punycode) form, for example xn--bcher-kva.de rather than bücher.de: Router looks the host up as written, and a non-ASCII name is rejected as a host that does not exist. Uploading works in every environment, so it is the portable choice; always pass the image_url exactly as the upload returned it. If your image is not already at a public https URL, upload it first:
  1. Upload each reference image as multipart/form-data, with the image in the form field file (JPEG, PNG, or WebP, up to 75 MB). Authenticate the same way you do for Router, with X-API-Key or Authorization: Bearer.
  2. Read image_url from the JSON response and pass it in image_urls:
Text-to-image calls omit image_urls and need no upload.

Model outputs and stored assets

Input and output fields vary by model. Moving from a provider SDK or proxy can change both the route and how you read the result. Some assets are rehosted on Comfy storage; others are provider URLs or inline bytes. See Result assets for lifetimes and replay behavior.

Next

Quickstart

Generate your first image through Comfy Router.

Using the Router API

Choose a model, inspect its schema, and handle results and retries.