Comfy Router quickstart

Comfy Router lets you call partner models through https://api.comfy.org with one Comfy API key. Send the model’s input to POST /v2/models/{provider}/{model} and wait for the finished result. This example runs byteplus/dreamina-seedance-2-5-260628, a video model. These examples use Comfy as the default provider. To use an alternate provider, add model_provider to the SDK call or ?model_provider=<provider> to the URL. The provider coverage matrix lists the available model and provider combinations. Start with byteplus/dreamina-seedance-2-5-260628 below, or choose another model first.

Create an API key

Create a key in your Comfy workspace. In a Bash-compatible terminal, set:

export COMFY_API_KEY="comfyui-..."

Keep API keys on your server or in your local environment. These examples are for a terminal or server, not browser JavaScript.Router charges credits per request. If your workspace has no credit balance, the first live call returns 402 with error_type: insufficient_credits. This check runs before body validation, so an unfunded workspace can return 402 even for an invalid request. Add credits at workspace billing before debugging the request body.

Save a key for this request

Generate this value once for this request. If you retry the same request, reuse it.

export COMFY_REQUEST_KEY="$(uuidgen)"

If uuidgen is unavailable, use another UUID generator. Use a new key when you start a new generation.

Run the model

Choose your language and run the example. Generation can take a few minutes.

curl --max-time 660 \
  https://api.comfy.org/v2/models/byteplus/dreamina-seedance-2-5-260628 \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $COMFY_REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": [{"text": "A red fox trotting through a snowy pine forest", "type": "text"}], "duration": 5, "ratio": "16:9", "resolution": "720p"}'

# Python 3.10+
# Install: python -m pip install "comfy-sdk>=0.3.0"
# Save as quickstart.py, then run: python quickstart.py

import os

from comfy_sdk import Comfy

# Comfy reads COMFY_API_KEY from the environment.
with Comfy() as client:
    result = client.models.run(
        "byteplus/dreamina-seedance-2-5-260628",
        {
            "content": [
                {
                    "text": "A red fox trotting through a snowy pine forest",
                    "type": "text",
                },
            ],
            "duration": 5,
            "ratio": "16:9",
            "resolution": "720p",
        },
        idempotency_key=os.environ["COMFY_REQUEST_KEY"],
        timeout=660.0,
    )

print("result:", result)

// Node.js 22+
// Install: npm install "@comfyorg/sdk@>=0.4.0" --save-dev tsx
// Save as quickstart.mts, then run: npx tsx quickstart.mts

import { comfy } from "@comfyorg/sdk";

// Comfy reads COMFY_API_KEY from the environment.
const idempotencyKey = process.env.COMFY_REQUEST_KEY;
if (!idempotencyKey) throw new Error("Set COMFY_REQUEST_KEY first.");

const result = await comfy.models.run(
  "byteplus/dreamina-seedance-2-5-260628",
  {
    content: [
      {
        text: "A red fox trotting through a snowy pine forest",
        type: "text",
      },
    ],
    duration: 5,
    ratio: "16:9",
    resolution: "720p",
  },
  { idempotencyKey, timeoutMs: 660_000 },
);

console.log("result:", result.data);

// Swift 5.9+ (macOS 14+, iOS 17+). This snippet is a command-line program.
// Do not ship the key inside an iOS app: it is extractable from the binary.
// In an app, call your own backend and keep the key there.
// Install: add .package(url: "https://github.com/Comfy-Org/comfy-swift-sdk.git", from: "0.5.0")
// Add ComfySwiftSDK to your target, put this in Sources/.../main.swift, then run: swift run

import ComfySwiftSDK
import Foundation

let env = ProcessInfo.processInfo.environment

guard let apiKey = env["COMFY_API_KEY"], !apiKey.isEmpty else {
    fatalError("Set COMFY_API_KEY first.")
}
guard let requestKey = env["COMFY_REQUEST_KEY"], !requestKey.isEmpty else {
    fatalError("Set COMFY_REQUEST_KEY first.")
}

let client = ComfyCloudClient(apiKey: apiKey)

let result = try await client.models.run(
    "byteplus/dreamina-seedance-2-5-260628",
    input: [
        "content": [
            [
                "text": "A red fox trotting through a snowy pine forest",
                "type": "text",
            ],
        ],
        "duration": 5,
        "ratio": "16:9",
        "resolution": "720p",
    ],
    idempotencyKey: requestKey,
    timeout: 660  // seconds
)

print(result.output)

All four examples take the key from COMFY_API_KEY: the Python and TypeScript clients read it from the environment themselves, and the Swift example reads it and passes it to ComfyCloudClient(apiKey:).

Read the result

Router returns the model’s native result. Inspect the response body and read the fields your application needs.

Queue instead of waiting

run holds the connection until the image is ready. To get a request_id back at once and collect the result later, from this process or another one, call submit instead (the SDK versions step 3 installs have it), or send the same body to POST /v2/models/{provider}/{model}/requests over HTTP. Send an Idempotency-Key with it as you did in step 2: a submit retried after a dropped connection then returns the original request instead of queueing and billing a second one. The SDKs mint one per submit call. Every model page has a Queue and collect later tab beside the synchronous snippet, and Queued delivery walks through status, cancellation and collection. Queued delivery is scoped to the workspace behind your key, which a key created in your Comfy workspace carries.

Develop with Comfy

Deploy ComfyUI

Comfy Router

Comfy CLI

Specifications

Comfy Router quickstart

Queue instead of waiting

​Queue instead of waiting

Queue instead of waiting