Hash Vault: optional payload_string + three extra any-type slots, v1.2.0

Dropped the forceInput=True on payload_string so the socket is truly
optional. Added any_input_2, any_input_3, any_input_4 alongside the
existing any_input. Users can now hash purely on image + converted-
widget values without manufacturing a synthetic payload string.

Primary use case: image-only APIs with meaningful widgets. For a
Gemini Style Transfer node with (image, style dropdown, strength
float) and no prompt, convert the style and strength widgets to
inputs, then wire image -> any_input, style -> any_input_2,
strength -> any_input_3. All three factor into the hash.

Back-compat: workflows that only use payload_string + any_input
produce bit-identical hash keys to v1.0/v1.1. The "__slotN:" prefix
only appears when slots 2-4 are actually wired, so existing
hash_vault/ entries keep hitting. Verified with a direct comparison
against the pre-v1.2 hashing path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jeremieLouvaert

README.md

@@ -20,7 +20,7 @@ Acts as a circuit-breaker for your wallet. Pass your prompt or image through thi
 
 ComfyUI's native caching often breaks with external API nodes (dynamic timestamps, non-deterministic seeds). The Hash Vault is an aggressive disk-caching layer that strictly hashes your prompt, parameters, and input tensors.
 
-- **Hash Vault (Check Cache):** Hashes your inputs and checks local disk for a cached result.
+- **Hash Vault (Check Cache):** Hashes any combination of a prompt STRING and up to four `any_input` slots — wire an image, a converted-widget dropdown, a converted-widget float, whatever defines uniqueness for your API call. All inputs are optional; any subset you connect factors into the cache key. No prompt? Hash on image + widget values alone.
 - **Lazy API Switch:** Uses ComfyUI's `{"lazy": True}` evaluation engine. On a cache hit, this switch **physically prevents** the upstream API node from executing — saving money and time.
 - **Hash Vault (Save Result):** Writes new API outputs to the vault for future cache hits.
 
@@ -43,6 +43,16 @@ To properly bypass an API node, sandwich it with the vault nodes:
 4. Connect the output of your API Node to **Save Result** (using the `hash_key` from step 1).
 5. Connect both the `cached_data` (from step 1) and the `api_data` (from step 4) to the **Lazy API Switch**.
 
+### What to feed Check Cache
+
+Check Cache has one STRING socket (`payload_string`) and four any-type sockets (`any_input`, `any_input_2`, `any_input_3`, `any_input_4`). All are optional — connect whatever defines uniqueness for your API call:
+
+- **Prompt-driven API (e.g. Gemini Image Generate):** wire the prompt STRING to `payload_string`. Done.
+- **Image + prompt API (e.g. image edit):** prompt → `payload_string`, image → `any_input`.
+- **Image-only API with widgets (e.g. Gemini Style Transfer — no prompt, but a style dropdown and strength float):** right-click the style widget → Convert Widget to Input, same for strength. Wire image → `any_input`, style → `any_input_2`, strength → `any_input_3`. All three factor into the hash; changing any of them produces a new cache key.
+
+Any subset of slots works; unused slots contribute nothing to the hash. Adding or ignoring `any_input_2/3/4` in a new workflow doesn't invalidate existing cache keys from older workflows that only used `payload_string` + `any_input`.
+
 ```
                            ┌─────────────┐
               ┌───────────►│  API Node    ├──► 💾 Save Result ──┐

api_optimizer_nodes.py

@@ -142,11 +142,13 @@ class DeterministicHashVault:
     @classmethod
     def INPUT_TYPES(s):
         return {
-            "required": {
-                "payload_string": ("STRING", {"forceInput": True, "tooltip": "Connect your prompt or JSON params here"}),
-            },
             "optional": {
-                "any_input": (any_type, {"tooltip": "Optional: Connect init image or latent to factor into hash"}),
+                "payload_string": ("STRING", {"forceInput": True,
+                                               "tooltip": "Prompt, JSON params, or any STRING that should factor into the cache key. Optional — you can hash purely on any_input slots if you prefer."}),
+                "any_input":    (any_type, {"tooltip": "Any input to hash: image, latent, conditioning, or a converted widget (convert a downstream node's widget to input and wire it here). Content is hashed recursively."}),
+                "any_input_2":  (any_type, {"tooltip": "Second any-type input. Use one slot per widget you want to factor into the cache key — e.g. image on any_input, style dropdown on any_input_2, strength float on any_input_3."}),
+                "any_input_3":  (any_type, {"tooltip": "Third any-type input."}),
+                "any_input_4":  (any_type, {"tooltip": "Fourth any-type input."}),
                 "cache_ttl_hours": ("FLOAT", {"default": 0.0, "min": 0.0, "max": 8760.0, "step": 1.0,
                                                "tooltip": "Cache time-to-live in hours. 0 = never expires"}),
             }
@@ -183,13 +185,30 @@ def _hash_value(self, hash_obj, value):
         else:
             hash_obj.update(str(value).encode("utf-8"))
 
-    def check_vault(self, payload_string, any_input=None, cache_ttl_hours=0.0):
+    def check_vault(self, payload_string="", any_input=None,
+                    any_input_2=None, any_input_3=None, any_input_4=None,
+                    cache_ttl_hours=0.0):
         hash_obj = hashlib.sha256()
-        hash_obj.update(str(payload_string).encode("utf-8"))
 
+        # payload_string is optional as of v1.2.0; an empty string still
+        # contributes a stable (empty) marker so pre-v1.2 workflows that
+        # explicitly passed "" as the payload produce the same hash they
+        # used to.
+        hash_obj.update(str(payload_string or "").encode("utf-8"))
+
+        # any_input hashing is bit-identical to v1.0/v1.1 to preserve existing
+        # cache keys — unchanged workflows keep hitting their existing entries.
         if any_input is not None:
             self._hash_value(hash_obj, any_input)
 
+        # New slots introduced in v1.2.0. The "__slotN:" prefix only appears
+        # when the slot is actually wired, so adding these inputs to the node
+        # doesn't perturb hashes for workflows that only use any_input.
+        for slot_idx, value in enumerate((any_input_2, any_input_3, any_input_4), start=2):
+            if value is not None:
+                hash_obj.update(f"__slot{slot_idx}:".encode("utf-8"))
+                self._hash_value(hash_obj, value)
+
         hash_key = hash_obj.hexdigest()
 
         vault_dir = os.path.join(folder_paths.get_output_directory(), "hash_vault")

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "comfyui-api-optimizer"
 description = "API cost tracking, deterministic hash caching, and lazy execution bypass for cloud API workflows"
-version = "1.1.0"
+version = "1.2.0"
 license = { file = "LICENSE" }
 
 [project.urls]