Add API scripts (upload/download/run/convert) and API-format headswap workflow

workflows/api/head-swap-flux-klein.json

@@ -0,0 +1,378 @@
+{
+  "109": {
+    "class_type": "SamplerCustomAdvanced",
+    "inputs": {
+      "guider": [
+        "123",
+        0
+      ],
+      "latent_image": [
+        "113",
+        0
+      ],
+      "noise": [
+        "110",
+        0
+      ],
+      "sampler": [
+        "125",
+        0
+      ],
+      "sigmas": [
+        "122",
+        0
+      ]
+    }
+  },
+  "110": {
+    "class_type": "RandomNoise",
+    "inputs": {
+      "noise_seed": 432262096973493
+    }
+  },
+  "111": {
+    "class_type": "VAELoader",
+    "inputs": {
+      "vae_name": "flux2-vae.safetensors"
+    }
+  },
+  "112": {
+    "class_type": "GetImageSize",
+    "inputs": {
+      "image": [
+        "120",
+        0
+      ]
+    }
+  },
+  "113": {
+    "class_type": "EmptyFlux2LatentImage",
+    "inputs": {
+      "batch_size": 1,
+      "height": [
+        "112",
+        1
+      ],
+      "width": [
+        "112",
+        0
+      ]
+    }
+  },
+  "114:76": {
+    "class_type": "ReferenceLatent",
+    "inputs": {
+      "conditioning": [
+        "116:76",
+        0
+      ],
+      "latent": [
+        "114:78",
+        0
+      ]
+    }
+  },
+  "114:77": {
+    "class_type": "ReferenceLatent",
+    "inputs": {
+      "conditioning": [
+        "116:77",
+        0
+      ],
+      "latent": [
+        "114:78",
+        0
+      ]
+    }
+  },
+  "114:78": {
+    "class_type": "VAEEncode",
+    "inputs": {
+      "pixels": [
+        "121",
+        0
+      ],
+      "vae": [
+        "111",
+        0
+      ]
+    }
+  },
+  "115": {
+    "class_type": "CLIPLoader",
+    "inputs": {
+      "clip_name": "qwen_3_8b_fp8mixed.safetensors",
+      "device": "default",
+      "type": "flux2"
+    }
+  },
+  "116:76": {
+    "class_type": "ReferenceLatent",
+    "inputs": {
+      "conditioning": [
+        "119",
+        0
+      ],
+      "latent": [
+        "116:78",
+        0
+      ]
+    }
+  },
+  "116:77": {
+    "class_type": "ReferenceLatent",
+    "inputs": {
+      "conditioning": [
+        "117",
+        0
+      ],
+      "latent": [
+        "116:78",
+        0
+      ]
+    }
+  },
+  "116:78": {
+    "class_type": "VAEEncode",
+    "inputs": {
+      "pixels": [
+        "120",
+        0
+      ],
+      "vae": [
+        "111",
+        0
+      ]
+    }
+  },
+  "117": {
+    "_meta": {
+      "title": "CLIP Text Encode (Positive Prompt)"
+    },
+    "class_type": "CLIPTextEncode",
+    "inputs": {
+      "clip": [
+        "115",
+        0
+      ],
+      "text": "head_swap: start with Picture 1 as the base image, keeping its lighting, environment, and background. remove the head from Picture 1 completely and replace it with the head from Picture 2, strictly preserving the hair, eye color, nose structure of Picture 2. copy the direction of the eye, head rotation, micro expressions from Picture 1, high quality, sharp details, 4k.\n\nDescribe the expression in Picture 1 and copy it to the new image.\n"
+    }
+  },
+  "118": {
+    "class_type": "UNETLoader",
+    "inputs": {
+      "unet_name": "flux-2-klein-9b.safetensors",
+      "weight_dtype": "default"
+    }
+  },
+  "119": {
+    "_meta": {
+      "title": "CLIP Text Encode ( Negative Prompt)"
+    },
+    "class_type": "CLIPTextEncode",
+    "inputs": {
+      "clip": [
+        "115",
+        0
+      ],
+      "text": "bad quality, noise, blurry, worst quality, low resolution, blur, distortion, unnatural blending, cartoon, illustration, painting"
+    }
+  },
+  "120": {
+    "class_type": "ResizeImageMaskNode",
+    "inputs": {
+      "input": [
+        "76",
+        0
+      ],
+      "resize_type": "scale total pixels",
+      "resize_type.megapixels": 1.5,
+      "scale_method": "lanczos"
+    }
+  },
+  "121": {
+    "class_type": "ResizeImageMaskNode",
+    "inputs": {
+      "input": [
+        "187",
+        0
+      ],
+      "resize_type": "scale total pixels",
+      "resize_type.megapixels": 1.5,
+      "scale_method": "lanczos"
+    }
+  },
+  "122": {
+    "class_type": "Flux2Scheduler",
+    "inputs": {
+      "height": [
+        "112",
+        1
+      ],
+      "steps": 8,
+      "width": [
+        "112",
+        0
+      ]
+    }
+  },
+  "123": {
+    "class_type": "CFGGuider",
+    "inputs": {
+      "cfg": 1,
+      "model": [
+        "190",
+        0
+      ],
+      "negative": [
+        "114:76",
+        0
+      ],
+      "positive": [
+        "114:77",
+        0
+      ]
+    }
+  },
+  "125": {
+    "class_type": "KSamplerSelect",
+    "inputs": {
+      "sampler_name": "lcm"
+    }
+  },
+  "131": {
+    "class_type": "VAEDecode",
+    "inputs": {
+      "samples": [
+        "109",
+        0
+      ],
+      "vae": [
+        "111",
+        0
+      ]
+    }
+  },
+  "133": {
+    "class_type": "LoraLoaderModelOnly",
+    "inputs": {
+      "lora_name": "flux2/klein/bfs_head_v1_flux-klein_9b_step3500_rank128.safetensors",
+      "model": [
+        "118",
+        0
+      ],
+      "strength_model": 1
+    }
+  },
+  "160": {
+    "class_type": "ImageCropByMask",
+    "inputs": {
+      "image": [
+        "81",
+        0
+      ],
+      "mask": [
+        "81",
+        1
+      ]
+    }
+  },
+  "163": {
+    "class_type": "SaveImage",
+    "inputs": {
+      "filename_prefix": "headswap_flux_klein_optimized",
+      "images": [
+        "131",
+        0
+      ]
+    }
+  },
+  "176": {
+    "class_type": "ImageConcanate",
+    "inputs": {
+      "direction": "down",
+      "image1": [
+        "120",
+        0
+      ],
+      "image2": [
+        "121",
+        0
+      ],
+      "match_image_size": true
+    }
+  },
+  "177": {
+    "class_type": "ImageConcanate",
+    "inputs": {
+      "direction": "right",
+      "image1": [
+        "176",
+        0
+      ],
+      "image2": [
+        "131",
+        0
+      ],
+      "match_image_size": true
+    }
+  },
+  "178": {
+    "class_type": "PreviewImage",
+    "inputs": {
+      "images": [
+        "177",
+        0
+      ]
+    }
+  },
+  "187": {
+    "class_type": "RMBG",
+    "inputs": {
+      "background": "Alpha",
+      "image": [
+        "81",
+        0
+      ],
+      "invert_output": false,
+      "mask_blur": 0,
+      "mask_offset": 0,
+      "model": "RMBG-2.0",
+      "process_res": 1024,
+      "refine_foreground": false,
+      "sensitivity": 1
+    }
+  },
+  "190": {
+    "_meta": {
+      "title": "Lissie lora"
+    },
+    "class_type": "LoraLoaderModelOnly",
+    "inputs": {
+      "lora_name": "lissie_flux2_klein.safetensors",
+      "model": [
+        "133",
+        0
+      ],
+      "strength_model": 1
+    }
+  },
+  "76": {
+    "_meta": {
+      "title": "Body Reference"
+    },
+    "class_type": "LoadImage",
+    "inputs": {
+      "image": "general_image.jpg"
+    }
+  },
+  "81": {
+    "_meta": {
+      "title": "Face Reference"
+    },
+    "class_type": "LoadImage",
+    "inputs": {
+      "image": "reference_face.JPG"
+    }
+  }
+}

workflows/scripts/convert_workflow.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""Convert a ComfyUI workflow from UI format (Save/Workflow menu) to API format.
+
+Equivalent to the frontend's Workflow > Export (API), but headless. Needs a
+running ComfyUI instance because widget-to-input mapping comes from its
+GET /object_info (so the instance must have the same custom nodes installed
+as the workflow uses).
+
+Handles: subgraphs (flattened, ids become "<instance>:<inner>"), Reroute
+splicing, bypassed (mode 4) nodes with type-matched pass-through, muted
+(mode 2) nodes, widget-converted-to-input entries, and the phantom
+control_after_generate value that follows every seed widget.
+
+Example:
+    python convert_workflow.py --url http://127.0.0.1:7865 \
+        ../head-swap-flux-klein.json -o ../api/head-swap-flux-klein.json
+"""
+import argparse
+import json
+import pathlib
+import sys
+
+import requests
+
+VIRTUAL_TYPES = {"Reroute", "Note", "MarkdownNote", "PrimitiveNode"}
+WIDGET_SCALAR_TYPES = {"INT", "FLOAT", "STRING", "BOOLEAN", "COMBO"}
+SUBGRAPH_INPUT_ID = -10
+SUBGRAPH_OUTPUT_ID = -20
+
+
+class Scope:
+    """One graph namespace: either the root workflow or a subgraph instance."""
+
+    def __init__(self, graph, prefix="", parent=None, instance_id=None):
+        self.nodes = {n["id"]: n for n in graph.get("nodes", [])}
+        self.links = {}
+        for l in graph.get("links", []):
+            if isinstance(l, dict):  # subgraph defs store links as objects
+                self.links[l["id"]] = (l["origin_id"], l["origin_slot"], l["target_id"], l["target_slot"])
+            else:  # root stores [id, src, src_slot, dst, dst_slot, type]
+                self.links[l[0]] = (l[1], l[2], l[3], l[4])
+        self.prefix = prefix
+        self.parent = parent            # (parent Scope, instance node id) or None
+        self.instance_id = instance_id
+        self.children = {}              # instance node id -> child Scope
+
+    def fid(self, node_id):
+        return f"{self.prefix}{node_id}"
+
+
+class Converter:
+    def __init__(self, workflow, object_info):
+        self.oi = object_info
+        self.subgraph_defs = {
+            sg["id"]: sg for sg in workflow.get("definitions", {}).get("subgraphs", [])
+        }
+        self.root = Scope(workflow)
+        self._build_children(self.root)
+
+    def _build_children(self, scope):
+        for nid, node in scope.nodes.items():
+            sg = self.subgraph_defs.get(node["type"])
+            if sg is not None:
+                child = Scope(sg, prefix=f"{scope.fid(nid)}:", parent=(scope, nid), instance_id=nid)
+                scope.children[nid] = child
+                self._build_children(child)
+
+    def all_scopes(self):
+        stack = [self.root]
+        while stack:
+            s = stack.pop()
+            yield s
+            stack.extend(s.children.values())
+
+    def resolve(self, scope, link_id):
+        """Follow a link upstream to a real executable (node_fid, output_slot), or None."""
+        if link_id is None or link_id not in scope.links:
+            return None
+        origin_id, origin_slot, _, _ = scope.links[link_id]
+
+        if origin_id == SUBGRAPH_INPUT_ID:  # crossed into this subgraph from outside
+            parent_scope, instance_id = scope.parent
+            instance = parent_scope.nodes[instance_id]
+            outer_link = instance["inputs"][origin_slot].get("link")
+            return self.resolve(parent_scope, outer_link)
+
+        node = scope.nodes[origin_id]
+        ntype = node["type"]
+
+        if ntype in self.subgraph_defs:  # source is a subgraph instance: descend
+            child = scope.children[origin_id]
+            for lid, (_, _, tid, tslot) in child.links.items():
+                if tid == SUBGRAPH_OUTPUT_ID and tslot == origin_slot:
+                    return self.resolve(child, lid)
+            return None
+
+        if ntype == "Reroute":
+            return self.resolve(scope, node["inputs"][0].get("link"))
+
+        mode = node.get("mode", 0)
+        if mode == 2:  # muted: acts as removed
+            return None
+        if mode == 4:  # bypassed: pass through first linked input of matching type
+            out_type = node["outputs"][origin_slot].get("type", "*")
+            for inp in node.get("inputs", []):
+                if inp.get("link") is None:
+                    continue
+                in_type = inp.get("type", "*")
+                if in_type == out_type or "*" in (in_type, out_type):
+                    return self.resolve(scope, inp["link"])
+            return None
+
+        return (scope.fid(origin_id), origin_slot)
+
+    def widget_inputs(self, node):
+        """Map a node's widgets_values onto named inputs using /object_info order."""
+        spec = self.oi[node["type"]].get("input", {})
+        ordered = list(spec.get("required", {}).items()) + list(spec.get("optional", {}).items())
+        values = node.get("widgets_values") or []
+        if isinstance(values, dict):  # some packs (rgthree) serialize by name
+            widget_names = {name for name, s in ordered if self._is_widget(s)}
+            return {k: v for k, v in values.items() if k in widget_names}
+        result = {}
+        self._consume_widgets(ordered, list(values), result)
+        return result
+
+    def _consume_widgets(self, ordered, queue, result, prefix=""):
+        for name, s in ordered:
+            if not queue:
+                return
+            opts = s[1] if len(s) > 1 and isinstance(s[1], dict) else {}
+            if s[0] == "COMFY_DYNAMICCOMBO_V3":
+                # the selection is one widget value; the chosen option pulls in
+                # nested inputs addressed with dotted ids ("resize_type.megapixels")
+                selected = queue.pop(0)
+                result[f"{prefix}{name}"] = selected
+                option = next((o for o in opts.get("options", []) if o["key"] == selected), None)
+                if option:
+                    inner = option["inputs"]
+                    inner_ordered = (list(inner.get("required", {}).items())
+                                     + list(inner.get("optional", {}).items()))
+                    self._consume_widgets(inner_ordered, queue, result, prefix=f"{prefix}{name}.")
+            elif self._is_widget(s):
+                result[f"{prefix}{name}"] = queue.pop(0)
+                if opts.get("control_after_generate") and queue:
+                    queue.pop(0)  # discard the UI-only fixed/increment/randomize widget
+
+    @staticmethod
+    def _is_widget(s):
+        kind = s[0]
+        opts = s[1] if len(s) > 1 and isinstance(s[1], dict) else {}
+        if opts.get("forceInput"):
+            return False
+        return isinstance(kind, list) or kind in WIDGET_SCALAR_TYPES
+
+    def convert(self):
+        prompt = {}
+        for scope in self.all_scopes():
+            for nid, node in scope.nodes.items():
+                ntype = node["type"]
+                if (ntype in VIRTUAL_TYPES or ntype in self.subgraph_defs
+                        or node.get("mode", 0) in (2, 4)):
+                    continue
+                if ntype not in self.oi:
+                    raise SystemExit(
+                        f"ERROR: node {scope.fid(nid)} has type {ntype!r} which the ComfyUI "
+                        "instance does not know -- install its custom nodes first")
+                inputs = self.widget_inputs(node)
+                for inp in node.get("inputs", []):
+                    source = self.resolve(scope, inp.get("link"))
+                    if source is not None:
+                        inputs[inp["name"]] = list(source)
+                    elif inp.get("link") is not None and not inp.get("widget"):
+                        print(f"warning: {scope.fid(nid)} ({ntype}) input {inp['name']!r} "
+                              "leads to a muted/bypassed dead end; leaving unconnected",
+                              file=sys.stderr)
+                entry = {"class_type": ntype, "inputs": inputs}
+                title = node.get("title")
+                if title:
+                    entry["_meta"] = {"title": title}
+                prompt[scope.fid(nid)] = entry
+        return prompt
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--url", required=True, help="ComfyUI base URL (source of /object_info)")
+    ap.add_argument("workflow", help="UI-format workflow JSON")
+    ap.add_argument("-o", "--output", help="where to write the API JSON (default: stdout)")
+    args = ap.parse_args()
+
+    wf = json.loads(pathlib.Path(args.workflow).read_text())
+    if "nodes" not in wf:
+        sys.exit("ERROR: input already looks like API format (no 'nodes' array)")
+
+    object_info = requests.get(f"{args.url.rstrip('/')}/object_info", timeout=120).json()
+    prompt = Converter(wf, object_info).convert()
+    out = json.dumps(prompt, indent=2, sort_keys=True)
+    if args.output:
+        pathlib.Path(args.output).write_text(out + "\n")
+        print(f"wrote {args.output} ({len(prompt)} nodes)", file=sys.stderr)
+    else:
+        print(out)
+
+
+if __name__ == "__main__":
+    main()

workflows/scripts/download_files.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Download files from a ComfyUI instance's output (or input/temp) folder.
+
+Uses ComfyUI's built-in GET /view endpoint. File names may include a
+subfolder ("qwen_edit/2026-07-07/img_00001_.webp") -- the same strings
+run_workflow.py prints when a job finishes. Prints the local path of each
+downloaded file to stdout.
+
+Examples:
+    python download_files.py --url https://POD-7865.proxy.runpod.net headswap_00001_.png
+    python download_files.py --url http://127.0.0.1:7865 --out results a/x.png b/y.png
+"""
+import argparse
+import pathlib
+import sys
+
+import requests
+
+
+def download_file(base_url, name, folder_type="output", out_dir=".", timeout=300):
+    """Download one file by its ComfyUI reference name; returns the local path."""
+    ref = pathlib.PurePosixPath(name)
+    r = requests.get(
+        f"{base_url.rstrip('/')}/view",
+        params={
+            "filename": ref.name,
+            "subfolder": str(ref.parent) if str(ref.parent) != "." else "",
+            "type": folder_type,
+        },
+        timeout=timeout,
+    )
+    r.raise_for_status()
+    dest = pathlib.Path(out_dir) / name
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_bytes(r.content)
+    return dest
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--url", required=True, help="ComfyUI base URL, e.g. https://POD-7865.proxy.runpod.net")
+    ap.add_argument("--type", default="output", choices=["output", "input", "temp"],
+                    help="which ComfyUI folder to read from (default: output)")
+    ap.add_argument("--out", default=".", help="local directory to save into (default: cwd)")
+    ap.add_argument("names", nargs="+", help='file names, optionally with subfolder ("sub/file.png")')
+    args = ap.parse_args()
+
+    failed = False
+    for name in args.names:
+        try:
+            dest = download_file(args.url, name, args.type, args.out)
+        except (OSError, requests.RequestException) as e:
+            print(f"ERROR downloading {name}: {e}", file=sys.stderr)
+            failed = True
+            continue
+        print(f"downloaded {args.type}/{name} -> {dest} ({dest.stat().st_size} bytes)", file=sys.stderr)
+        print(dest)
+    sys.exit(1 if failed else 0)
+
+
+if __name__ == "__main__":
+    main()

workflows/scripts/run_workflow.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Run an API-format ComfyUI workflow synchronously and wait for it to finish.
+
+Queues the workflow via POST /prompt, polls GET /history/{prompt_id} until the
+job completes, then prints one reference name per produced output file to
+stdout ("file.png" or "subfolder/file.png") -- feed those straight to
+download_files.py. Exits non-zero on validation or execution failure, with
+ComfyUI's error details on stderr.
+
+The workflow must be API format (flat {"<id>": {"class_type": ...}} dict).
+Export one from the UI with Workflow > Export (API), or convert a saved UI
+JSON with convert_workflow.py.
+
+Runtime patching (so workflow files stay generic):
+    --set NODE_ID.INPUT=VALUE   override any node input, e.g. --set 76.image=body.jpg
+                                (VALUE is parsed as JSON when possible, else kept as string)
+    --prefix PREFIX             set filename_prefix on every node that has one,
+                                e.g. --prefix "headswap/%year%%month%%day%-%hour%%minute%%second%"
+    --randomize-seeds           randomize every seed/noise_seed input (on by default;
+                                disable with --keep-seeds for reproducible reruns)
+
+Example:
+    python run_workflow.py --url https://POD-7865.proxy.runpod.net \
+        ../api/head-swap-flux-klein.json \
+        --set 76.image=body.jpg --set 81.image=head.jpg \
+        --prefix "headswap/%year%%month%%day%-%hour%%minute%%second%"
+"""
+import argparse
+import json
+import pathlib
+import random
+import sys
+import time
+import uuid
+
+import requests
+
+SEED_INPUT_NAMES = ("seed", "noise_seed")
+
+
+def parse_set(spec):
+    """'76.image=body.jpg' -> ('76', 'image', 'body.jpg'). Values parse as JSON when possible."""
+    try:
+        target, raw = spec.split("=", 1)
+        node_id, input_name = target.split(".", 1)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"--set expects NODE_ID.INPUT=VALUE, got {spec!r}")
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError:
+        value = raw
+    return node_id, input_name, value
+
+
+def collect_output_files(history_entry):
+    """Yield (ref_name, folder_type) for every file any output node produced."""
+    for node_output in history_entry.get("outputs", {}).values():
+        for value in node_output.values():
+            if not isinstance(value, list):
+                continue
+            for item in value:
+                if isinstance(item, dict) and "filename" in item:
+                    name = item["filename"]
+                    if item.get("subfolder"):
+                        name = f"{item['subfolder']}/{name}"
+                    yield name, item.get("type", "output")
+
+
+def run(base_url, workflow, timeout=900, poll_interval=2.0, quiet=False):
+    """Queue an API-format workflow and block until done. Returns the history entry."""
+    base_url = base_url.rstrip("/")
+    r = requests.post(
+        f"{base_url}/prompt",
+        json={"prompt": workflow, "client_id": str(uuid.uuid4())},
+        timeout=60,
+    )
+    if r.status_code != 200:
+        try:
+            detail = json.dumps(r.json(), indent=2)
+        except ValueError:
+            detail = r.text
+        raise RuntimeError(f"queueing failed (HTTP {r.status_code}):\n{detail}")
+    prompt_id = r.json()["prompt_id"]
+    if not quiet:
+        print(f"queued prompt {prompt_id}", file=sys.stderr)
+
+    start = time.monotonic()
+    while True:
+        elapsed = time.monotonic() - start
+        if elapsed > timeout:
+            raise RuntimeError(f"timed out after {timeout}s waiting for prompt {prompt_id}")
+        h = requests.get(f"{base_url}/history/{prompt_id}", timeout=60).json()
+        if prompt_id in h:
+            entry = h[prompt_id]
+            status = entry.get("status", {})
+            if status.get("status_str") == "error":
+                messages = json.dumps(status.get("messages", []), indent=2)
+                raise RuntimeError(f"workflow execution failed:\n{messages}")
+            return entry
+        if not quiet:
+            print(f"  waiting... {int(elapsed)}s", file=sys.stderr)
+        time.sleep(poll_interval)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--url", required=True, help="ComfyUI base URL, e.g. https://POD-7865.proxy.runpod.net")
+    ap.add_argument("workflow", help="path to an API-format workflow JSON")
+    ap.add_argument("--set", dest="sets", type=parse_set, action="append", default=[],
+                    metavar="NODE_ID.INPUT=VALUE", help="override a node input (repeatable)")
+    ap.add_argument("--prefix", help="set filename_prefix on every node that has one")
+    ap.add_argument("--keep-seeds", action="store_true",
+                    help="keep the seeds saved in the workflow instead of randomizing")
+    ap.add_argument("--timeout", type=float, default=900, help="max seconds to wait (default 900)")
+    ap.add_argument("--poll", type=float, default=2.0, help="poll interval in seconds (default 2)")
+    args = ap.parse_args()
+
+    workflow = json.loads(pathlib.Path(args.workflow).read_text())
+    if "nodes" in workflow and "class_type" not in next(iter(workflow.values()), {}):
+        sys.exit("ERROR: this is a UI-format workflow. Convert it first: "
+                 "python convert_workflow.py --url <URL> <workflow.json>")
+
+    for node_id, input_name, value in args.sets:
+        if node_id not in workflow:
+            sys.exit(f"ERROR: --set references unknown node id {node_id!r}")
+        workflow[node_id]["inputs"][input_name] = value
+        print(f"set {node_id}.{input_name} = {value!r}", file=sys.stderr)
+
+    if args.prefix:
+        for node_id, node in workflow.items():
+            if "filename_prefix" in node.get("inputs", {}):
+                node["inputs"]["filename_prefix"] = args.prefix
+                print(f"set {node_id}.filename_prefix = {args.prefix!r}", file=sys.stderr)
+
+    if not args.keep_seeds:
+        for node_id, node in workflow.items():
+            for name in SEED_INPUT_NAMES:
+                if isinstance(node.get("inputs", {}).get(name), int):
+                    node["inputs"][name] = random.randrange(2**48)
+                    print(f"randomized {node_id}.{name} = {node['inputs'][name]}", file=sys.stderr)
+
+    try:
+        entry = run(args.url, workflow, timeout=args.timeout, poll_interval=args.poll)
+    except (requests.RequestException, RuntimeError) as e:
+        sys.exit(f"ERROR: {e}")
+
+    outputs = list(collect_output_files(entry))
+    saved = [name for name, ftype in outputs if ftype == "output"]
+    temp = [name for name, ftype in outputs if ftype != "output"]
+    if temp:
+        print(f"({len(temp)} preview/temp file(s) not listed: {', '.join(temp)})", file=sys.stderr)
+    if not saved:
+        print("workflow finished but produced no saved output files", file=sys.stderr)
+    for name in saved:
+        print(name)
+
+
+if __name__ == "__main__":
+    main()

workflows/scripts/upload_files.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Upload local files into a ComfyUI instance's input folder.
+
+Uses ComfyUI's built-in POST /upload/image endpoint. Prints one reference
+name per uploaded file to stdout ("name.png" or "subfolder/name.png") --
+exactly the string a LoadImage node's `image` input expects.
+
+ComfyUI dedups colliding names by renaming to "name (1).png" unless
+--overwrite is given, so ALWAYS use the printed name, not the local one.
+
+Examples:
+    python upload_files.py --url https://POD-7865.proxy.runpod.net head.jpg body.jpg
+    python upload_files.py --url http://127.0.0.1:7865 --subfolder demo --overwrite *.png
+"""
+import argparse
+import pathlib
+import sys
+
+import requests
+
+
+def upload_file(base_url, path, subfolder="", overwrite=False, timeout=120):
+    """Upload one file; returns the reference name to use in a workflow."""
+    path = pathlib.Path(path)
+    with path.open("rb") as f:
+        r = requests.post(
+            f"{base_url.rstrip('/')}/upload/image",
+            files={"image": (path.name, f)},
+            data={
+                "subfolder": subfolder,
+                "overwrite": "true" if overwrite else "false",
+                "type": "input",
+            },
+            timeout=timeout,
+        )
+    r.raise_for_status()
+    info = r.json()
+    name = info["name"]
+    if info.get("subfolder"):
+        name = f"{info['subfolder']}/{name}"
+    return name
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--url", required=True, help="ComfyUI base URL, e.g. https://POD-7865.proxy.runpod.net")
+    ap.add_argument("--subfolder", default="", help="subfolder under ComfyUI/input/ to upload into")
+    ap.add_argument("--overwrite", action="store_true", help="replace existing files instead of auto-renaming")
+    ap.add_argument("files", nargs="+", help="local files to upload")
+    args = ap.parse_args()
+
+    failed = False
+    for f in args.files:
+        try:
+            name = upload_file(args.url, f, args.subfolder, args.overwrite)
+        except (OSError, requests.RequestException) as e:
+            print(f"ERROR uploading {f}: {e}", file=sys.stderr)
+            failed = True
+            continue
+        print(f"uploaded {f} -> input/{name}", file=sys.stderr)
+        print(name)
+    sys.exit(1 if failed else 0)
+
+
+if __name__ == "__main__":
+    main()