nodes/gateway-ComfyUI-Kie-API
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: move internal docs under _internal

Browse Source
This commit is contained in:
Dreaming Computers
2026-01-30 12:16:53 +07:00
parent 0eb1726b41
commit 4a8a906377
6 changed files with 1 additions and 355 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/flux_i2i_plan.md
-47
View File
@@ -1,47 +0,0 @@
# Flux 2 I2I Nodes — Plan
## Spec scan (source of truth)
- `_internal/docs/KIE_API_FLUX-2-PRO-I2I_SPEC.md`
- `_internal/docs/KIE_AI-FLUX-2-FLEX-I2I_SPEC.MD`
## Field comparison (Pro vs Flex)
Same fields in both specs:
- `model` (string; only value differs)
- `input.input_urls` (required, array URL, 1–8 images)
- `input.prompt` (required, 3–5000 chars)
- `input.aspect_ratio` (required enum)
- `input.resolution` (required enum)
- `callBackUrl` (optional)
Enumerations (identical):
- `aspect_ratio`: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, auto
- `resolution`: 1K, 2K
Conclusion: inputs/outputs are identical; only `model` differs.
## Node architecture decision
We can implement a **single node** with a `model` dropdown:
- `flux-2/pro-image-to-image`
- `flux-2/flex-image-to-image`
Conditions satisfied:
- All other parameters are the same in both specs.
- Output type is the same (IMAGE).
## Helper vs node split
Helper:
- `kie_api/flux2_i2i.py` (new)
- Accept `model` as a required argument.
- Handle upload, createTask, poll, download, decode.
Node:
- `KIE_Flux2_I2I` in `nodes.py`
- `model` dropdown + inputs from spec
- Calls `run_flux2_i2i(...)`
Docs:
- `web/docs/KIE_Flux2_I2I.md` (new)
## Open questions (confirm before code)
1) Should we allow 1–8 images (batch) or force 1 image?
2) Do you want `model` in node name or just in a dropdown?
docs/flux_i2i_status.md
-9
View File
@@ -1,9 +0,0 @@
# Flux 2 I2I — Status
Last updated: 2026-01-30
- [x] Helper added (`kie_api/flux2_i2i.py`)
- [x] Node wrapper added (`nodes.py`)
- [x] Node registered in mappings (`nodes.py`)
- [x] Node docs added (`web/docs/KIE_Flux2_I2I.md`)
- [x] Compile check (`python3 -m py_compile nodes.py kie_api/flux2_i2i.py`)
docs/flux_i2i_tasks.md
-32
View File
@@ -1,32 +0,0 @@
# Flux 2 I2I — Task List
## Phase 0: Agree on scope
- Confirm single node with model dropdown is acceptable.
- Confirm allowed image count (1 vs 1–8).
## Phase 1: Spec-to-helper
- Add `kie_api/flux2_i2i.py`
- constants: MODEL_OPTIONS, ASPECT_RATIO_OPTIONS, RESOLUTION_OPTIONS
- validate prompt length (3–5000)
- validate images tensor shape and count
- upload images (1..8)
- createTask + poll + extract result URLs
- download + decode to tensor
## Phase 2: Node wrapper
- Add class `KIE_Flux2_I2I` to `nodes.py`
- `INPUT_TYPES` reflects spec (plus `model` dropdown, `log`)
- Call `run_flux2_i2i(...)`
- Add HELP text
## Phase 3: Register node
- Import new helper in `nodes.py`
- Add to `NODE_CLASS_MAPPINGS`
- Add to `NODE_DISPLAY_NAME_MAPPINGS`
## Phase 4: Docs
- Add `web/docs/KIE_Flux2_I2I.md`
- Include inputs/outputs + enums + defaults
## Phase 5: Sanity checks
- `python3 -m py_compile nodes.py kie_api/flux2_i2i.py`
docs/implementation_plan.md
-107
View File
@@ -1,107 +0,0 @@
# ComfyUI Node + Helper Separation Plan
## Goals
- Keep model-specific API logic in helpers (`kie_api/*`).
- Keep ComfyUI node definitions in `nodes.py` (or a future `nodes/` package).
- Ensure every node relies on helpers instead of re-implementing API calls.
- Document best practices and track follow-up fixes.
## Current Nodes (as of Jan 30, 2026)
Image:
- Nano Banana Pro (image)
- Seedream 4.5 (text-to-image)
- Seedream 4.5 (edit)
Video:
- Kling 2.5 I2V Pro
- Kling 2.6 I2V
- Kling 2.6 T2V
- Kling 2.6 Motion I2V
- Seedance V1 Pro Fast I2V
- Seedance 1.5 Pro I2V/T2V
Helpers:
- auth, credits, http, log, jobs, results
- upload, images, video, validation, grid, prompt_lists
- model-specific helpers: nanobanana, seedream45_t2i, seedream45_edit, seedance*, kling*
## Best Practices Implementation (Current Standard)
1) **Nodes are thin wrappers.**
- Node `generate()` methods delegate to helper functions (`run_*`).
- Node I/O uses ComfyUI types (`IMAGE`, `VIDEO`, `STRING`, `INT`, `BOOLEAN`).
2) **Helpers encapsulate the full job lifecycle.**
- Validation → upload → create task → poll → download/decode → credits logging.
- Shared behavior is already centralized in `jobs.py`, `upload.py`, `images.py`, `video.py`, `validation.py`.
3) **Consistent error handling.**
- `TransientKieError` signals retryable failures (HTTP 429 or 5xx, transient task failure states).
- Non-retry errors raise `RuntimeError` with clear messages.
4) **Logging is centralized and predictable.**
- `_log()` is used for all progress messages.
- Nodes expose a `log` flag and pass it through.
5) **Enum inputs are pinned.**
- ComfyUI node options use COMBOs that map to pinned server enums (`duration`, `aspect_ratio`, etc.).
6) **Helpers own logic; nodes own UI.**
- No API calls, uploads, or polling logic inside nodes.
- Nodes should only translate ComfyUI inputs → helper inputs and return helper outputs.
7) **Docs reflect actual behavior.**
- Node docs in `web/docs/` mirror the helper inputs/outputs and current defaults.
- HELP text and `INPUT_TYPES` must match.
## Things To Review / Fix (Cleanup Targets)
1) **Duplicate `createTask` logic across helpers.**
- `nanobanana.py`, `kling25_i2v.py`, `kling26_i2v.py`, `kling26_t2v.py`, `kling26motion_i2v.py`,
`seedance*`, `seedream*` all implement request + error handling for `createTask`.
- Candidate: move to `jobs.py` or a `requests.py` helper for shared API calls.
2) **Duplicate image upload + validation patterns.**
- Each model re-validates image tensor shapes, slices batches, and uploads via `_upload_image`.
- Candidate: a shared helper (e.g. `_upload_first_image`, `_upload_images_limit`).
3) **Node inputs do not expose all documented parameters.**
- Several node HELP blocks mention `poll_interval_s`, `timeout_s`, and retry settings,
but these are not exposed in `INPUT_TYPES`.
- Decide whether to:
- expose them via `INPUT_TYPES`, or
- remove from HELP to avoid confusion.
4) **Model docs vs helper docs drift risk.**
- `web/docs/` contains node pages; helper behavior lives in `kie_api/*`.
- Add a short helper summary section per model doc or generate them from helpers.
5) **Category naming consistency.**
- Some helpers appear as nodes in `kie/helpers` (grid, prompt parsing), while others are `kie/api`.
- Clarify if helper nodes should live under a dedicated category and be separated from API nodes in UI.
## Cleanup Task List (Initial)
### 2) Normalize helper APIs (createTask + upload + validation)
- Extract a shared `create_task()` helper (or move into `jobs.py`) to remove per-model duplication.
- Add shared helpers for common upload patterns:
- upload first image
- upload optional tail image
- upload list of images with a max limit
- Consolidate image shape validation helpers (single image vs batch) into `validation.py`.
### 3) Align node HELP with `INPUT_TYPES`
- Audit each node in `nodes.py` for:
- missing inputs referenced in HELP
- defaults or ranges that differ between HELP and `INPUT_TYPES`
- Either expose these inputs or remove them from HELP to avoid mismatch.
### 4) Keep docs in sync with helpers
- For each model in `web/docs/`, add a short “Helper behavior” section:
- validation rules
- retry behavior
- polling defaults
- output format
- Add a checklist to update docs when helper defaults change.
## Next Steps (if approved)
1) Create a dedicated “Best Practices + Implementation Checklist” doc for adding new models.
2) Start Cleanup Task List item 3 (HELP vs INPUT_TYPES) as the first low-hanging task.
3) After cleanup item 3, draft a new node using the standard pattern.
docs/node_from_spec.md
-159
View File
@@ -1,159 +0,0 @@
# 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.
kie_api/seedream45_edit.py
+1 -1
View File
@@ -1,7 +1,7 @@
"""Seedream 4.5 image edit helper.
Implements the Seedream 4.5 edit workflow as documented in
`docs/KIE_API_SEEDREAM_45_EDIT_SPEC.md`.
`_internal/docs/KIE_API_SEEDREAM_45_EDIT_SPEC.md`.
This module:
- validates inputs