Files

T

Arcum42 b4740cb968 Updating reference docs.

2026-07-01 12:20:05 -07:00

11 KiB

Raw Permalink Blame History

title, description

title	description
Cloud API Overview	Programmatic access to Comfy Cloud for running workflows, managing files, and monitoring execution

import PollJobCompletion from '/snippets/cloud/poll-job-completion.mdx' import WebSocketProgress from '/snippets/cloud/websocket-progress.mdx' import DownloadOutputs from '/snippets/cloud/download-outputs.mdx' import CompleteExample from '/snippets/cloud/complete-example.mdx' import GetApiKey from '/snippets/get-api-key.mdx'

**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](https://www.comfy.org/cloud/pricing?utm_source=docs&utm_campaign=cloud-api) 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:

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

const API_KEY = process.env.COMFY_CLOUD_API_KEY!;

const response = await fetch("https://cloud.comfy.org/api/user", {
  headers: { "X-API-Key": API_KEY },
});
const user = await response.json();

import os
import requests

API_KEY = os.environ["COMFY_CLOUD_API_KEY"]
headers = {"X-API-Key": API_KEY}

response = requests.get(
    "https://cloud.comfy.org/api/user",
    headers=headers
)

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](https://www.comfy.org/cloud/pricing?utm_source=docs&utm_campaign=cloud-api) for subscription details.

Example: Submitting Multiple Jobs in Parallel

```python Python 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())


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

async function submitWorkflow(
  workflow: Record<string, any>
): Promise<string> {
  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 }),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return (await response.json()).prompt_id;
}

async function main() {
  const base = JSON.parse(
    await Deno.readTextFile("workflow_api.json")
  );

  // Create variations by changing the seed
  const seeds = [42, 123, 456];
  const workflows = seeds.map((seed) => {
    const wf = structuredClone(base);
    wf["3"].inputs.seed = seed;
    return wf;
  });

  // Submit all workflows concurrently
  const promptIds = await Promise.all(
    workflows.map((wf) => submitWorkflow(wf))
  );

  for (const pid of promptIds) {
    console.log(`Job submitted: ${pid}`);
  }

  // Poll or use WebSocket to monitor each job...
}

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

```bash curl 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)"'}' ```

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

// Load your workflow (exported from ComfyUI in API format)
const workflow = JSON.parse(await Deno.readTextFile("workflow_api.json"));

// Submit the 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 result = await response.json();
const promptId = result.prompt_id;
console.log(`Job submitted: ${promptId}`);

import os
import requests
import json

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

def get_headers():
    return {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# Load your workflow (exported from ComfyUI in API format)
with open("workflow_api.json") as f:
    workflow = json.load(f)

# Submit the workflow
response = requests.post(
    f"{BASE_URL}/api/prompt",
    headers=get_headers(),
    json={"prompt": workflow}
)
result = response.json()
prompt_id = result["prompt_id"]
print(f"Job submitted: {prompt_id}")

Step 2: Monitor Job Progress

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

Option A: Polling (Simple)

Option B: WebSocket (Real-time Progress)

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

See [WebSocket Reference](/development/cloud/api-reference#websocket-for-real-time-progress) 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.

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:

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

11 KiB Raw Permalink Blame History