API workflows

DMAI NODES uses ComfyUI's native queue and workflow API. The node configs work without the custom frontend; image count, LoRA order, seed handling and validation run on the server.

Submit a workflow

Start ComfyUI, select model files in a starter workflow, and export it in API format. The included *.api.json examples can also be edited directly. UI workflow JSON and API workflow JSON have different structures.

python custom_nodes/DMAI-NODES/tools/run_workflow.py \
  --url http://127.0.0.1:8188 \
  --prompt "A sculptural object in soft studio light" \
  --count 2 --seed 481516 --gallery website-demo --wait

Run the command from your ComfyUI directory using its Python environment. The default example uses Krea 2 Turbo in Manual with enhancement none; it does not require the optional Krea enhancer. Use --workflow for a different included API example. The helper expects starter node IDs 1 (Prompter), 3 (Engine) and 4 (Gallery); adapt these lookups before using a workflow with different IDs. For the SDXL example, --checkpoint can set the installed checkpoint filename. Edit model selections in other API examples to match your catalog. This command queues real generation on your own server.

POST /prompt with {"prompt": <API workflow>, "client_id": "<unique ID>"}.
Keep the returned prompt_id.
Read GET /history/{prompt_id} for completion or errors. Comfy's /ws stream is available for progress.
Read Gallery output metadata or the gallery route below to fetch originals.

In a completed starter job, Gallery metadata is at history[prompt_id]["outputs"]["4"]["dmai_gallery"][0]. Its items contain original and thumbnail URLs. Use your Gallery node ID instead of "4" for other workflows. The Gallery does not emit Comfy's native UI images field; its typed IMAGE output remains available to downstream nodes. The paginated gallery route provides the full saved history.

Use seed strings for the full unsigned 64-bit range; JavaScript numbers cannot represent all of it exactly. Each image's exact seed is recorded in the Engine report. The CLI timeout only stops waiting; it does not cancel the job.

Engine sampling modes

Version 0.2.0 starts new Engines and all starter templates in "mode": "manual", with "preset_id": "" and "enhancer": "none" inside settings. Manual executes the validated settings values. Existing saved configs retain their mode and settings.

For DMAI Enhanced, use "mode": "enhanced", a selected preset_id, and the matching validated preset in the Engine's presets array. Presets are data, not uploaded executable code. The frontend exposes Upload JSON only in Enhanced and has no preset export button; headless clients supply the same configuration directly. See preset format and limits.

An Enhanced config with an empty preset_id fails with an actionable error: upload a DMAI JSON preset or switch to Manual. The server continues resolving historical built-in preset IDs for saved workflows and API templates. The bootstrap response retains that catalog for compatibility; its presence does not mean the frontend offers those presets as new choices. Current node IDs, request types, API routes and JSON schema versions are unchanged from 0.1.3.

Prompter ID migration

Since version 0.1.3, the Prompter's API class_type is DMAINodesPrompter. The request configuration, DMAI_PROMPT output and Engine connections keep the same contracts. Older DMAI packages still own DMAIPrompter; the server intentionally has no alias that could overwrite them.

Use the updated starter API files for new integrations. The included run_workflow.py converts identifiable 0.1.0-0.1.2 DMAI NODES Prompters in memory before submitting and leaves the source file intact. Direct /prompt callers should migrate their template first:

python custom_nodes/DMAI-NODES/tools/migrate_workflow.py old-workflow.api.json --output migrated-workflow.api.json

The offline tool also accepts saved UI workflows. It requires a new output path and never replaces the source. Only records matching the new package's configuration and connection contracts are converted. Legacy CLIP/conditioning Prompters and ambiguous records remain unchanged; do not replace every occurrence of DMAIPrompter globally. UI workflows loaded in Comfy's frontend are migrated before nodes are created.

Generation progress over WebSocket

Connect to ComfyUI's /ws?clientId=<client ID> before submitting the workflow. Use the same ID as client_id in POST /prompt. The Engine sends dmai_generation_progress messages to that client through ComfyUI's existing WebSocket:

{
  "type": "dmai_generation_progress",
  "data": {
    "prompt_id": "<queued prompt ID>",
    "node_id": "3",
    "phase": "sampling",
    "image_index": 1,
    "image_count": 2,
    "value": 4,
    "max": 8,
    "fraction": 0.6842105263
  }
}

Field	Meaning
`prompt_id`	Native ComfyUI execution ID; match it to the queued job.
`node_id`	Native executing Engine ID. Expanded subgraphs may use a different ID from the visible graph.
`phase`	`preparing`, `sampling`, `decoding`, `finalizing`, `complete`, `error` or `interrupted`.
`image_index` / `image_count`	Zero-based current image index and total requested images.
`value` / `max`	Current sampler progress counters; use them during `sampling`.
`fraction`	Monotonic completed-work fraction from 0 to 1 across this Engine invocation.

When available, display_node_id, real_node_id and parent_node_id provide ComfyUI's native subgraph mapping. Clients must match both the job and the intended Engine; receiving an event for another node does not advance this Engine.

The fraction normalizes each image's native sampler updates to its resolved step count, adds one unit after each completed decode, and reserves one final unit for assembling the Engine result. It measures completed work, not elapsed time. Model loading stays at zero. A sampler that emits no native progress advances only when its call returns; no timer simulates sampling progress. Internal VAE updates are excluded from the sampler counters.

Engine complete is not workflow completion. Gallery or other downstream nodes may still be running. The Prompter caps its display at 99% until ComfyUI emits native execution_success for the same prompt_id, so saved results are available before 100% appears. Handle native execution_error and execution_interrupted as failure/cancellation, including failures after the Engine has finished. Cached Engines may emit no package progress events; use native execution events and /history/{prompt_id} to determine the job's final state.

Progress observers exist only for the duration of Engine execution and are removed after success, failure or interruption. No additional WebSocket server is required.

Package endpoints

Routes are relative to ComfyUI's base URL. JSON responses use {"ok": true, "data": ...} or {"ok": false, "error": ...}. Downloads return file bytes.

Method	Route	Purpose
GET	`/dmai-nodes/v1/health`	Package version and capability flags
GET	`/dmai-nodes/v1/bootstrap`	Model profiles, installed files, LoRAs, historical preset catalog, runtime samplers and schedulers
POST	`/dmai-nodes/v1/presets/validate`	Validate a single JSON preset or pack
GET	`/dmai-nodes/v1/galleries/{gallery_id}?offset=0&limit=60`	Saved images, total and snapshot watermark
GET	`/dmai-nodes/v1/images/{image_id}`	Original PNG
GET	`/dmai-nodes/v1/images/{image_id}?thumbnail=1`	Small JPEG preview
GET	`/dmai-nodes/v1/images/{image_id}?download=1`	Original PNG with download disposition
POST	`/dmai-nodes/v1/galleries/{gallery_id}/zip`	Export selected original files

ZIP body: {"ids": ["<image ID>", "<image ID>"]}. To export a stable full-history snapshot, use {"all": true, "before": <watermark>}. Exports require 1–100 images and at most 2 GiB of original bytes. Pagination with before=<watermark> excludes newer images. An invalid, missing or cross-gallery image fails the whole export.

Gallery IDs are 1–64 letters, numbers, underscores or hyphens, beginning with a letter or number. The UI creates a persistent ID for each new Gallery; API clients must choose their own. A shared ID intentionally means shared history.

Saved PNG metadata includes the prompt and workflow when provided by ComfyUI. Treat exported images as potentially containing their generation recipe.

Connecting a future website

Use a server-side gateway between the website and ComfyUI:

Website → authenticated application server → ComfyUI /prompt
        ← application job/result endpoint ← /history + Gallery

The application server should own approved workflow templates, model allowlists, user authorization, quotas and job IDs. Send user prompts and selected settings into those templates. Keep ComfyUI on a private network or behind an authenticated proxy and TLS. Do not place server credentials in browser JavaScript.

This release supplies the headless node contract and local Gallery API. It does not implement website accounts, tenant isolation, billing, authentication or a public job gateway. Gallery IDs identify collections; they are not access-control tokens. ComfyUI cancellation is server-wide unless your gateway coordinates ownership.

Official reference: ComfyUI server routes.