Learn › ComfyUI Advanced: Training, Kontext, and Automation › Building a Production Pipeline with the ComfyUI API

Building a Production Pipeline with the ComfyUI API

Advanced 🕐 13 min Lesson 10 of 12
What you'll learn
  • Build a FastAPI wrapper around the ComfyUI API with API key authentication, timeout handling, and error responses
  • Explain why run_in_executor is needed for the blocking WebSocket and urllib calls in an async FastAPI endpoint
  • Start ComfyUI headlessly on Vast.ai using tmux, with --listen 0.0.0.0 and --disable-auto-launch
  • Connect the production endpoint to n8n using an HTTP Request node with binary output handling

What a Production Pipeline Needs

The script from Lesson 9 works well for local use, but deploying it in a real application reveals several gaps:

  • No authentication: anyone who reaches port 8188 can submit prompts, view history, and read all generated images
  • No error handling: if ComfyUI crashes, runs out of VRAM mid-generation, or is unreachable, the script hangs or raises an unhandled exception
  • No timeout: a single generation can run for 10+ minutes on a slow GPU; if the process hangs, the script waits forever
  • No queue management: submitting too many concurrent requests can overload ComfyUI's queue or cause out-of-memory errors

The solution is a thin wrapper service that sits in front of ComfyUI and handles all of this. FastAPI is the right tool — it is fast, well-documented, and easy to deploy alongside ComfyUI on the same machine.

The FastAPI Wrapper

Install FastAPI and its dependencies: pip install fastapi uvicorn websocket-client python-multipart.

Create a file called comfyui_service.py alongside your workflow_api.json:

import asyncio
import json
import os
import random
import uuid
import urllib.parse
import urllib.request
from fastapi import FastAPI, Header, HTTPException
from fastapi.responses import Response
import websocket

COMFYUI = "127.0.0.1:8188"
API_KEY = os.environ.get("SERVICE_API_KEY", "changeme")
TIMEOUT = 300  # seconds before giving up on a generation

app = FastAPI()

with open("workflow_api.json") as f:
    BASE_WORKFLOW = json.load(f)

# Replace these with your workflow's actual node IDs
PROMPT_NODE = "6"   # CLIPTextEncode (positive)
SEED_NODE = "3"     # KSampler


def _queue_and_wait(prompt_text: str) -> bytes:
    workflow = json.loads(json.dumps(BASE_WORKFLOW))  # deep copy
    workflow[PROMPT_NODE]["inputs"]["text"] = prompt_text
    workflow[SEED_NODE]["inputs"]["seed"] = random.randint(0, 2**32)

    client_id = str(uuid.uuid4())
    prompt_id = str(uuid.uuid4())

    ws = websocket.WebSocket()
    ws.connect(f"ws://{COMFYUI}/ws?clientId={client_id}", timeout=10)

    body = json.dumps({
        "prompt": workflow,
        "client_id": client_id,
        "prompt_id": prompt_id,
    }).encode()
    req = urllib.request.Request(
        f"http://{COMFYUI}/prompt",
        data=body,
        headers={"Content-Type": "application/json"},
    )
    with urllib.request.urlopen(req, timeout=10) as resp:
        result = json.loads(resp.read())
        if "error" in result:
            raise RuntimeError(result["error"])

    ws.settimeout(TIMEOUT)
    while True:
        msg = ws.recv()
        if isinstance(msg, str):
            data = json.loads(msg)
            if data["type"] == "executing":
                d = data["data"]
                if d["node"] is None and d["prompt_id"] == prompt_id:
                    break
    ws.close()

    with urllib.request.urlopen(
        f"http://{COMFYUI}/history/{prompt_id}", timeout=10
    ) as resp:
        history = json.loads(resp.read())[prompt_id]

    for node_output in history["outputs"].values():
        for img in node_output.get("images", []):
            params = urllib.parse.urlencode({
                "filename": img["filename"],
                "subfolder": img["subfolder"],
                "type": img["type"],
            })
            with urllib.request.urlopen(
                f"http://{COMFYUI}/view?{params}", timeout=10
            ) as resp:
                return resp.read()

    raise RuntimeError("No images in output")


@app.post("/generate")
async def generate(
    prompt: str,
    x_api_key: str = Header(None),
):
    if x_api_key != API_KEY:
        raise HTTPException(status_code=401, detail="Invalid API key")
    try:
        image_bytes = await asyncio.get_event_loop().run_in_executor(
            None, _queue_and_wait, prompt
        )
        return Response(content=image_bytes, media_type="image/png")
    except TimeoutError:
        raise HTTPException(status_code=504, detail="Generation timed out")
    except RuntimeError as e:
        raise HTTPException(status_code=500, detail=str(e))

Start the service: uvicorn comfyui_service:app --host 0.0.0.0 --port 8000

To generate an image, make a POST request to /generate with a prompt query parameter and an X-Api-Key header:

curl -X POST 
  "http://localhost:8000/generate?prompt=a+portrait+of+a+woman" 
  -H "X-Api-Key: changeme" 
  --output result.png

Set the API key via environment variable before starting the service: SERVICE_API_KEY=your-secret-key uvicorn comfyui_service:app --host 0.0.0.0 --port 8000

Key Design Decisions in the Wrapper

Deep copy of the workflow: Each request gets a fresh copy of the base workflow (json.loads(json.dumps(BASE_WORKFLOW))) before modifications. Without this, concurrent requests would mutate the same object and mix up prompts between requests.

run_in_executor for blocking code: The WebSocket and urllib calls are blocking — they wait for network I/O. Running them directly in an async FastAPI endpoint blocks the event loop and prevents other requests from being handled. run_in_executor offloads the blocking work to a thread pool while the event loop stays free.

WebSocket timeout: ws.settimeout(TIMEOUT) causes ws.recv() to raise a TimeoutError if no message arrives within TIMEOUT seconds. This prevents the endpoint from hanging indefinitely if ComfyUI stops responding mid-generation.

API key in header: The key is sent as an HTTP header (X-Api-Key) rather than a query parameter. Query parameters appear in server logs and browser history; headers do not.

Deploying ComfyUI Headlessly on Vast.ai

For a persistent production setup where the service handles requests without you being logged in, deploy both ComfyUI and the FastAPI wrapper on a Vast.ai instance running continuously.

Starting ComfyUI headlessly: Launch it with the flags that disable the automatic browser launch and allow network access:

python main.py --listen 0.0.0.0 --disable-auto-launch --port 8188

Use tmux or screen to keep the process running after you disconnect from SSH:

tmux new-session -d -s comfyui 
  "python /workspace/ComfyUI/main.py --listen 0.0.0.0 --disable-auto-launch"
tmux new-session -d -s api 
  "cd /workspace && SERVICE_API_KEY=your-secret-key uvicorn comfyui_service:app --host 0.0.0.0 --port 8000"

Both processes now run in background tmux sessions. You can disconnect from SSH and they will continue running.

Port exposure: On Vast.ai, your instance exposes ports via port mappings. When creating or configuring the instance, add port 8000 to the exposed ports list. The console shows the external hostname and port number for each mapped port — this is the URL you use to reach your service from outside.

Important: exposing port 8000 means your FastAPI wrapper is publicly reachable. The API key in the X-Api-Key header is your only authentication. Use a strong, randomly generated key (at least 32 characters).

Calling the Pipeline from n8n

Once the service is running, any tool that can make HTTP requests can generate images. In n8n:

  1. Add an HTTP Request node.
  2. Set Method to POST.
  3. Set URL to http://YOUR_HOST:PORT/generate?prompt={{ $json.prompt }} — the {{ $json.prompt }} expression pulls the prompt text from the previous node's output.
  4. Add a header: X-Api-Key → your secret key.
  5. Set Response Format to File so n8n handles the binary image response correctly.

The n8n node outputs the image as binary data, which you can pass to a Write Binary File node, an email attachment node, an S3 upload node, or any other output step in your automation.

Queue Management and Concurrency

The current wrapper handles one request at a time per process — the WebSocket wait blocks until the generation finishes before accepting the next request. For most single-user setups, this is correct: ComfyUI itself can only run one generation at a time per GPU, so queueing in the wrapper prevents the ComfyUI queue from growing unbounded.

If you need concurrent request handling, the right approach is to submit multiple prompts to ComfyUI's queue (it handles them sequentially) and use separate WebSocket connections with different client_id values to track each one independently. The GET /queue endpoint returns how many prompts are pending, which you can use to implement backpressure — returning a 429 (Too Many Requests) response if the queue depth exceeds a threshold.

For high-throughput scenarios, run multiple ComfyUI instances on separate GPUs and distribute requests across them with a load balancer. Each instance is independent and handles its own queue.

Monitoring and Uptime

The GET /system_stats endpoint returns GPU usage, VRAM allocation, and system memory. Poll it from a monitoring script to detect if ComfyUI has crashed or run out of VRAM:

import urllib.request, json
with urllib.request.urlopen("http://localhost:8188/system_stats") as r:
    stats = json.loads(r.read())
    vram_free = stats["devices"][0]["vram_free"]
    print(f"VRAM free: {vram_free / 1024**3:.1f} GB")

If VRAM free drops to near zero and stays there, ComfyUI has likely stalled. The fix is to restart the ComfyUI process — in a tmux session, you can attach with tmux attach -t comfyui, stop the process, and restart it without losing the session.

Key takeaways
  • A deep copy of the workflow object is required for each request — mutating the shared base object causes concurrent requests to mix up prompts
  • run_in_executor offloads blocking WebSocket and urllib calls to a thread pool, keeping the FastAPI event loop free to handle other requests
  • ws.settimeout(TIMEOUT) on the WebSocket prevents the endpoint from hanging indefinitely if ComfyUI stops responding mid-generation
  • On Vast.ai, use tmux to keep ComfyUI and the FastAPI service running after SSH disconnects — both processes survive the disconnection in a background session
  • The GET /queue endpoint lets you implement backpressure by checking pending job depth before accepting a new request — return 429 if the queue is too deep
Learn more every week Get 5 hand-picked prompts + new AI tools every Monday. Free.