comfyui-payload-sanitization-protocol

name	comfyui-payload-sanitization-protocol
description	Protocol for cleaning LLM-generated or metadata-enriched JSON payloads to ensure compatibility with the ComfyUI API.

ComfyUI API Payload Sanitization Protocol

This skill provides a standardized procedure for preparing JSON payloads for the ComfyUI API when they have been generated by LLMs or enriched with metadata.

Overview

LLMs often include descriptive metadata (e.g., _meta, description, anchor_id) within the JSON structure to help human agents track tasks. However, the ComfyUI /prompt endpoint is strictly schema-validated and will reject any payload containing keys not defined in the original workflow.

Trigger

Use this protocol when submitting payloads generated via script or LLM that result in a 400 Bad Request error from the ComfyUI server, specifically citing unexpected keys.

Workflow

1. Identify Metadata Keys: Inspect the failing payload to find non-standard keys (commonly _meta, anchor_id, or custom descriptive fields).
2. Sanitization Scripting: Instead of manual editing, use a Python script to recursively traverse the JSON object and remove all keys that do not exist in the original base workflow template.
3. Recursive Implementation:
   • Load the clean base workflow (the one exported directly from ComfyUI).
   • Load the enriched payload (containing the prompt text/parameters).
   • Deep-merge the enriched values into the clean structure, ensuring no extra keys are introduced during the merge.

Example Python Implementation

import json

def sanitize_payload(base_workflow, enriched_payload):
    """
    Merges enriched data into a clean base workflow to ensure 
    no non-standard metadata keys remain.
    """
    # Create a deep copy of the clean structure
    clean_payload = json.loads(json.dumps(base_workflow))
    
    # Extract only the valid node updates from the enriched payload
    for node_id, node_data in enriched_payload.items():
        if node_id in clean_payload:
            # Remove any metadata at the top level of the enriched node
            # before updating the clean structure
            if isinstance(node_data, dict):
                node_data.pop('_meta', None)
            clean_payload[node_id].update(node_data)
            
    return clean_payload

# Usage
with open('base_workflow.json', 'r') as f:
    base = json.load(f)
with open('enriched_batch.json', 'r') as f:
    enriched = json.load(f)

sanitized = sanitize_payload(base, enriched)

Pitfalls & Troubleshooting

• Recursive Metadata: Some workflows might have metadata nested deep within node inputs. A simple pop() on the top level may not be enough; a recursive key removal function is safer for complex nodes.
• Data Type Mismatches: Ensure that while stripping keys, you do not accidentally change the data type of required fields (e.g., converting an integer to a string).