Experimental API: This API is experimental and subject to change. Endpoints, request/response formats, and behavior may be modified without notice.

Comfy Cloud API

The Comfy Cloud API provides programmatic access to run workflows on Comfy Cloud infrastructure. The API is compatible with local ComfyUI’s API, making it easy to migrate existing integrations.

Subscription required: API access is available on the Standard, Creator and Pro tiers. The Free tier does not include API access. See pricing plans for details.

Credits and Usage

API requests draw from the same monthly credit allocation as the Comfy Cloud web UI — there is no separate API credit pool. Each tier’s included credits, top-up options, and per-workflow runtime caps apply to API jobs in exactly the same way as UI jobs. See the pricing page for the monthly credit amounts on the Standard, Creator and Pro tiers. If you run out of credits mid-month, top-ups can be purchased from your account dashboard.

Base URL

https://cloud.comfy.org

Authentication

All API requests require an API key passed via the X-API-Key header.

Getting an API Key

See Getting an API Key for instructions on creating and managing your Cloud API key.

Using the API Key

Pass your API key in the X-API-Key header with every request:

curl -X GET "https://cloud.comfy.org/api/user" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY"

Core Concepts

Workflows

ComfyUI workflows are JSON objects describing a graph of nodes. The API accepts workflows in the API format (node IDs as keys with class_type, inputs, etc.) as produced by the ComfyUI frontend’s “Export Workflow (API)” option.

Jobs

When you submit a workflow, a job is created. Jobs are executed asynchronously:

Submit workflow via POST /api/prompt
Receive a prompt_id (job ID)
Monitor progress via WebSocket or poll for status
Retrieve outputs when complete

Parallel Execution (Concurrent Jobs)

API users can submit multiple workflows concurrently without waiting for previous jobs to complete. Simply send multiple POST /api/prompt requests — no special headers or parameters are needed. The dispatcher will run them in parallel up to your subscription tier’s limit.

Subscription Tier	Concurrent Jobs
Standard	1
Creator	3
Pro	5

Jobs submitted beyond your concurrency limit will queue normally and execute automatically as slots free up.

Parallel execution is currently available via the API only. See pricing plans for subscription details.

Example: Submitting Multiple Jobs in Parallel

import os
import json
import asyncio
import aiohttp

BASE_URL = "https://cloud.comfy.org"
API_KEY = os.environ["COMFY_CLOUD_API_KEY"]

async def submit_workflow(session, workflow):
    """Submit a single workflow and return the prompt_id."""
    async with session.post(
        f"{BASE_URL}/api/prompt",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json={"prompt": workflow},
    ) as response:
        result = await response.json()
        return result["prompt_id"]

async def main():
    with open("workflow_api.json") as f:
        base_workflow = json.load(f)

    # Create variations by changing the seed
    workflows = []
    for seed in [42, 123, 456]:
        workflow = json.loads(json.dumps(base_workflow))
        workflow["3"]["inputs"]["seed"] = seed
        workflows.append(workflow)

    # Submit all workflows concurrently
    async with aiohttp.ClientSession() as session:
        prompt_ids = await asyncio.gather(
            *[submit_workflow(session, wf) for wf in workflows]
        )

    for pid in prompt_ids:
        print(f"Job submitted: {pid}")

    # Poll or use WebSocket to monitor each job...

asyncio.run(main())

Outputs

Generated content (images, videos, audio) is stored in cloud storage. Output files can be downloaded via the /api/view endpoint, which returns a 302 redirect to a temporary signed URL.

Quick Start

Here’s a complete example showing how to submit a workflow, monitor its progress, and retrieve outputs:

Step 1: Submit a Workflow

curl -X POST "https://cloud.comfy.org/api/prompt" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": '"$(cat workflow_api.json)"'}'

Step 2: Monitor Job Progress

You can monitor job completion using either polling or WebSocket for real-time updates.

Option A: Polling (Simple)

Job Status Values: The API returns one of the following status values:

Status	Description
`pending`	Job is queued and waiting to start
`in_progress`	Job is currently executing
`completed`	Job finished successfully
`failed`	Job encountered an error
`cancelled`	Job was cancelled by user

# Poll for job completion
curl -X GET "$BASE_URL/api/job/{prompt_id}/status" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY"

# Response examples:
# {"status": "pending"}      - Job is queued
# {"status": "in_progress"}  - Job is currently running
# {"status": "completed"}    - Job finished successfully
# {"status": "failed"}       - Job encountered an error
# {"status": "cancelled"}    - Job was cancelled

Option B: WebSocket (Real-time Progress)

For real-time progress updates and to collect output metadata:

async function listenForCompletion(
  promptId: string,
  timeout: number = 300000
): Promise<Record<string, any>> {
  const wsUrl = `wss://cloud.comfy.org/ws?clientId=${crypto.randomUUID()}&token=${API_KEY}`;
  const outputs: Record<string, any> = {};

  return new Promise((resolve, reject) => {
    const ws = new WebSocket(wsUrl);
    const timer = setTimeout(() => {
      ws.close();
      reject(new Error(`Job did not complete within ${timeout / 1000}s`));
    }, timeout);

    ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      const msgType = data.type;
      const msgData = data.data ?? {};

      // Filter to our job
      if (msgData.prompt_id !== promptId) return;

      if (msgType === "executing") {
        const node = msgData.node;
        if (node) {
          console.log(`Executing node: ${node}`);
        } else {
          console.log("Execution complete");
        }
      } else if (msgType === "progress") {
        console.log(`Progress: ${msgData.value}/${msgData.max}`);
      } else if (msgType === "executed" && msgData.output) {
        outputs[msgData.node] = msgData.output;
      } else if (msgType === "execution_success") {
        console.log("Job completed successfully!");
        clearTimeout(timer);
        ws.close();
        resolve(outputs);
      } else if (msgType === "execution_error") {
        const errorMsg = msgData.exception_message ?? "Unknown error";
        clearTimeout(timer);
        ws.close();
        reject(new Error(`Execution error: ${errorMsg}`));
      }
    };

    ws.onerror = (err) => {
      clearTimeout(timer);
      reject(err);
    };
  });
}

// Wait for completion and collect outputs
const outputs = await listenForCompletion(promptId);

See WebSocket Reference for detailed message types and handling binary preview images.

Step 3: Download Outputs

Once the job completes, download the generated files. The outputs object returned from WebSocket (or available via the history endpoint) contains output data organized by node ID. Each node’s output may contain images, video, or audio arrays with file metadata. Example outputs structure:

{
  "9": {
    "images": [
      {
        "filename": "ComfyUI_00001_.png",
        "subfolder": "",
        "type": "output"
      }
    ]
  }
}

The node ID ("9" in this example) corresponds to the SaveImage or other output nodes in your workflow. You can find these IDs by opening your workflow JSON file and looking for nodes with class_type like SaveImage, VHS_VideoCombine, etc.

# Download a single output file (follow 302 redirect with -L)
curl -L "$BASE_URL/api/view?filename=output.png&subfolder=&type=output" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY" \
  -o output.png

The /api/view endpoint returns a 302 redirect to a temporary signed URL. Your HTTP client must follow redirects to download the file.

Complete Example

Here’s a full end-to-end example combining all three steps:

import { readFile, writeFile } from "fs/promises";

const BASE_URL = "https://cloud.comfy.org";
const API_KEY = process.env.COMFY_CLOUD_API_KEY!;

async function main() {
  // 1. Load and modify workflow
  const workflow = JSON.parse(await readFile("workflow_api.json", "utf-8"));
  workflow["3"].inputs.seed = 42;
  workflow["6"].inputs.text = "a beautiful sunset";

  // 2. Submit workflow
  const response = await fetch(`${BASE_URL}/api/prompt`, {
    method: "POST",
    headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ prompt: workflow }),
  });
  const { prompt_id } = await response.json();
  console.log(`Job submitted: ${prompt_id}`);

  // 3. Poll for completion
  while (true) {
    const statusRes = await fetch(`${BASE_URL}/api/job/${prompt_id}/status`, {
      headers: { "X-API-Key": API_KEY },
    });
    const { status } = await statusRes.json();

    if (status === "completed") break;
    if (["failed", "cancelled"].includes(status)) {
      throw new Error(`Job ${status}`);
    }
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }

  // 4. Get outputs via job detail endpoint
  const jobRes = await fetch(`${BASE_URL}/api/jobs/${prompt_id}`, {
    headers: { "X-API-Key": API_KEY },
  });
  const job = await jobRes.json();
  const outputs = job.outputs;

  // 5. Download output files
  for (const nodeOutputs of Object.values(outputs)) {
    for (const fileInfo of (nodeOutputs as any).images ?? []) {
      const params = new URLSearchParams({
        filename: fileInfo.filename,
        subfolder: fileInfo.subfolder ?? "",
        type: "output",
      });
      const viewRes = await fetch(`${BASE_URL}/api/view?${params}`, {
        headers: { "X-API-Key": API_KEY },
        redirect: "manual",
      });
      const signedUrl = viewRes.headers.get("location")!;
      const fileRes = await fetch(signedUrl);
      await writeFile(`./${fileInfo.filename}`, Buffer.from(await fileRes.arrayBuffer()));
      console.log(`Downloaded: ${fileInfo.filename}`);
    }
  }
}

main();

Available Endpoints

Category	Description
Workflows	Submit workflows, check status
Jobs	Monitor job status and queue
Inputs	Upload images, masks, and other inputs
Outputs	Download generated content
WebSocket	Real-time progress updates
Object Info	Available nodes and their definitions

Next Steps

The quick start above covers the basics of submitting workflows and retrieving results. For more advanced use cases, refer to the Cloud API Reference:

Uploading Input Files - Upload images, masks, or other user-provided content for workflows that require external inputs
Modifying Workflow Inputs - Dynamically change workflow parameters like prompts, seeds, or node settings before submission
Using Partner Nodes - Call external AI services (Flux Pro, Ideogram, etc.) that require additional API key configuration
Queue Management - Monitor queue status, cancel jobs, or interrupt running executions
Error Handling - Handle HTTP errors, execution failures, and understand exception types

Additional resources:

OpenAPI Specification - Machine-readable API spec for code generation

​Comfy Cloud API

​Credits and Usage

​Base URL

​Authentication

​Getting an API Key

​Using the API Key

​Core Concepts

​Workflows

​Jobs

​Parallel Execution (Concurrent Jobs)

​Example: Submitting Multiple Jobs in Parallel

​Outputs

​Quick Start

​Step 1: Submit a Workflow

​Step 2: Monitor Job Progress

​Option A: Polling (Simple)

​Option B: WebSocket (Real-time Progress)

​Step 3: Download Outputs

​Complete Example

​Available Endpoints

​Next Steps

Comfy Cloud API

Credits and Usage

Base URL

Authentication

Getting an API Key

Using the API Key

Core Concepts

Workflows

Jobs

Parallel Execution (Concurrent Jobs)

Example: Submitting Multiple Jobs in Parallel

Outputs

Quick Start

Step 1: Submit a Workflow

Step 2: Monitor Job Progress

Option A: Polling (Simple)

Option B: WebSocket (Real-time Progress)

Step 3: Download Outputs

Complete Example

Available Endpoints

Next Steps