Building a Production Pipeline with the ComfyUI API
- 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:
- Add an HTTP Request node.
- Set Method to POST.
- 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. - Add a header:
X-Api-Key→ your secret key. - 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.
- 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
Progress is saved in this browser only — clear your cache or switch device and it's gone. Create a free account and it follows you everywhere.