diff --git a/_internal/STATUS.md b/_internal/STATUS.md deleted file mode 100644 index e8f6312..0000000 --- a/_internal/STATUS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Internal Status - -Last updated: 2026-02-03 - -## Active Tasks -- [x] Consolidate Gemini LLM nodes into one with model dropdown (2.5/3 Pro/Flash) -- [x] Gate unsupported options by model (reasoning_effort, response_format, google search) -- [x] Update node docs + README to reflect unified Gemini node - -## Notes -- 2026-01-31: Gemini LLM node now selects model via dropdown and logs selected model. -- 2026-02-02: Seedream 4.5 Edit updated to accept up to 14 input images. -- 2026-02-02: Added System Prompt Selector helper node with `prompts/images` + `prompts/videos` templates and docs. -- 2026-02-02: Added sample prompt templates and documented template format in `prompts/README.md`. -- 2026-02-02: Removed deprecated publish workflow and bumped package version to 0.1.4. -- 2026-02-03: Refactored shared image validation + createTask helper into `kie_api/validation.py` and `kie_api/jobs.py` (branch `dev/refactor-helpers`). -- 2026-02-03: Added refactor plan doc for phased helper consolidation in `_internal/docs/KIE_API_REFRACTOR_HELPERS.md`. -- 2026-02-03: Updated Suno music nodes to return two audio outputs and two cover images to match API responses. -- 2026-02-03: Updated README and Suno docs to note two-song/two-cover outputs. diff --git a/_internal/docs/KIE_API_REFRACTOR_HELPERS.md b/_internal/docs/KIE_API_REFRACTOR_HELPERS.md deleted file mode 100644 index e95508a..0000000 --- a/_internal/docs/KIE_API_REFRACTOR_HELPERS.md +++ /dev/null @@ -1,110 +0,0 @@ -# KIE API Helper Refactor Plan - -Purpose: keep model wrappers thin and move reusable behavior into shared helpers to reduce drift, simplify maintenance, and lower risk of subtle behavior differences across nodes. - -This document is intended to be a living reference so refactors can be done in phases without losing context or expanding scope unintentionally. - -## Guiding principles -- Preserve ComfyUI node behavior exactly (logging text, errors, defaults, and API payloads). -- Prefer small, incremental moves into existing helpers. -- Only change one dimension at a time (validation, createTask, uploads, polling, decoding). -- Keep wrapper modules focused on: input validation (by helper), payload construction, and orchestration. - -## Scope map (what belongs where) -- **Wrappers (model files)**: model-specific options, payload fields, and UI-level defaults. -- **Helpers (shared)**: input validation, API transport, polling, uploads, decoding, payload templates, constants. - -## Phase 1 (Minimal): validation + createTask extraction -Status: **completed in dev branch `dev/refactor-helpers`** - -### Changes delivered -1) Shared image tensor validation -- Added helper: `kie_api/validation.py:_validate_image_tensor_batch` -- Replaced local copies in: - - `kie_api/kling26_i2v.py` - - `kie_api/kling26motion_i2v.py` - - `kie_api/seedancev1pro_fast_i2v.py` - - `kie_api/seedream45_edit.py` - -2) Shared createTask helper -- Added helper: `kie_api/jobs.py:_create_task` -- Replaced local createTask copies in: - - `kie_api/kling26_i2v.py` - - `kie_api/kling26motion_i2v.py` - - `kie_api/kling25_i2v.py` - - `kie_api/seedancev1pro_fast_i2v.py` - - `kie_api/seedream45_edit.py` - - `kie_api/kling26_t2v.py` (import now from jobs) - -### Risk assessment -- **Likelihood of break**: Low -- **Why**: Logic moved verbatim into shared helpers; wrappers still call with identical inputs; payloads unchanged. -- **Risk surface**: Import paths, missing helpers, or overlooked custom behavior. - -### Maintenance cost reduction -- Validation: 4 copies -> 1 helper -- createTask: 5 copies -> 1 helper -- Expected savings: fewer drift bugs when API error handling changes. - -## Phase 2 (Moderate): model option validation + enums -Status: **not started** - -### Candidate targets -- Seedream 4.5 `_validate_options` (duplicate across `seedream45_edit` and `seedream45_t2i`) -- Common enum lists (durations, resolutions, aspect ratios) - -### Suggested helpers -- `kie_api/seedream45.py:validate_seedream45_options` -- `kie_api/constants.py` for enum lists - -### Risk assessment -- **Likelihood of break**: Low–Medium -- **Why**: If enums are moved incorrectly or reused across incompatible models, behavior could change. - -## Phase 3 (Full): upload + payload + result collection -Status: **not started** - -### Candidate targets -- Image upload prep + single-image handling (repeats across I2V models) -- Video upload / coercion patterns in motion-control models -- Standard post-processing: poll -> extract -> download -> decode - -### Suggested helpers -- `kie_api/upload.py:prepare_single_image_upload(...)` -- `kie_api/payloads.py:build_kling_i2v_payload(...)` -- `kie_api/runners.py:run_task_and_collect_video(...)` - -### Risk assessment -- **Likelihood of break**: Medium -- **Why**: Higher chance of subtle behavior changes (logging, ordering, error messages) -- **Mitigation**: keep wrapper-level logging strings unchanged; add tests or smoke checks with known inputs - -## Out of scope (explicitly) -- Any change to node UI defaults or parameter names -- Any change to API payload fields or mapping -- Any change to log messages (unless required for correctness) -- Any behavior change to timeouts, retry logic, or polling intervals - -## Verification checklist (ComfyUI nodes) -Smoke test goal: verify refactor didn’t change behavior, logging, or payloads. - -- Load workflows using refactored nodes (Kling 2.6 I2V, Kling 2.6 Motion I2V, Seedance V1 Pro Fast I2V, Seedream 4.5 Edit, Kling 2.5 I2V, Kling 2.6 T2V) -- Run each node once with a minimal valid input; confirm job completes and outputs are produced -- Confirm request creation succeeds and polling still completes (no new transient failures) -- Confirm log messages look identical (especially createTask + polling status lines) -- Trigger one invalid input per node (empty prompt or missing image) and confirm error text matches prior behavior -- For Kling 2.5 I2V, verify both `image` only and `image + tail_image` paths still work - -## Notes -- Keep this file updated after each refactor phase with: scope, changes, and risk notes. - -## Refactor backlog (itemized) -| Item | Status | Maintenance cost if left | Likelihood of break if refactored | Notes | -| --- | --- | --- | --- | --- | -| Shared image tensor validation | Done (Phase 1) | Medium | Low | Verbatim move into `validation.py` | -| Shared createTask helper | Done (Phase 1) | Medium | Low | Verbatim move into `jobs.py` | -| Seedream 4.5 option validation | Not started | Low–Medium | Low–Medium | Shared enums and validation for edit + t2i | -| Shared enum constants | Not started | Low | Low–Medium | Centralize option lists in `constants.py` | -| Shared single-image upload prep | Not started | Medium | Medium | Multiple I2V wrappers duplicate upload + logging | -| Shared payload builders | Not started | Medium | Medium | Risk of subtle field mismatch | -| Shared result runner (poll + download + decode) | Not started | Medium | Medium | Must preserve timing/logging semantics | diff --git a/_internal/docs/KIE_API_SEEDREAM_45_EDIT_SPEC.md b/_internal/docs/KIE_API_SEEDREAM_45_EDIT_SPEC.md deleted file mode 100644 index 55a85e3..0000000 --- a/_internal/docs/KIE_API_SEEDREAM_45_EDIT_SPEC.md +++ /dev/null @@ -1,194 +0,0 @@ -Seedream 4.5 is Bytedance’s refined image model for 4K generation, precise editing, and consistent multi-image output. - -POST -/api/v1/jobs/createTask -Create Task -Create a new generation task - -Request Parameters -The API accepts a JSON payload with the following structure: - -Request Body Structure -{ - "model": "string", - "callBackUrl": "string (optional)", - "input": { - // Input parameters based on form configuration - } -} -Root Level Parameters -model -Required -string -The model name to use for generation - -Example: - -"seedream/4.5-edit" -callBackUrl -Optional -string -Callback URL for task completion notifications. Optional parameter. If provided, the system will send POST requests to this URL when the task completes (success or failure). If not provided, no callback notifications will be sent. - -Example: - -"https://your-domain.com/api/callback" -Input Object Parameters -The input object contains the following parameters based on the form configuration: - -input.prompt -Required -string -A text description of the image you want to generate - -Max length: 3000 characters -Example: - -"Keep the model's pose and the flowing shape of the liquid dress unchanged. Change the clothing material from silver metal to completely transparent clear water (or glass). Through the liquid water, the model's skin details are visible. Lighting changes from reflection to refraction." -input.image_urls -Required -array(URL) -Upload an image file to use as input for the API - -File URL after upload, not file content; Accepted types: image/jpeg, image/png, image/webp; Max size: 10.0MB -Max count: 14 images -Example: - -["https://static.aiquickdraw.com/tools/example/1764851484363_ScV1s2aq.webp"] -input.aspect_ratio -Required -string -Width-height ratio of the image, determining its visual form. - -Available options: - -1:1 -- -1:1 -4:3 -- -4:3 -3:4 -- -3:4 -16:9 -- -16:9 -9:16 -- -9:16 -2:3 -- -2:3 -3:2 -- -3:2 -21:9 -- -21:9 -Example: - -"1:1" -input.quality -Required -string -Basic outputs 2K images, while High outputs 4K images. - -Available options: - -basic -- -Basic -high -- -High -Example: - -"basic" -Request Example - -cURL - -JavaScript - -Python -import requests -import json - -url = "https://api.kie.ai/api/v1/jobs/createTask" -headers = { - "Content-Type": "application/json", - "Authorization": "Bearer YOUR_API_KEY" -} - -payload = { - "model": "seedream/4.5-edit", - "callBackUrl": "https://your-domain.com/api/callback", - "input": { - "prompt": "Keep the model's pose and the flowing shape of the liquid dress unchanged. Change the clothing material from silver metal to completely transparent clear water (or glass). Through the liquid water, the model's skin details are visible. Lighting changes from reflection to refraction.", - "image_urls": [ - "https://static.aiquickdraw.com/tools/example/1764851484363_ScV1s2aq.webp" - ], - "aspect_ratio": "1:1", - "quality": "basic" - } -} - -response = requests.post(url, headers=headers, data=json.dumps(payload)) -result = response.json() -print(result) -Response Example -{ - "code": 200, - "message": "success", - "data": { - "taskId": "task_12345678" - } -} -Response Fields -code -Status code, 200 for success, others for failure -message -Response message, error description when failed -data.taskId -Task ID for querying task status -Callback Notifications -When you provide the callBackUrl parameter when creating a task, the system will send POST requests to the specified URL upon task completion (success or failure). - -Success Callback Example -{ - "code": 200, - "data": { - "completeTime": 1755599644000, - "consumeCredits": 100, - "costTime": 8, - "createTime": 1755599634000, - "model": "seedream/4.5-edit", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"seedream/4.5-edit\",\"input\":{\"prompt\":\"Keep the model's pose and the flowing shape of the liquid dress unchanged. Change the clothing material from silver metal to completely transparent clear water (or glass). Through the liquid water, the model's skin details are visible. Lighting changes from reflection to refraction.\",\"image_urls\":[\"https://static.aiquickdraw.com/tools/example/1764851484363_ScV1s2aq.webp\"],\"aspect_ratio\":\"1:1\",\"quality\":\"basic\"}}", - "remainedCredits": 2510330, - "resultJson": "{\"resultUrls\":[\"https://example.com/generated-image.jpg\"]}", - "state": "success", - "taskId": "e989621f54392584b05867f87b160672", - "updateTime": 1755599644000 - }, - "msg": "Playground task completed successfully." -} -Failure Callback Example -{ - "code": 501, - "data": { - "completeTime": 1755597081000, - "consumeCredits": 0, - "costTime": 0, - "createTime": 1755596341000, - "failCode": "500", - "failMsg": "Internal server error", - "model": "seedream/4.5-edit", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"seedream/4.5-edit\",\"input\":{\"prompt\":\"Keep the model's pose and the flowing shape of the liquid dress unchanged. Change the clothing material from silver metal to completely transparent clear water (or glass). Through the liquid water, the model's skin details are visible. Lighting changes from reflection to refraction.\",\"image_urls\":[\"https://static.aiquickdraw.com/tools/example/1764851484363_ScV1s2aq.webp\"],\"aspect_ratio\":\"1:1\",\"quality\":\"basic\"}}", - "remainedCredits": 2510430, - "state": "fail", - "taskId": "bd3a37c523149e4adf45a3ddb5faf1a8", - "updateTime": 1755597097000 - }, - "msg": "Playground task failed." -} diff --git a/_internal/docs/KIE_Seedream45_Edit_MultiImage_TASKS.md b/_internal/docs/KIE_Seedream45_Edit_MultiImage_TASKS.md deleted file mode 100644 index 8935467..0000000 --- a/_internal/docs/KIE_Seedream45_Edit_MultiImage_TASKS.md +++ /dev/null @@ -1,39 +0,0 @@ -# KIE Seedream 4.5 Edit — Multi-Image Support Task List - -Goal: allow the Seedream45_Edit node/helper to accept and upload up to 14 input images, then pass all uploaded URLs to `input.image_urls`. - -## Context (current behavior) -- Helper: `kie_api/seedream45_edit.py` uploads only the first image in the batch. -- Node: `nodes.py` HELP text explicitly says "first image used". -- Spec: `_internal/docs/KIE_API_SEEDREAM_45_EDIT_SPEC.md` lists `input.image_urls` but does not specify a max count. -- Multi-image patterns to mirror: `kie_api/flux2_i2i.py` and `kie_api/nanobanana.py`. - -## Open question (must confirm before coding) -- Confirm the server-side max image count for Seedream 4.5 Edit (user believes 14). If confirmed, update the spec doc to include the max. - -## Phase 1 — Spec/requirements alignment -- [ ] Confirm max image count with KIE docs or internal source. -- [ ] Update `_internal/docs/KIE_API_SEEDREAM_45_EDIT_SPEC.md` to include max count (1..14) once confirmed. - -## Phase 2 — Helper changes (seedream45_edit.py) -- [ ] Add `MAX_IMAGE_COUNT = 14` (or confirmed value). -- [ ] Update `_validate_image_input()` to keep shape checks; do not fail on batch size > 1. -- [ ] Upload up to `MAX_IMAGE_COUNT` images using the pattern in `flux2_i2i.py`: - - log when more than max provided - - iterate through `min(total_images, MAX_IMAGE_COUNT)` - - build `image_urls` list from uploads -- [ ] Update payload to use `image_urls` list (instead of a single URL). -- [ ] Log how many URLs are sent to `createTask` for traceability. - -## Phase 3 — Node wrapper and docs -- [ ] Update `nodes.py` HELP text for `KIE_Seedream45_Edit` to reflect up to 14 images and that all provided images are uploaded (up to the cap). -- [ ] Update `web/docs/KIE_Seedream45_Edit.md` with correct inputs/outputs and helper behavior (upload cap, truncation behavior). - -## Phase 4 — Validation -- [ ] Run `python3 -m py_compile nodes.py kie_api/seedream45_edit.py`. -- [ ] Minimal manual test: pass a batch of 2+ images and confirm multiple uploads + task creation includes multiple URLs. - -## Acceptance criteria -- Helper uploads up to 14 images and sends all URLs in `input.image_urls`. -- If more than 14 images are supplied, the helper logs a truncation message and uses only the first 14. -- Node HELP and web docs clearly describe the multi-image behavior.