File size: 5,617 Bytes
e4ab0d4 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 | # ComfyUI Server API Testing
Use this when an agent or maintainer needs to validate real ComfyUI execution,
not just static workflow JSON. It is useful for nodes that depend on ComfyUI's
runtime registry, hidden inputs, output nodes, prompt history, or file writes.
## What The AI Session Needs
The AI session needs three kinds of access:
1. Network access to the ComfyUI server. Usually this is
`http://127.0.0.1:8188`. If the agent sandbox blocks local networking, grant
network permission for the session.
2. Read access to the repository and test workflow files. The agent should
build or load API prompts from repo-local files where possible.
3. Write access to a safe output folder. Prefer a repo-local ignored folder,
such as `.tmp/comfy-loop-test-output/`, so generated images or EXRs do
not land in production show folders while the test is still experimental.
Do not give the agent broad write access to project drives just to test a node.
If the workflow under test normally writes to an external shot path, override the
output base path in the submitted API prompt.
## ComfyUI Settings And Server State
ComfyUI must already be running and listening on a reachable host/port.
Useful checks:
```powershell
Invoke-WebRequest -Uri http://127.0.0.1:8188/system_stats -UseBasicParsing
```
or from Python:
```python
import json
import urllib.request
with urllib.request.urlopen("http://127.0.0.1:8188/system_stats") as r:
print(json.load(r)["system"]["comfyui_version"])
```
For custom node changes:
- Run `dev-sync` only when explicitly requested.
- Restart ComfyUI after syncing Python files. The running process will not see a
new Python node until restart.
- Confirm node registration with `/object_info`:
```python
import json
import urllib.request
with urllib.request.urlopen("http://127.0.0.1:8188/object_info") as r:
info = json.load(r)
print("Koolook_LoopStatus" in info)
```
In the ComfyUI UI, enable the developer/API workflow option when you need to
manually export API-format workflows. The exact label can vary by frontend
version, but it is commonly under settings as developer mode / dev mode options,
which exposes "Save (API Format)".
## Canvas JSON Is Not API JSON
The normal saved workflow/canvas JSON is not what `/prompt` accepts. The API
prompt is a stripped graph shaped like this:
```json
{
"4": {
"class_type": "SaveEXRFrames",
"inputs": {
"images": ["21", 0],
"filepath": ["8", 0],
"start_frame": ["22", 0]
}
}
}
```
Each node id maps to `class_type` and `inputs`. Inputs are either literal widget
values or links in `[source_node_id, output_index]` form.
Subgraphs are another important difference. A canvas workflow can contain a
visual subgraph wrapper node, but `/prompt` needs the executable API graph. For
small tests, flatten the demo subgraph to the actual internal nodes. For larger
subgraphs, export API format from ComfyUI or build a converter that understands
the subgraph definition.
## Endpoints Used Most Often
| Endpoint | Use |
|---|---|
| `GET /system_stats` | Confirms the server is reachable and reports ComfyUI/Python/GPU state. |
| `GET /object_info` | Confirms node classes and input schemas are registered in the live server. |
| `POST /prompt` | Queues an API-format prompt. |
| `GET /history/{prompt_id}` | Checks completion status, errors, and output records for a queued prompt. |
| `GET /queue` | Shows running and pending prompts when debugging auto-queue behavior. |
## Safe Validation Pattern
1. Query `/system_stats`.
2. Query `/object_info` for every custom node used by the test.
3. Build an API prompt with a unique repo-local output folder.
4. Submit the prompt to `/prompt`.
5. Poll `/history/{prompt_id}` until the prompt completes or errors.
6. Check the expected files on disk.
7. For queue-controller nodes, keep polling the output folder or `/queue`,
because child prompts may be submitted after the first prompt finishes.
The loop demo has a reusable harness:
```powershell
.\.venv-codex\Scripts\python scripts\run_loop_demo_api_test.py
```
It writes to `.tmp/comfy-loop-test-output/run-*/`, which is ignored by
git.
## Lessons From The Loop Controller Work
- A saver that receives a batch and prints `4/4` is not the same as four
independent frame executions. Deep subgraphs that cannot accept sequences need
one prompt per frame.
- Easy-Use `forLoopStart` / `forLoopEnd` did not reliably re-enter this demo
graph as needed, so the working model became queue-driven: process frame 0,
save frame 0, then submit a child prompt with frame index 1.
- Hidden inputs such as `PROMPT` and `UNIQUE_ID` are available only inside
ComfyUI execution. They are what let a node inspect and resubmit its own API
prompt.
- Connected widgets can disappear from the visible widget value list. Do not
rely only on `widgets_values` order when a node has connectable optional
inputs. Prefer connected inputs, explicit node ids, or runtime inference from
the API prompt.
- ComfyUI caching can make a test look successful without re-running the saver.
Use unique output paths per test run when file writes are part of the proof.
## What To Document In PRs
When a PR includes ComfyUI-server validation, include:
- the server URL used, usually `http://127.0.0.1:8188`;
- the harness or command run;
- whether custom node code was dev-synced and whether ComfyUI was restarted;
- the expected output folder;
- exact success evidence, such as `status_str: success` and output file count;
- any warnings about API prompt flattening or canvas subgraphs.
|