Guidance for coding agents building apps with the Comfy SDK and Comfy Router. No MCP server.

GitHub stars
262

Install

/plugin install comfy-sdk@comfy-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add Comfy-Org/comfy-skills.

Contents

Discovered from source

Skills 1

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

  1. Key read server side; GET /v2/models succeeds.
  2. Model chosen from that list; body built from its openapi.json.
  3. run only where the process can wait minutes; otherwise submit.
  4. Timeout in the right unit, or left at the default.
  5. insufficient_credits surfaced to the user, not retried.

Read next

Sponsors

Details

Marketplace
Comfy-Org/comfy-skills
Source
claude-code-sdk
Category
Community

More from Comfy-Org/comfy-skills

All 2