gateway-ComfyUI-Kie-API/docs/node_from_spec.md

# Building ComfyUI Nodes From KIE API Specs

This is the ground-truth process for turning a pinned KIE API spec into:
- a helper (model runner) in `kie_api/`
- a ComfyUI node wrapper in `nodes.py`
- a matching user-facing doc in `web/docs/`

## Source Material (What We Actually Use)
Primary inputs:
- `_internal/docs/KIE_API_*_SPEC.md` and other spec files in `_internal/docs/`
- `_internal/docs/COMFYUI_NODE_CHEATSHEET.md`
- `_internal/docs/REPO_RULES.md`
- Existing node + helper implementations (`nodes.py`, `kie_api/*.py`)

Note: There is no `codecs/` folder in this repo. If one appears later, add it to this list.

## Non-Negotiable Rules (Do Not Hallucinate)
- Never invent fields or options that are not in a spec.
- If a spec is incomplete or ambiguous, stop and request clarification.
- The helper owns API logic. The node is a thin wrapper only.
- ComfyUI image tensors are **BHWC float32** in **[0..1]**.
- Video outputs must remain compatible with ComfyUI `SaveVideo`.

## Step 1: Parse the Spec (Pin the Facts)
From the spec file, extract these fields exactly:
- **Model name** (string used in the payload `model`)
- **Input fields** (required vs optional)
- **Allowed options** (enumerations for combos)
- **Input constraints** (max lengths, valid ranges, max count)
- **Response shape** (task id, result URLs, failure fields)

If you cannot find a field in the spec, do not add it to the node.

## Step 2: Decide Helper vs Node Responsibilities
Helpers (model runners) MUST do:
- prompt validation (length/range)
- image/video upload (if input URLs are required)
- task creation and polling
- result parsing and download/decoding
- logging + credit logging

Nodes MUST do:
- define ComfyUI inputs/outputs
- call exactly one helper function
- return the helper output without modification

## Step 3: Map Spec Inputs to ComfyUI Inputs
Use these mapping rules (always prefer existing patterns):

Spec field type -> ComfyUI type:
- string prompt -> `STRING` (multiline)
- boolean -> `BOOLEAN`
- number -> `FLOAT` (with min/max/step if in spec)
- integer -> `INT` (with min/max if in spec)
- enum -> `COMBO` with the exact options list
- image URL(s) -> `IMAGE` (ComfyUI tensors), then upload in helper
- video URL(s) -> `VIDEO`, then upload in helper

Required vs optional:
- Spec **required** -> `required` section of `INPUT_TYPES`
- Spec **optional** -> `optional` section of `INPUT_TYPES`

Image and video rules:
- If spec allows 1..N images, accept a batch `IMAGE` input and enforce max N.
- If spec allows optional image list, permit `images=None` and skip upload.
- Video inputs are passed through the existing video helpers.

## Step 4: Implement the Helper (Model Runner)
Location: `kie_api/<model>.py`

Required responsibilities:
1) Validate inputs
2) Upload any images/videos (convert tensors to bytes)
3) Create task (`createTask`)
4) Poll until completion (`recordInfo`)
5) Parse result URLs
6) Download output and convert to ComfyUI types

Existing helpers to reuse:
- `kie_api/auth.py` (`_load_api_key`)
- `kie_api/jobs.py` (`_poll_task_until_complete`)
- `kie_api/upload.py` (image/video upload + conversions)
- `kie_api/images.py` (image download + tensor decode)
- `kie_api/video.py` (video download + SaveVideo-compatible output)
- `kie_api/results.py` (result URL extraction)
- `kie_api/validation.py` (prompt validation)
- `kie_api/log.py` (logging)
- `kie_api/credits.py` (credits logging)

Helper output contract:
- Image models return `torch.Tensor` with shape [B, H, W, C], float32, 0..1
- Video models return a SaveVideo-compatible object (match existing video nodes)

## Step 5: Implement the Node Wrapper
Location: `nodes.py`

Requirements:
- Keep node `generate()` minimal: just call helper and return results.
- `INPUT_TYPES`, `RETURN_TYPES`, `RETURN_NAMES`, `FUNCTION`, `CATEGORY` are required.
- `HELP` must match the actual node inputs and defaults.
- Expose enums as `COMBO` options exactly as listed in the spec.
- If spec includes optional inputs, include them under `optional`.

## Step 6: Register the Node
Ensure:
- The node class is imported in `nodes.py`
- It appears in `NODE_CLASS_MAPPINGS`
- It has a name in `NODE_DISPLAY_NAME_MAPPINGS`

## Step 7: Document the Node (web/docs)
Create or update `web/docs/<NodeName>.md`:
- Match the exact ComfyUI inputs and outputs
- Include defaults and enums
- Add a brief “Helper behavior” summary:
  - validation rules
  - polling defaults
  - retry behavior (if any)

## Helper/Node Consistency Checklist
Before declaring done:
- Node HELP matches INPUT_TYPES (no hidden inputs).
- Helper validates all required fields and enum options.
- Spec-required inputs are not optional in the node.
- All options in the spec are represented as COMBOs.
- Output type is correct (IMAGE or VIDEO).

## Spec-to-Node Quick Example (Image-to-Image)
Spec fields:
- model: "flux-2/pro-image-to-image"
- input.input_urls (required, 1..8)
- input.prompt (required, max 5000)
- input.aspect_ratio (required enum)
- input.resolution (required enum)

ComfyUI node inputs:
- `images: IMAGE` (required)
- `prompt: STRING` (required)
- `aspect_ratio: COMBO` (required)
- `resolution: COMBO` (required)
- `log: BOOLEAN` (optional, local-only)

Helper responsibilities:
- Validate prompt length
- Validate `images` tensor shape and count (max 8)
- Upload images to URLs
- Build payload with `input_urls`
- Create task + poll
- Download result URL and decode to tensor

## When Specs Are Incomplete
If a spec:
- omits an option list
- lacks a max length/range
- conflicts with existing helper behavior

Then:
1) Do not guess defaults.
2) Add a TODO in the spec doc.
3) Ask for clarification or source doc before coding.