comfy-sdk — build with Comfy Router
Steering only. Model names, schemas, prices and default timeouts change:
discover them at run time (section 3) or read them off the installed SDK, and
never paste one from memory.
1. Pick the right client
- Router (partner models,
https://api.comfy.org) is reached through the
models namespace:
- Python:
Comfy().models (AsyncComfy().models for asyncio).
- TypeScript: the module-level
comfy.models, after comfy.config({ credentials })
or with COMFY_API_KEY set. new Comfy({ apiKey }) is the Comfy Cloud
workflow client and has no .models.
- Cloud (
/api/v2/jobs, run a ComfyUI workflow) is the class client in both SDKs.
- Both use the same
COMFY_API_KEY. Hosts are separate: COMFY_ROUTER_BASE_URL
redirects Router, COMFY_BASE_URL redirects Cloud. Leave both unset in production.
from comfy_sdk import Comfy
client = Comfy() # reads COMFY_API_KEY
result = client.models.run("<provider>/<model>", {<provider's native body>})
import { comfy } from "@comfyorg/sdk";
comfy.config({ credentials: process.env.COMFY_API_KEY });
const { kind, data, requestId } = await comfy.models.run("<provider>/<model>", {<native body>});
2. Credentials stay on the server
- The SDKs read
COMFY_API_KEY from the process environment; neither loads a
.env file. Your framework does that (python-dotenv, Next.js .env.local,
etc.). An explicit api_key= / credentials argument always wins over the variable.
- Never expose the key to a browser bundle (no
NEXT_PUBLIC_ / VITE_ prefix). Call
Router from a server route and return the result to the page.
- Preflight before any paid call: list models (section 3). A
401 there means the
key, not the model, is wrong.
3. Discover, then call
GET /v2/models lists what the credential can run, with billing facts. Paginate
with next_cursor while has_more is true; treat cursors as opaque.
GET /v2/models/{provider}/{model}/openapi.json is that model's input/output schema.
The second argument to run / submit is the provider's native body, forwarded
unchanged, so build it from this schema, not from another provider's shape.
- TypeScript wraps both:
comfy.models.list() walks the catalog and
comfy.models.schema(model) fetches the document. In Python, if the installed
client.models has no such helper, call the two routes on the Router host
yourself with Authorization: Bearer <COMFY_API_KEY>.
- A model id is exactly two segments,
provider/model.
4. run, submit or subscribe
run blocks until the generation is finished. The wait is server side:
Router holds the connection up to its own deadline, then answers
504 deadline_exceeded. The SDK retries that with the same Idempotency-Key
and Retry-After, collecting the running generation rather than starting a
second one.
submit returns a handle with a request_id at once. Use it in any web request
handler, serverless function or job queue that cannot hold a connection for
minutes. Collect later, even from another process, with
models.handle(model, request_id) then get() / status() / cancel().
subscribe is submit + poll + collect with a progress callback. Its timeout is
client side only; when it expires it makes one best-effort cancel. A
generation already running at the partner completes and is billed regardless.
- There are no webhooks or push events: the status route is how you follow a
request.
submit / handle / subscribe need comfy-sdk / @comfyorg/sdk
0.3.0 or newer.
5. Timeouts: units and what they bound
- Python
models.run(..., timeout=) is seconds and defaults to the SDK's own
run timeout, sized to Router's deadline. Comfy(timeout=...) sizes ordinary API
calls and does not change the run default.
- TypeScript
{ timeoutMs } is milliseconds; its default is longer than
Router's deadline so a same-key collect still fits. Prefer an AbortSignal to
timeoutMs: null.
- The exact defaults move between releases. Read them from the installed SDK
(the
run signature, DEFAULT_RUN_TIMEOUT_MS) instead of hard-coding a number.
- Do not set a run timeout below a realistic generation (tens of seconds to
minutes). If your platform caps request duration (serverless, proxies), switch
to
submit instead of lowering the timeout.
6. Retries and idempotency are already handled
- Every
run / submit mints an Idempotency-Key and reuses it for its own
retries, so a retried attempt is charged at most once. Calling run again is a
new key and a new charge: do not wrap it in your own retry loop.
- To retry one logical call across processes or restarts, pass
idempotency_key= / { idempotencyKey } yourself and keep the body identical;
the same key with a different body is refused 409 invalid_input (use a new key).
7. Errors: branch on the bucket
A Router error response carries Router's wire bucket (also the
X-Comfy-Error-Type header), but where you read it depends on the language and
the call:
- Python, every call: Router responses raise classes from
comfy_sdk.router_exceptions, all descending from RouterError; read
exc.error_type.
- TypeScript
comfy.models.run (synchronous): throws ComfyError and its
subclasses (InsufficientCredits, Forbidden, Unauthorized, NotFound),
not routerErrors.*. Read err.code; there is no errorType, and
instanceof routerErrors.RouterError is false.
- TypeScript queued (
submit / handle / subscribe): a Router error
response throws routerErrors.*, all descending from
routerErrors.RouterError; read err.errorType.
Failures on the client side are not Router responses and carry no bucket:
- SDK-raised: a plain
ComfyError (Python and TypeScript). An unreadable reply
is code invalid_response in Python and on the TypeScript queued calls, but
unexpected_response from TypeScript comfy.models.run. A TypeScript queued
call exceeding timeoutMs is request_timeout.
- Transport: a dropped connection or read timeout surfaces as the HTTP library's
own error once the SDK's retries are spent:
httpx.HTTPError in Python, a
native TypeError from fetch in TypeScript.
- Waits and cancellation: Python
subscribe past its timeout= raises
TimeoutError (a run past its timeout= is a transport read timeout).
A TypeScript caller's own AbortSignal rethrows its abort reason unchanged
(an AbortError by default).
So a TypeScript app needs a ComfyError catch on both paths, a
routerErrors.RouterError catch on the queued one, and a final catch for
transport errors and its own aborts; a Python app catches RouterError, then
ComfyError, httpx.HTTPError and TimeoutError.
insufficient_credits (402): stop and tell the user to add credits. Never retry.
content_policy_violation: do not resend the same prompt.
rate_limited / concurrency_limit_exceeded (429): wait Retry-After, then
resend. Python run does this for you. TypeScript does not retry a 429;
wait err.retryAfter seconds yourself, or tell the user to try again.
not_enabled (403): the workspace is not on this model or route yet; terminal.
provider_timeout vs deadline_exceeded: both 504; the first is the partner,
the second is Comfy's bound. The SDK retries the second with the same key.
- Keep a catch-all branch. An unrecognised bucket surfaces as the base class:
RouterError in Python and for Router responses on the TypeScript queued path,
ComfyError from TypeScript run and from SDK-raised client-side failures.
- A queued request can finish as
COMPLETED with an error_type; get() raises
the typed error, and the event iterator yields it as the last observation.
8. Results
- Python
run returns the provider's payload as-is. TypeScript returns
{ kind, data, requestId } (kind is "json" or "binary"; branch on it) and
caps the buffered body (maxBytes).
- Asset URLs in a result are time-limited. Download or re-host what you want to
keep before responding to the user; do not store a partner URL as a permanent link.
9. Before the first generation
- Key read server side;
GET /v2/models succeeds.
- Model chosen from that list; body built from its
openapi.json.
run only where the process can wait minutes; otherwise submit.
- Timeout in the right unit, or left at the default.
insufficient_credits surfaced to the user, not retried.
Read next
1---2name: comfy-sdk3description: Build an app that generates images, video or audio through Comfy Router using the Comfy SDK (Python `comfy-sdk` or TypeScript `@comfyorg/sdk`). Use when a task mentions the Comfy SDK, Comfy Router, `models.run`, or adding generation to an app via api.comfy.org. Not for driving the `comfy` CLI, ComfyUI workflows or custom nodes (see the `comfy` skill).4metadata:5 source: https://skillmd.com/skills/comfy-org/comfy-sdk6---78# comfy-sdk — build with Comfy Router910Steering only. Model names, schemas, prices and default timeouts change:11discover them at run time (section 3) or read them off the installed SDK, and12never paste one from memory.1314## 1. Pick the right client1516- **Router** (partner models, `https://api.comfy.org`) is reached through the17 `models` namespace:18 - Python: `Comfy().models` (`AsyncComfy().models` for asyncio).19 - TypeScript: the **module-level** `comfy.models`, after `comfy.config({ credentials })`20 or with `COMFY_API_KEY` set. `new Comfy({ apiKey })` is the Comfy Cloud21 *workflow* client and has **no** `.models`.22- **Cloud** (`/api/v2/jobs`, run a ComfyUI workflow) is the class client in both SDKs.23- Both use the same `COMFY_API_KEY`. Hosts are separate: `COMFY_ROUTER_BASE_URL`24 redirects Router, `COMFY_BASE_URL` redirects Cloud. Leave both unset in production.2526```python27from comfy_sdk import Comfy2829client = Comfy() # reads COMFY_API_KEY30result = client.models.run("<provider>/<model>", {<provider's native body>})31```3233```ts34import { comfy } from "@comfyorg/sdk";3536comfy.config({ credentials: process.env.COMFY_API_KEY });37const { kind, data, requestId } = await comfy.models.run("<provider>/<model>", {<native body>});38```3940## 2. Credentials stay on the server4142- The SDKs read `COMFY_API_KEY` from the **process environment**; neither loads a43 `.env` file. Your framework does that (`python-dotenv`, Next.js `.env.local`,44 etc.). An explicit `api_key=` / `credentials` argument always wins over the variable.45- Never expose the key to a browser bundle (no `NEXT_PUBLIC_` / `VITE_` prefix). Call46 Router from a server route and return the result to the page.47- Preflight before any paid call: list models (section 3). A `401` there means the48 key, not the model, is wrong.4950## 3. Discover, then call5152- `GET /v2/models` lists what the credential can run, with billing facts. Paginate53 with `next_cursor` while `has_more` is true; treat cursors as opaque.54- `GET /v2/models/{provider}/{model}/openapi.json` is that model's input/output schema.55 The second argument to `run` / `submit` is the provider's **native body**, forwarded56 unchanged, so build it from this schema, not from another provider's shape.57- TypeScript wraps both: `comfy.models.list()` walks the catalog and58 `comfy.models.schema(model)` fetches the document. In Python, if the installed59 `client.models` has no such helper, call the two routes on the Router host60 yourself with `Authorization: Bearer <COMFY_API_KEY>`.61- A model id is exactly two segments, `provider/model`.6263## 4. `run`, `submit` or `subscribe`6465- `run` blocks until the generation is finished. The wait is **server side**:66 Router holds the connection up to its own deadline, then answers67 `504 deadline_exceeded`. The SDK retries that with the same `Idempotency-Key`68 and `Retry-After`, collecting the running generation rather than starting a69 second one.70- `submit` returns a handle with a `request_id` at once. Use it in any web request71 handler, serverless function or job queue that cannot hold a connection for72 minutes. Collect later, even from another process, with73 `models.handle(model, request_id)` then `get()` / `status()` / `cancel()`.74- `subscribe` is submit + poll + collect with a progress callback. Its timeout is75 **client side only**; when it expires it makes one best-effort cancel. A76 generation already running at the partner completes and is billed regardless.77- There are no webhooks or push events: the status route is how you follow a78 request. `submit` / `handle` / `subscribe` need `comfy-sdk` / `@comfyorg/sdk`79 0.3.0 or newer.8081## 5. Timeouts: units and what they bound8283- Python `models.run(..., timeout=)` is **seconds** and defaults to the SDK's own84 run timeout, sized to Router's deadline. `Comfy(timeout=...)` sizes ordinary API85 calls and does **not** change the run default.86- TypeScript `{ timeoutMs }` is **milliseconds**; its default is longer than87 Router's deadline so a same-key collect still fits. Prefer an `AbortSignal` to88 `timeoutMs: null`.89- The exact defaults move between releases. Read them from the installed SDK90 (the `run` signature, `DEFAULT_RUN_TIMEOUT_MS`) instead of hard-coding a number.91- Do not set a run timeout below a realistic generation (tens of seconds to92 minutes). If your platform caps request duration (serverless, proxies), switch93 to `submit` instead of lowering the timeout.9495## 6. Retries and idempotency are already handled9697- Every `run` / `submit` mints an `Idempotency-Key` and reuses it for its own98 retries, so a retried attempt is charged at most once. Calling `run` again is a99 **new key and a new charge**: do not wrap it in your own retry loop.100- To retry one logical call across processes or restarts, pass101 `idempotency_key=` / `{ idempotencyKey }` yourself and keep the body identical;102 the same key with a different body is refused `409 invalid_input` (use a new key).103104## 7. Errors: branch on the bucket105106A Router error response carries Router's wire bucket (also the107`X-Comfy-Error-Type` header), but where you read it depends on the language and108the call:109110- **Python**, every call: Router responses raise classes from111 `comfy_sdk.router_exceptions`, all descending from `RouterError`; read112 `exc.error_type`.113- **TypeScript `comfy.models.run`** (synchronous): throws `ComfyError` and its114 subclasses (`InsufficientCredits`, `Forbidden`, `Unauthorized`, `NotFound`),115 **not** `routerErrors.*`. Read `err.code`; there is no `errorType`, and116 `instanceof routerErrors.RouterError` is `false`.117- **TypeScript queued** (`submit` / `handle` / `subscribe`): a Router error118 response throws `routerErrors.*`, all descending from119 `routerErrors.RouterError`; read `err.errorType`.120121Failures on the client side are **not** Router responses and carry no bucket:122123- SDK-raised: a plain `ComfyError` (Python and TypeScript). An unreadable reply124 is `code` `invalid_response` in Python and on the TypeScript queued calls, but125 `unexpected_response` from TypeScript `comfy.models.run`. A TypeScript queued126 call exceeding `timeoutMs` is `request_timeout`.127- Transport: a dropped connection or read timeout surfaces as the HTTP library's128 own error once the SDK's retries are spent: `httpx.HTTPError` in Python, a129 native `TypeError` from `fetch` in TypeScript.130- Waits and cancellation: Python `subscribe` past its `timeout=` raises131 `TimeoutError` (a `run` past its `timeout=` is a transport read timeout).132 A TypeScript caller's own `AbortSignal` rethrows its abort reason unchanged133 (an `AbortError` by default).134135So a TypeScript app needs a `ComfyError` catch on both paths, a136`routerErrors.RouterError` catch on the queued one, and a final catch for137transport errors and its own aborts; a Python app catches `RouterError`, then138`ComfyError`, `httpx.HTTPError` and `TimeoutError`.139140- `insufficient_credits` (`402`): stop and tell the user to add credits. Never retry.141- `content_policy_violation`: do not resend the same prompt.142- `rate_limited` / `concurrency_limit_exceeded` (`429`): wait `Retry-After`, then143 resend. Python `run` does this for you. TypeScript does **not** retry a `429`;144 wait `err.retryAfter` seconds yourself, or tell the user to try again.145- `not_enabled` (`403`): the workspace is not on this model or route yet; terminal.146- `provider_timeout` vs `deadline_exceeded`: both `504`; the first is the partner,147 the second is Comfy's bound. The SDK retries the second with the same key.148- Keep a catch-all branch. An unrecognised bucket surfaces as the base class:149 `RouterError` in Python and for Router responses on the TypeScript queued path,150 `ComfyError` from TypeScript `run` and from SDK-raised client-side failures.151- A queued request can finish as `COMPLETED` **with** an `error_type`; `get()` raises152 the typed error, and the event iterator yields it as the last observation.153154## 8. Results155156- Python `run` returns the provider's payload as-is. TypeScript returns157 `{ kind, data, requestId }` (`kind` is `"json"` or `"binary"`; branch on it) and158 caps the buffered body (`maxBytes`).159- Asset URLs in a result are time-limited. Download or re-host what you want to160 keep before responding to the user; do not store a partner URL as a permanent link.161162## 9. Before the first generation1631641. Key read server side; `GET /v2/models` succeeds.1652. Model chosen from that list; body built from its `openapi.json`.1663. `run` only where the process can wait minutes; otherwise `submit`.1674. Timeout in the right unit, or left at the default.1685. `insufficient_credits` surfaced to the user, not retried.169170## Read next171172- Quickstart: https://docs.comfy.org/development/comfy-router/quickstart173- Queued delivery: https://docs.comfy.org/development/comfy-router/queue174- Error buckets: https://docs.comfy.org/development/comfy-router/reference#error-buckets175- SDK READMEs: https://github.com/Comfy-Org/comfy-python-sdk and176 https://github.com/Comfy-Org/comfy-typescript-sdk