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: Running workflows via the API requires an active Comfy Cloud subscription. See pricing plans for details.

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

Visit https://platform.comfy.org/login and Log In

Please visit https://platform.comfy.org/login and log in with the corresponding account

Click `+ New` in API Keys to Create an API Key

Click + New in API Keys to create an API Key

Enter API Key Name

(Required) Enter the API Key name,
Click Generate to create

Save the Obtained API Key

Since the API Key is only visible upon first creation, please save it immediately after creation. It cannot be viewed later, so please keep it safe. Please note that you should not share your API Key with others. Once it leaked, you can delete it and create a new one.

Keep your API key secure. Never commit it to version control or share it publicly.

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 “Save (API Format)” 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

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 history endpoint
  const historyRes = await fetch(`${BASE_URL}/api/history_v2/${prompt_id}`, {
    headers: { "X-API-Key": API_KEY },
  });
  const history = await historyRes.json();
  const outputs = history.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

​Base URL

​Authentication

​Getting an API Key

​Using the API Key

​Core Concepts

​Workflows

​Jobs

​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

Base URL

Authentication

Getting an API Key

Using the API Key

Core Concepts

Workflows

Jobs

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