From 730e73f5a48228d2e8644eb59e465296802d5a52 Mon Sep 17 00:00:00 2001 From: Bryan Wade Date: Tue, 15 Sep 2026 14:11:05 -0700 Subject: [PATCH 1/3] Help developers choose the right integration path faster The development landing page now presents its four primary paths together before the existing workflow quickstart, with one destination and a concise description per path. Constraint: Preserve the existing Quick Start guide and its current upstream copy. Rejected: Keep the supplemental More grid | the request calls for exactly four use-case panels. Confidence: high Scope-risk: narrow Reversibility: clean Tested: Mintlify strict build validation under Node 22.22.2; local desktop preview of the card grid and Quick Start transition Not-tested: Dedicated mobile viewport --- development/overview.mdx | 66 ++++++++++------------------------------ 1 file changed, 16 insertions(+), 50 deletions(-) diff --git a/development/overview.mdx b/development/overview.mdx index dc58feb41..5a22ffc14 100644 --- a/development/overview.mdx +++ b/development/overview.mdx @@ -5,9 +5,22 @@ description: "Using ComfyUI as a Developer" ComfyUI is a modular GenAI inference engine that can be run as a server, accessed via API, extended with custom nodes, and managed from the command line. Most API work follows two steps: get ComfyUI running somewhere, then run workflows against it from your application. - - Generate your first image with a Comfy API key in Python, TypeScript, or cURL. - +## Use cases + + + + Generate with hosted models through Comfy Router. + + + Deploy ComfyUI on the Developer Platform or your own infrastructure. + + + Run workflows from your application with an SDK or the HTTP API. + + + Connect AI agents to ComfyUI with MCP and Comfy CLI. + + ## Quick Start @@ -60,50 +73,3 @@ The fastest way to try the workflow API is to run a workflow against Comfy Cloud When you need your own models and custom nodes behind the endpoint, create a [Comfy API deployment](/development/serverless/overview), a serverless endpoint managed through the Developer Platform. The same SDK code works against it; only the base URL changes. - -## Deploy ComfyUI - -Learn how to deploy and scale ComfyUI, on the Developer Platform or your own infrastructure. - - - Compare Comfy API deployments, Comfy Cloud, and self-hosting, and pick the right target. - - -See also: [Comfy API deployments](/development/serverless/overview) · [Comfy Cloud](/development/deploy/cloud) · [Self-Hosting Options](/development/deploy/self-hosting) - -## Run Workflows - -Learn how to run workflows using our SDKs and the v2 HTTP API. They work against Comfy Cloud, Comfy API deployments, and your own ComfyUI instance. - - - See which client works with which deployment, starting with the Python and TypeScript SDKs. - - -See also: [Comfy SDKs](/development/api-development/sdks) · [API Proxy for Self-Hosted](/development/comfyui-server/api-proxy) · [Comfy API v2 Reference](/api-reference/v2/overview) - -## Agent Tools / MCP - -Connect AI agents to ComfyUI via the Model Context Protocol (MCP). Start with the hosted Cloud MCP, or use Local MCP and Comfy CLI for other setups. - - - Compare Cloud MCP, Local MCP, and Comfy CLI, and find the right setup for your AI agent integration. - - -See also: [Comfy MCP](/agent-tools/mcp) for cloud and local connections - -## More - - - - The raw REST and WebSocket API of the ComfyUI server: routes, messages, and startup flags. - - - Install, update, and manage ComfyUI from the terminal. - - - Extend ComfyUI with Python backends and JavaScript UI extensions. - - - Package and publish custom nodes through the Comfy Registry. - - From d0e8e503944dd3f92292541b3b394b117a440bcb Mon Sep 17 00:00:00 2001 From: Bryan Wade Date: Tue, 15 Sep 2026 14:27:10 -0700 Subject: [PATCH 2/3] Keep Router limitations aligned with queued delivery The new queued-delivery guide landed while the capabilities page still described Router as synchronous-only. Reconcile that page with the gated preview and point readers to the canonical queue guide instead of duplicating its examples. Constraint: Queued delivery is a caller-gated preview and returns 403 not_enabled when unavailable. Rejected: Keep the separate API-guide summary | upstream now has a dedicated queue guide and model examples, so another summary would duplicate them. Confidence: high Scope-risk: narrow Directive: Update queue semantics at the upstream contract before changing generated reference text. Tested: Mintlify strict validation; Mintlify broken-link check; unauthenticated live requests reached all four api.comfy.org queue routes and returned 401 with request IDs Not-tested: Authenticated queued generation because it can consume credits and is rollout-gated --- development/comfy-router/limitations.mdx | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/development/comfy-router/limitations.mdx b/development/comfy-router/limitations.mdx index c377726ee..861e87331 100644 --- a/development/comfy-router/limitations.mdx +++ b/development/comfy-router/limitations.mdx @@ -4,26 +4,24 @@ sidebarTitle: "Capabilities and limits" description: "Choose Router or a partner proxy, plan for long-running calls, and understand recovery, rate limits, and asset storage." --- -Router runs a partner model through one synchronous HTTP call. Use it when your application can wait for a finished result and handle the model's own input and output fields. +Router's default route runs a partner model through one synchronous HTTP call. Queued delivery is available in a gated preview for applications that need to submit work and collect it later. ## What Router supports | Requirement | Router support | Alternative or next step | | --- | --- | --- | | Generate with one request | `POST /v2/models/{provider}/{model}` returns the finished result. | Start with the [Quickstart](/development/comfy-router/quickstart). | -| Submit a job and collect it later | No general job/status API or completion webhook. | Run Router from a worker, or use a partner proxy with submit-and-poll operations. | -| Show progress or stream output | No live progress, streaming, or preview frames during the call. | Show an indeterminate state, or use a supported proxy operation. | -| Recover after a lost connection | Same-key collection is available when Router retained a handle to an accepted generation. | Preserve the key and follow [retry guidance](/development/comfy-router/api#retry-outcomes). | +| Submit a request and collect it later | Available in gated preview through `POST /v2/models/{provider}/{model}/requests`. | See [Queued delivery](/development/comfy-router/queue). | +| Show progress or stream output | Queued delivery reports queue state and can include queue position, but no percentage progress, streaming output, or preview frames. | Poll the returned `status_url`, or use a supported proxy operation for provider-specific progress. | +| Recover after a lost connection | After receiving a queued request handle, use its returned URLs. If submission is interrupted before that, retry with the same idempotency key. Synchronous calls can sometimes be collected the same way. | Preserve the idempotency key and follow [retry guidance](/development/comfy-router/api#retry-outcomes). | | Reconcile Comfy charges | No universal Comfy cost or credit-balance field on the response. | Use [workspace billing](https://platform.comfy.org). | | Store results permanently | Asset URLs can expire, including rehosted and replayed URLs. | Download the assets; see [result assets](/development/comfy-router/reference#result-assets). | -## No queued submission +## Queued delivery is in preview -Router holds the connection while the model runs. For asynchronous providers, it submits the job and polls internally. Queued delivery (submit, get a `request_id`, poll, collect) is in a gated preview: see [Queued delivery](/development/comfy-router/queue). Outside the preview, Router does not expose a job ID, status endpoint, callback, or webhook. +Queued delivery returns a `request_id` and URLs for status, result collection, and cancellation. It is enabled per caller; callers without access receive `403` with `not_enabled`. Cancellation is best effort, and Router does not provide a completion webhook. See [Queued delivery](/development/comfy-router/queue) for examples and the full lifecycle. -If your request cannot stay open long enough, call Router from a worker and track the job in your application. Use a [partner proxy](#router-does-not-cover-every-partner-operation) when you need the provider's submit-and-poll controls. - -## Calls are cut off at a server deadline +## Synchronous calls are cut off at a server deadline Router's default deadline is **10 minutes**, configurable by the deployment. Set your client timeout above it so Router can return its error and request ID first. @@ -48,11 +46,11 @@ The request-rate limit applies to invocation and catalog/schema reads, including Cache catalog and schema reads. Revalidate schemas with `ETag` and `If-None-Match`. See [Headers](/development/comfy-router/headers) for retry and committed-spend fields. -## No progress while a call runs +## No live progress while a request 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. +Synchronous delivery returns only the final response. Queued delivery exposes queue state and can include queue position, but neither mode provides streamed tokens, server-sent events, percentage updates, or intermediate preview frames. A provider's internal progress is not forwarded. -Show an indeterminate progress indicator. If you need progress or streaming, use a partner-proxy operation that exposes it. +Show an indeterminate progress indicator after a queued request begins running. If you need provider-specific progress or streaming, use a partner-proxy operation that exposes it. From b5c079a2f36cd03287d5183189f2e9a07e57653f Mon Sep 17 00:00:00 2001 From: Bryan Wade Date: Tue, 15 Sep 2026 16:41:13 -0700 Subject: [PATCH 3/3] Use workspace terminology for queue preview gating The canonical queue guide scopes preview enablement and not_enabled responses to a workspace, so the capabilities page now uses the same term. Constraint: Leave the surrounding lifecycle description unchanged. Confidence: high Scope-risk: narrow Tested: Mintlify strict validation; git diff --check --- development/comfy-router/limitations.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development/comfy-router/limitations.mdx b/development/comfy-router/limitations.mdx index 861e87331..bbac6036e 100644 --- a/development/comfy-router/limitations.mdx +++ b/development/comfy-router/limitations.mdx @@ -19,7 +19,7 @@ Router's default route runs a partner model through one synchronous HTTP call. Q ## Queued delivery is in preview -Queued delivery returns a `request_id` and URLs for status, result collection, and cancellation. It is enabled per caller; callers without access receive `403` with `not_enabled`. Cancellation is best effort, and Router does not provide a completion webhook. See [Queued delivery](/development/comfy-router/queue) for examples and the full lifecycle. +Queued delivery returns a `request_id` and URLs for status, result collection, and cancellation. It is enabled per workspace; workspaces without access receive `403` with `not_enabled`. Cancellation is best effort, and Router does not provide a completion webhook. See [Queued delivery](/development/comfy-router/queue) for examples and the full lifecycle. ## Synchronous calls are cut off at a server deadline