Skip to main content
Beta. The SDKs and the Comfy API v2 they call are at 0.1.x. The shape of the API can still change before we lock it down. Now is the cheapest time to tell us it is wrong. See Feedback.
The Comfy SDKs let your application run ComfyUI workflows and get the results back. You submit a workflow, ComfyUI executes it, and you download the outputs. The same code runs against Comfy Cloud or against a ComfyUI instance you host yourself. Only the base URL changes. The SDKs are clients for the Comfy API v2, a versioned HTTP API that we intend to support long term. New releases of ComfyUI will not break integrations built on it. Things people build this way:
  • Plugins that generate content inside another application, such as Blender or Krita
  • Consumer apps that run generation on behalf of their users
  • Batch pipelines, for example running one workflow over every frame of a video
  • Backend services that need many workflows in flight at once
These SDKs drive ComfyUI from the outside. If you are writing custom nodes or frontend extensions that run inside ComfyUI, you want Develop Custom Nodes instead. Those are a separate set of APIs.

Install

Python 3.10 or newer. Node 22 or newer.

Quickstart

Upload an input image, run a workflow, and write the results to disk.
workflow_api.json is a workflow saved in API format. "10" and "9" are node IDs from that file: the node the input image feeds into, and the output node whose results you want. Asset handles are lazy. photo.png is hashed locally and only uploaded if the server does not already have those bytes, so re-running with the same input costs nothing. run() submits the job and waits for it to reach a terminal state. To do work while it executes, use submit() instead and watch the event stream. To run against your own ComfyUI instead, change one line and drop the key: Comfy("http://127.0.0.1:8189"). See below.

Choosing a base URL

Comfy Cloud

Works out of the box. Create an API key and pass it to the client.
API access requires a paid Comfy Cloud subscription. The free tier does not include it. How many jobs you can run at once depends on your tier. See Cloud API Overview.

Your own ComfyUI

During the beta, the v2 API is served by comfy-api-proxy, a small open-source service that runs alongside your ComfyUI:
By default it proxies the ComfyUI on 127.0.0.1:8188 and serves the v2 API on 127.0.0.1:8189. Use --comfyui and --port to change either. Then point the SDK at http://127.0.0.1:8189. Authentication is not required by default. If the proxy is configured with a static bearer token, pass that token as the SDK API key: Comfy("http://127.0.0.1:8189", api_key="..."). The proxy binds to loopback only by default. Run it with --comfyui-base-dir /path/to/ComfyUI if you also want to upload model files into your install. The proxy is a stopgap. Once the v2 API stabilizes it moves into ComfyUI core and the proxy is no longer needed.

Watching a job run

job.events() gives you a live stream of the job’s state: node and step progress, preview frames, and each output the moment it is committed. It reconnects on its own if the connection drops.
Preview.to_pil() requires the optional Pillow extra: pip install "comfy-sdk[pil]". result() returns the finished job, or raises JobFailed with the node-level detail if execution failed. See the SDK README for your language for the full event catalog. The stream is a live feed, not a replayable log. It exists so you can render progress, not so you can rely on it for results. Polling the job is what is authoritative, and run(), wait(), and result() fall back to polling automatically. See Design Notes for why.

What the SDKs cover today

The first version does one thing properly: run a workflow and get the results back.
  • Assets. Create input handles from a file, bytes, a stream, or a URL. Handles are lazy and content addressed, so re-running with the same input does not re-upload it.
  • Submission. Submit an API-format graph. Submission is idempotent, and a full queue is retried for you within a bounded budget.
  • Execution. Poll with wait(), or follow events() for live progress.
  • Outputs. Write to disk, buffer into memory, fetch a byte range, or get a short-lived download URL.
  • Errors. Typed exceptions such as JobFailed, Unauthorized, InsufficientCredits, and QueueFull, rather than raw status codes.
  • Cancellation. Jobs can be canceled while running. TypeScript additionally accepts an AbortSignal on any call.
Python ships both a synchronous Comfy client and an AsyncComfy client with the same surface. TypeScript is async only. Not in this version: managing saved workflows, the model library, node introspection, and named workflow parameters. Design Notes explains why the surface starts this small.

Reference

The SDK READMEs are the full reference for each language, including auth, assets, errors, and the low-level escape hatches.

Python SDK

comfy-sdk on PyPI. Sync and async clients.

TypeScript SDK

@comfyorg/sdk on npm. Typed, async, with a low-level client.

Comfy API v2 Reference

The HTTP API underneath both SDKs. Use it directly from any language.

Design Notes

Why this API exists, how it relates to the existing ComfyUI APIs, and what comes next.

Feedback

This is 0.1.x on purpose. Method names, the client shape, the event catalog, the error taxonomy, and how asset handling feels in practice are all still cheap to change, and we plan to lock the surface down over the next few weeks. After that, “we support this long term” starts to mean we cannot fix it for you anymore. So tell us what is awkward, what you expected to find and did not, and what you ended up working around. The #developer-platform channel in our Discord is the place for it. If you want a first-party SDK in another language, say so there. Both SDKs sit on the same documented HTTP contract, so any language can talk to the API today, but we would rather know where the demand is.