diff --git a/.gitignore b/.gitignore index 4a0d74d..3e5877e 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ config/kie_key.txt __pycache__/ *.pyc .DS_Store +_internal/ diff --git a/README.md b/README.md index c630c27..7a3d15a 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # ComfyUI KIE API Integration -This repository sets up the groundwork for integrating the KIE Nano Banana Pro API into ComfyUI custom nodes. +ComfyUI custom nodes for the KIE API (image and video generation). ## Installation -- Place this repository inside your `ComfyUI/custom_nodes` directory (clone or copy). +- Clone or copy this repository into `ComfyUI/custom_nodes/ComfyUI-Kie-API`. - Restart ComfyUI so it discovers the node package. ## API Key Setup @@ -11,16 +11,23 @@ This repository sets up the groundwork for integrating the KIE Nano Banana Pro A - Paste your KIE API key into `config/kie_key.txt` (this file is gitignored). - Keep the key file alongside the repo so future nodes can read it. -## Future Nodes -- Placeholder for upcoming node descriptions and usage once implementation lands +## Nodes +- KIE Get Remaining Credits +- KIE Nano Banana Pro (Image) +- KIE Seedream 4.5 Text-To-Image +- KIE Seedream 4.5 Edit +- KIE Seedance V1 Pro Fast (I2V) +- KIE Seedance 1.5 Pro (I2V/T2V) +- KIE Kling 2.6 (I2V/T2V) +- KIE Kling 2.6 (T2V) +- KIE Kling 2.6 Motion-Control (I2V) +- KIE Grid Slice +- KIE Parse Prompt Grid JSON (1..9) +## Usage +- Drop a KIE node into your ComfyUI workflow and connect inputs. +- For video outputs, connect the VIDEO output to the SaveVideo node. +- Public node documentation lives in `web/docs`. -## Working Notes - -- Custom ComfyUI nodes for KIE / Nano Banana Pro. -- Repo is structured as a Python package (relative imports required). -- All API endpoints and enums are pinned in docs/ — do not guess values. -- Image uploads capped at 8 references per request. -- Credit checks are advisory (fail only when credits <= 0). -- Logging is console-based (toggle via node input). -. +## Documentation +- See `web/docs` for per-node details and parameter lists. diff --git a/docs/COMFYUI_NODE_CHEATSHEET.md b/docs/COMFYUI_NODE_CHEATSHEET.md deleted file mode 100644 index 9314bfa..0000000 --- a/docs/COMFYUI_NODE_CHEATSHEET.md +++ /dev/null @@ -1,5 +0,0 @@ -# ComfyUI Node Cheatsheet -- IMAGE tensor: torch.Tensor [B,H,W,C], RGB, float [0..1] -- Nodes must define INPUT_TYPES, RETURN_TYPES, FUNCTION, CATEGORY -- Must register NODE_CLASS_MAPPINGS and NODE_DISPLAY_NAME_MAPPINGS --BOOLEAN type is "BOOLEAN" (not "BOOL") diff --git a/docs/COMFY_ORG_CANONICAL_REFERENCES.md b/docs/COMFY_ORG_CANONICAL_REFERENCES.md deleted file mode 100644 index 8c2aa76..0000000 --- a/docs/COMFY_ORG_CANONICAL_REFERENCES.md +++ /dev/null @@ -1,9 +0,0 @@ -Very clearly follow the links on this page for proper comfy ui node creation - -https://docs.comfy.org/custom-nodes/walkthrough -https://docs.comfy.org/custom-nodes/backend/images_and_masks -https://docs.comfy.org/custom-nodes/backend/datatypes -https://docs.comfy.org/custom-nodes/backend/tensors - -Master list of all, if you can scan the page for what you need -https://docs.comfy.org/custom-nodes/overview \ No newline at end of file diff --git a/docs/KIE_AI_KLING26MOTION_I2V_SPEC.md b/docs/KIE_AI_KLING26MOTION_I2V_SPEC.md deleted file mode 100644 index 28b57bd..0000000 --- a/docs/KIE_AI_KLING26MOTION_I2V_SPEC.md +++ /dev/null @@ -1,196 +0,0 @@ -Kling 26 Motion I2V - -inputs -- Ref Image (Single Image) -- Motion video (Single mp4) - -These files are uploaded to Kie AI similar to how we upload the images in kling26_i2v.py how its done in their. - -KIE API Documents: - -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: - -"kling-2.6/motion-control" -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 desired output. Maximum length is 2500 characters. - -Max length: 2500 characters -Example: - -"The cartoon character is dancing." -input.input_urls -Required -array(URL) -An array containing a single image URL. The photo must clearly show the subject's head, shoulders, and torso. - -Please provide the URL of the uploaded file; Accepted types: image/jpeg, image/png, image/webp; Max size: 10.0MB -Example: - -["https://static.aiquickdraw.com/tools/example/1767694885407_pObJoMcy.png"] -input.video_urls -Required -array(URL) -An array containing a single video URL. The duration must be between 3 to 30 seconds, and the video must clearly show the subject's head, shoulders, and torso.The minimum width and height for videos must be 720 pixels, and only jpeg/jpg/png image formats are supported. - -Please provide the URL of the uploaded file; Accepted types: video/mp4, video/quicktime, video/x-matroska; Max size: 100.0MB -Example: - -["https://static.aiquickdraw.com/tools/example/1767525918769_QyvTNib2.mp4"] -input.character_orientation -Required -string -Generate the orientation of the characters in the video. 'image': same orientation as the person in the picture (max 10s video). 'video': consistent with the orientation of the characters in the video (max 30s video). - -Available options: - -image -- -Image -video -- -Video -Example: - -"video" -input.mode -Required -string -Output resolution mode. Use 'std' for 720p or 'pro' for 1080p. - -Available options: - -720p -- -720p -1080p -- -1080p -Example: - -"720p" -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": "kling-2.6/motion-control", - "callBackUrl": "https://your-domain.com/api/callback", - "input": { - "prompt": "The cartoon character is dancing.", - "input_urls": [ - "https://static.aiquickdraw.com/tools/example/1767694885407_pObJoMcy.png" - ], - "video_urls": [ - "https://static.aiquickdraw.com/tools/example/1767525918769_QyvTNib2.mp4" - ], - "character_orientation": "video", - "mode": "720p" - } -} - -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, - "costTime": 8, - "createTime": 1755599634000, - "model": "kling-2.6/motion-control", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"kling-2.6/motion-control\",\"input\":{\"prompt\":\"The cartoon character is dancing.\",\"input_urls\":[\"https://static.aiquickdraw.com/tools/example/1767694885407_pObJoMcy.png\"],\"video_urls\":[\"https://static.aiquickdraw.com/tools/example/1767525918769_QyvTNib2.mp4\"],\"character_orientation\":\"video\",\"mode\":\"720p\"}}", - "resultJson": "{\"resultUrls\":[\"https://example.com/generated-image.jpg\"]}", - "state": "success", - "taskId": "e989621f54392584b05867f87b160672", - "failCode": null, - "failMsg": null, - }, - "msg": "Playground task completed successfully." -} -Failure Callback Example -{ - "code": 501, - "data": { - "completeTime": 1755597081000, - "costTime": 0, - "createTime": 1755596341000, - "failCode": "500", - "failMsg": "Internal server error", - "model": "kling-2.6/motion-control", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"kling-2.6/motion-control\",\"input\":{\"prompt\":\"The cartoon character is dancing.\",\"input_urls\":[\"https://static.aiquickdraw.com/tools/example/1767694885407_pObJoMcy.png\"],\"video_urls\":[\"https://static.aiquickdraw.com/tools/example/1767525918769_QyvTNib2.mp4\"],\"character_orientation\":\"video\",\"mode\":\"720p\"}}", - "state": "fail", - "taskId": "bd3a37c523149e4adf45a3ddb5faf1a8", - "resultJson": null, - }, - "msg": "Playground task failed." -} -Important Notes -The callback content structure is identical to the Query Task API response -The param field contains the complete Create Task request parameters, not just the input section -If callBackUrl is not provided, no callback notifications will be sent \ No newline at end of file diff --git a/docs/KIE_AI_KLING26_T2V_SPEC.md b/docs/KIE_AI_KLING26_T2V_SPEC.md deleted file mode 100644 index 2b8fe8c..0000000 --- a/docs/KIE_AI_KLING26_T2V_SPEC.md +++ /dev/null @@ -1,177 +0,0 @@ -API documentation for kling 2.6 text to video (t2v) kie_api/kling26_t2v.py - -this are the exact methods and calls to do for this, do not make up any other data. Make sure our comfy ui node has the options listed if their are selections that can be made, like aspsect ratio, sound and duration.. - -below are the docs for this know for kling 2.6, - -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: - -"kling-2.6/text-to-video" -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 -The text prompt used to generate the video - -Max length: 2500 characters -Example: - -"Visual: In a fashion live-streaming room, clothes hang on a rack, and a full-length mirror reflects the host's figure. Dialog: [African-American female host] turns to show off the sweatshirt fit. [African-American female host, cheerful voice] says: \"360-degree flawless cut, slimming and flattering.\" Immediately, [African-American female host] moves closer to the camera. [African-American female host, lively voice] says: \"Double-sided brushed fleece, 30 dollars off with purchase now.\"" -input.sound -Required -boolean -This parameter is used to specify whether the generated video contains sound - -Boolean value (true/false) -Example: - -false -input.aspect_ratio -Required -string -This parameter defines the aspect ratio of the video. - -Available options: - -1:1 -- -1:1 -16:9 -- -16:9 -9:16 -- -9:16 -Example: - -"1:1" -input.duration -Required -string -Duration of the video in seconds - -Available options: - -5 -- -5 -10 -- -10 -Example: - -"5" -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": "kling-2.6/text-to-video", - "callBackUrl": "https://your-domain.com/api/callback", - "input": { - "prompt": "Visual: In a fashion live-streaming room, clothes hang on a rack, and a full-length mirror reflects the host's figure. Dialog: [African-American female host] turns to show off the sweatshirt fit. [African-American female host, cheerful voice] says: \"360-degree flawless cut, slimming and flattering.\" Immediately, [African-American female host] moves closer to the camera. [African-American female host, lively voice] says: \"Double-sided brushed fleece, 30 dollars off with purchase now.\"", - "sound": false, - "aspect_ratio": "1:1", - "duration": "5" - } -} - -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, - "costTime": 8, - "createTime": 1755599634000, - "model": "kling-2.6/text-to-video", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"kling-2.6/text-to-video\",\"input\":{\"prompt\":\"Visual: In a fashion live-streaming room, clothes hang on a rack, and a full-length mirror reflects the host's figure. Dialog: [African-American female host] turns to show off the sweatshirt fit. [African-American female host, cheerful voice] says: \\"360-degree flawless cut, slimming and flattering.\\" Immediately, [African-American female host] moves closer to the camera. [African-American female host, lively voice] says: \\"Double-sided brushed fleece, 30 dollars off with purchase now.\\"\",\"sound\":false,\"aspect_ratio\":\"1:1\",\"duration\":\"5\"}}", - "resultJson": "{\"resultUrls\":[\"https://example.com/generated-image.jpg\"]}", - "state": "success", - "taskId": "e989621f54392584b05867f87b160672", - "failCode": null, - "failMsg": null, - }, - "msg": "Playground task completed successfully." -} -Failure Callback Example -{ - "code": 501, - "data": { - "completeTime": 1755597081000, - "costTime": 0, - "createTime": 1755596341000, - "failCode": "500", - "failMsg": "Internal server error", - "model": "kling-2.6/text-to-video", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"kling-2.6/text-to-video\",\"input\":{\"prompt\":\"Visual: In a fashion live-streaming room, clothes hang on a rack, and a full-length mirror reflects the host's figure. Dialog: [African-American female host] turns to show off the sweatshirt fit. [African-American female host, cheerful voice] says: \\"360-degree flawless cut, slimming and flattering.\\" Immediately, [African-American female host] moves closer to the camera. [African-American female host, lively voice] says: \\"Double-sided brushed fleece, 30 dollars off with purchase now.\\"\",\"sound\":false,\"aspect_ratio\":\"1:1\",\"duration\":\"5\"}}", - "state": "fail", - "taskId": "bd3a37c523149e4adf45a3ddb5faf1a8", - "resultJson": null, - }, - "msg": "Playground task failed." -} \ No newline at end of file diff --git a/docs/KIE_AI_SEEDANCE15PRO_I2V.md b/docs/KIE_AI_SEEDANCE15PRO_I2V.md deleted file mode 100644 index 2166f81..0000000 --- a/docs/KIE_AI_SEEDANCE15PRO_I2V.md +++ /dev/null @@ -1,216 +0,0 @@ -Seedance 1.5 Pro I2V api call for Kie. - -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: - -"bytedance/seedance-1.5-pro" -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 -Enter video description (3-2500 characters)... - -Max length: 2500 characters -Example: - -"In a Chinese-English communication scenario, a 70-year-old old man said kindly to the child: Good boy, study hard where you are in China ! The child happily replied in Chinese: Grandpa, I'll come to accompany you when I finish my studies in China . Then the old man stroked the child's head " -input.input_urls -Optional -array(URL) -Upload 0-2 images. Leave empty to generate video from text only. - -Please provide the URL of the uploaded file; Accepted types: image/jpeg, image/png, image/webp; Max size: 10.0MB -Example: - -["https://static.aiquickdraw.com/tools/example/1766556007862_Y451Ehaf.png"] -input.aspect_ratio -Required -string -Select the frame dimensions. Default is 1:1. - -Available options: - -1:1 -- -1:1 -21:9 -- -21:9 -4:3 -- -4:3 -3:4 -- -3:4 -16:9 -- -16:9 -9:16 -- -9:16 -Example: - -"1:1" -input.resolution -Optional -string -Standard (480p) / High (720p) - -Available options: - -480p -- -480p -720p -- -720p -Example: - -"720p" -input.duration -Required -string -4s / 8s / 12s - -Available options: - -4 -- -4s -8 -- -8s -12 -- -12s -Example: - -"8" -input.fixed_lens -Optional -boolean -Enable to keep the camera view static and stable. Disable for dynamic camera movement. - -Boolean value (true/false) -input.generate_audio -Optional -boolean -Enable to create sound effects for the video (Additional cost applies). - -Boolean value (true/false) -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": "bytedance/seedance-1.5-pro", - "callBackUrl": "https://your-domain.com/api/callback", - "input": { - "prompt": "In a Chinese-English communication scenario, a 70-year-old old man said kindly to the child: Good boy, study hard where you are in China ! The child happily replied in Chinese: Grandpa, I'll come to accompany you when I finish my studies in China . Then the old man stroked the child's head ", - "input_urls": [ - "https://static.aiquickdraw.com/tools/example/1766556007862_Y451Ehaf.png" - ], - "aspect_ratio": "1:1", - "resolution": "720p", - "duration": "8" - } -} - -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, - "costTime": 8, - "createTime": 1755599634000, - "model": "bytedance/seedance-1.5-pro", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"bytedance/seedance-1.5-pro\",\"input\":{\"prompt\":\"In a Chinese-English communication scenario, a 70-year-old old man said kindly to the child: Good boy, study hard where you are in China ! The child happily replied in Chinese: Grandpa, I'll come to accompany you when I finish my studies in China . Then the old man stroked the child's head \",\"input_urls\":[\"https://static.aiquickdraw.com/tools/example/1766556007862_Y451Ehaf.png\"],\"aspect_ratio\":\"1:1\",\"resolution\":\"720p\",\"duration\":\"8\"}}", - "resultJson": "{\"resultUrls\":[\"https://example.com/generated-image.jpg\"]}", - "state": "success", - "taskId": "e989621f54392584b05867f87b160672", - "failCode": null, - "failMsg": null, - }, - "msg": "Playground task completed successfully." -} -Failure Callback Example -{ - "code": 501, - "data": { - "completeTime": 1755597081000, - "costTime": 0, - "createTime": 1755596341000, - "failCode": "500", - "failMsg": "Internal server error", - "model": "bytedance/seedance-1.5-pro", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"bytedance/seedance-1.5-pro\",\"input\":{\"prompt\":\"In a Chinese-English communication scenario, a 70-year-old old man said kindly to the child: Good boy, study hard where you are in China ! The child happily replied in Chinese: Grandpa, I'll come to accompany you when I finish my studies in China . Then the old man stroked the child's head \",\"input_urls\":[\"https://static.aiquickdraw.com/tools/example/1766556007862_Y451Ehaf.png\"],\"aspect_ratio\":\"1:1\",\"resolution\":\"720p\",\"duration\":\"8\"}}", - "state": "fail", - "taskId": "bd3a37c523149e4adf45a3ddb5faf1a8", - "resultJson": null, - }, - "msg": "Playground task failed." -} \ No newline at end of file diff --git a/docs/KIE_API_KLING26_I2V_SPEC.md b/docs/KIE_API_KLING26_I2V_SPEC.md deleted file mode 100644 index 5db3918..0000000 --- a/docs/KIE_API_KLING26_I2V_SPEC.md +++ /dev/null @@ -1,168 +0,0 @@ -spec to create a new node for kling , this is a video mode... which is image to text. - -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: - -"kling-2.6/image-to-video" -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 -The text prompt used to generate the video - -Max length: 1000 characters -Example: - -"In a bright rehearsal room, sunlight streams through the window, and a standing microphone is placed in the center of the room. [Campus band female lead singer] stands in front of the microphone with her eyes closed, while the other members stand around her. [Campus band female lead singer, full voice] leads: \"I will try to fix you, with all my heart and soul...\" The background is an a cappella harmony, and the camera slowly circles around the band members." -input.image_urls -Required -array(URL) -The URL of the image used to generate video - -File URL after upload, not file content; Accepted types: image/jpeg, image/png, image/webp; Max size: 10.0MB -Example: - -["https://static.aiquickdraw.com/tools/example/1764851002741_i0lEiI8I.png"] -input.sound -Required -boolean -This parameter is used to specify whether the generated video contains sound - -Boolean value (true/false) -Example: - -false -input.duration -Required -string -Duration of the video in seconds - -Available options: - -5 -- -5 -10 -- -10 -Example: - -"5" -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": "kling-2.6/image-to-video", - "callBackUrl": "https://your-domain.com/api/callback", - "input": { - "prompt": "In a bright rehearsal room, sunlight streams through the window, and a standing microphone is placed in the center of the room. [Campus band female lead singer] stands in front of the microphone with her eyes closed, while the other members stand around her. [Campus band female lead singer, full voice] leads: \"I will try to fix you, with all my heart and soul...\" The background is an a cappella harmony, and the camera slowly circles around the band members.", - "image_urls": [ - "https://static.aiquickdraw.com/tools/example/1764851002741_i0lEiI8I.png" - ], - "sound": false, - "duration": "5" - } -} - -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": "kling-2.6/image-to-video", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"kling-2.6/image-to-video\",\"input\":{\"prompt\":\"In a bright rehearsal room, sunlight streams through the window, and a standing microphone is placed in the center of the room. [Campus band female lead singer] stands in front of the microphone with her eyes closed, while the other members stand around her. [Campus band female lead singer, full voice] leads: \\"I will try to fix you, with all my heart and soul...\\" The background is an a cappella harmony, and the camera slowly circles around the band members.\",\"image_urls\":[\"https://static.aiquickdraw.com/tools/example/1764851002741_i0lEiI8I.png\"],\"sound\":false,\"duration\":\"5\"}}", - "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": "kling-2.6/image-to-video", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"kling-2.6/image-to-video\",\"input\":{\"prompt\":\"In a bright rehearsal room, sunlight streams through the window, and a standing microphone is placed in the center of the room. [Campus band female lead singer] stands in front of the microphone with her eyes closed, while the other members stand around her. [Campus band female lead singer, full voice] leads: \\"I will try to fix you, with all my heart and soul...\\" The background is an a cappella harmony, and the camera slowly circles around the band members.\",\"image_urls\":[\"https://static.aiquickdraw.com/tools/example/1764851002741_i0lEiI8I.png\"],\"sound\":false,\"duration\":\"5\"}}", - "remainedCredits": 2510430, - "state": "fail", - "taskId": "bd3a37c523149e4adf45a3ddb5faf1a8", - "updateTime": 1755597097000 - }, - "msg": "Playground task failed." -} \ No newline at end of file diff --git a/docs/KIE_API_NANOBANANA_SPEC.md b/docs/KIE_API_NANOBANANA_SPEC.md deleted file mode 100644 index 097ccec..0000000 --- a/docs/KIE_API_NANOBANANA_SPEC.md +++ /dev/null @@ -1,495 +0,0 @@ -## Credits (official) -GET https://api.kie.ai/api/v1/chat/credit -Header: Authorization: Bearer YOUR_API_KEY - -Response: -{ - "code": 200, - "msg": "success", - "data": 100 -} -- data = remaining credits (integer) - - -# KIE Nano Banana Pro API (Pinned) -- API key loaded from config/kie_key.txt -- Create task: POST /api/v1/jobs/createTask -- Poll task: GET /api/v1/jobs/recordInfo?taskId= -- Credits: GET https://api.kie.ai/api/v1/chat/credit with header `Authorization: Bearer `; expects JSON `{ "code": 200, "msg": "success", "data": }` and treat non-200 code as error. - -Nano Banan Pro API endpoint info and docs do not use anything other than whats below - -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: - -"nano-banana-pro" -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: 10000 characters -Example: - -"Comic poster: cool banana hero in shades leaps from sci-fi pad. Six panels: 1) 4K mountain landscape, 2) banana holds page of long multilingual text with auto translation, 3) Gemini 3 hologram for search/knowledge/reasoning, 4) camera UI sliders for angle focus color, 5) frame trio 1:1-9:16, 6) consistent banana poses. Footer shows Google icons. Tagline: Nano Banana Pro now on Kie AI." -input.image_input -Optional -array(URL) -Input images to transform or use as reference (supports up to 8 images) - -File URL after upload, not file content; Accepted types: image/jpeg, image/png, image/webp; Max size: 30.0MB -input.aspect_ratio -Optional -string -Aspect ratio of the generated image - -Available options: - -1:1 -- -1:1 -2:3 -- -2:3 -3:2 -- -3:2 -3:4 -- -3:4 -4:3 -- -4:3 -4:5 -- -4:5 -5:4 -- -5:4 -9:16 -- -9:16 -16:9 -- -16:9 -21:9 -- -21:9 -auto -- -Auto -Example: - -"1:1" -input.resolution -Optional -string -Resolution of the generated image - -Available options: - -1K -- -1K -2K -- -2K -4K -- -4K -Example: - -"1K" -input.output_format -Optional -string -Format of the output image - -Available options: - -png -- -PNG -jpg -- -JPG -Example: - -"png" -Request Example - -cURL - -JavaScript - -Python -curl -X POST "https://api.kie.ai/api/v1/jobs/createTask" \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_API_KEY" \ - -d '{ - "model": "nano-banana-pro", - "callBackUrl": "https://your-domain.com/api/callback", - "input": { - "prompt": "Comic poster: cool banana hero in shades leaps from sci-fi pad. Six panels: 1) 4K mountain landscape, 2) banana holds page of long multilingual text with auto translation, 3) Gemini 3 hologram for search/knowledge/reasoning, 4) camera UI sliders for angle focus color, 5) frame trio 1:1-9:16, 6) consistent banana poses. Footer shows Google icons. Tagline: Nano Banana Pro now on Kie AI.", - "aspect_ratio": "1:1", - "resolution": "1K", - "output_format": "png" - } -}' -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": "nano-banana-pro", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"nano-banana-pro\",\"input\":{\"prompt\":\"Comic poster: cool banana hero in shades leaps from sci-fi pad. Six panels: 1) 4K mountain landscape, 2) banana holds page of long multilingual text with auto translation, 3) Gemini 3 hologram for search/knowledge/reasoning, 4) camera UI sliders for angle focus color, 5) frame trio 1:1-9:16, 6) consistent banana poses. Footer shows Google icons. Tagline: Nano Banana Pro now on Kie AI.\",\"image_input\":[],\"aspect_ratio\":\"1:1\",\"resolution\":\"1K\",\"output_format\":\"png\"}}", - "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": "nano-banana-pro", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"nano-banana-pro\",\"input\":{\"prompt\":\"Comic poster: cool banana hero in shades leaps from sci-fi pad. Six panels: 1) 4K mountain landscape, 2) banana holds page of long multilingual text with auto translation, 3) Gemini 3 hologram for search/knowledge/reasoning, 4) camera UI sliders for angle focus color, 5) frame trio 1:1-9:16, 6) consistent banana poses. Footer shows Google icons. Tagline: Nano Banana Pro now on Kie AI.\",\"image_input\":[],\"aspect_ratio\":\"1:1\",\"resolution\":\"1K\",\"output_format\":\"png\"}}", - "remainedCredits": 2510430, - "state": "fail", - "taskId": "bd3a37c523149e4adf45a3ddb5faf1a8", - "updateTime": 1755597097000 - }, - "msg": "Playground task failed." -} - - -KIE AI FILE UPLOAD Stream endpoint to use.. - -# File Stream Upload - -## OpenAPI - -````yaml file-upload-api/file-upload-api.json post /api/file-stream-upload -openapi: 3.0.0 -info: - title: File Upload API - description: >- - File Upload Service API Documentation - Supporting multiple file upload - methods, uploaded files are temporary and automatically deleted after 3 days - version: 1.0.0 - contact: - name: Technical Support - email: support@kie.ai -servers: - - url: https://kieai.redpandaai.co - description: API Server -security: - - BearerAuth: [] -paths: - /api/file-stream-upload: - post: - summary: File Stream Upload - operationId: upload-file-stream - requestBody: - required: true - content: - multipart/form-data: - schema: - type: object - properties: - file: - type: string - format: binary - description: File to upload (binary data) - uploadPath: - type: string - description: File upload path, without leading or trailing slashes - example: images/user-uploads - fileName: - type: string - description: >- - File name (optional), including file extension. If not - provided, a random file name will be generated. If the same - file name is uploaded again, the old file will be - overwritten, but changes may not take effect immediately due - to caching - example: my-image.jpg - required: - - file - - uploadPath - responses: - '200': - $ref: '#/components/responses/SuccessResponse' - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/UnauthorizedError' - '500': - $ref: '#/components/responses/ServerError' -components: - responses: - SuccessResponse: - description: File uploaded successfully - content: - application/json: - schema: - type: object - properties: - success: - type: boolean - description: Whether the request was successful - code: - type: integer - enum: - - 200 - - 400 - - 401 - - 405 - - 500 - description: >- - Response Status Code - - - | Code | Description | - - |------|-------------| - - | 200 | Success - Request has been processed successfully | - - | 400 | Bad Request - Request parameters are incorrect or - missing required parameters | - - | 401 | Unauthorized - Authentication credentials are missing - or invalid | - - | 405 | Method Not Allowed - Request method is not supported | - - | 500 | Server Error - An unexpected error occurred while - processing the request | - msg: - type: string - description: Response message - example: File uploaded successfully - data: - $ref: '#/components/schemas/FileUploadResult' - required: - - success - - code - - msg - - data - example: - success: true - code: 200 - msg: File uploaded successfully - data: - fileName: uploaded-image.png - filePath: images/user-uploads/uploaded-image.png - downloadUrl: >- - https://tempfile.redpandaai.co/xxx/images/user-uploads/uploaded-image.png - fileSize: 154832 - mimeType: image/png - uploadedAt: '2025-01-01T12:00:00.000Z' - BadRequestError: - description: Request parameter error - content: - application/json: - schema: - $ref: '#/components/schemas/ApiResponse' - examples: - missing_parameter: - summary: Missing required parameter - value: - success: false - code: 400 - msg: 'Missing required parameter: uploadPath' - invalid_format: - summary: Format error - value: - success: false - code: 400 - msg: 'Base64 decoding failed: Invalid Base64 format' - UnauthorizedError: - description: Unauthorized access - content: - application/json: - schema: - $ref: '#/components/schemas/ApiResponse' - example: - success: false - code: 401 - msg: 'Authentication failed: Invalid API Key' - ServerError: - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/ApiResponse' - example: - success: false - code: 500 - msg: Internal server error - schemas: - FileUploadResult: - type: object - properties: - fileName: - type: string - description: File name - example: uploaded-image.png - filePath: - type: string - description: Complete file path in storage - example: images/user-uploads/uploaded-image.png - downloadUrl: - type: string - format: uri - description: File download URL - example: >- - https://tempfile.redpandaai.co/xxx/images/user-uploads/uploaded-image.png - fileSize: - type: integer - description: File size in bytes - example: 154832 - mimeType: - type: string - description: File MIME type - example: image/png - uploadedAt: - type: string - format: date-time - description: Upload timestamp - example: '2025-01-01T12:00:00.000Z' - required: - - fileName - - filePath - - downloadUrl - - fileSize - - mimeType - - uploadedAt - ApiResponse: - type: object - properties: - success: - type: boolean - description: Whether the request was successful - code: - $ref: '#/components/schemas/StatusCode' - msg: - type: string - description: Response message - example: File uploaded successfully - required: - - success - - code - - msg - StatusCode: - type: integer - enum: - - 200 - - 400 - - 401 - - 405 - - 500 - description: >- - Response Status Code - - - | Code | Description | - - |------|-------------| - - | 200 | Success - Request has been processed successfully | - - | 400 | Bad Request - Request parameters are incorrect or missing - required parameters | - - | 401 | Unauthorized - Authentication credentials are missing or invalid - | - - | 405 | Method Not Allowed - Request method is not supported | - - | 500 | Server Error - An unexpected error occurred while processing the - request | - securitySchemes: - BearerAuth: - type: http - scheme: bearer - bearerFormat: API Key - description: >- - All APIs require authentication via Bearer Token. - - - Get API Key: - - 1. Visit [API Key Management Page](https://kie.ai/api-key) to get your - API Key - - - Usage: - - Add to request header: - - Authorization: Bearer YOUR_API_KEY - -```` - ---- - -> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.kie.ai/llms.txt. diff --git a/docs/KIE_API_SEEDANCEV1Pro_FAST_I2V.md b/docs/KIE_API_SEEDANCEV1Pro_FAST_I2V.md deleted file mode 100644 index 4af53e5..0000000 --- a/docs/KIE_API_SEEDANCEV1Pro_FAST_I2V.md +++ /dev/null @@ -1,171 +0,0 @@ -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: - -"bytedance/v1-pro-fast-image-to-video" -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 -The text prompt used to generate the video - -Max length: 10000 characters -Example: - -"A cinematic close-up sequence of a single elegant ceramic coffee cup with saucer on a rustic wooden table near a sunlit window, hot rich espresso poured in a thin golden stream from above, gradually filling the cup in distinct stages: empty with faint steam, 1/4 filled with dark crema, half-filled with swirling coffee and rising steam, 3/4 filled nearing the rim, perfectly full just below overflow with glossy surface and soft bokeh highlights; ultra-realistic, warm golden-hour light, shallow depth of field, photorealism, detailed textures, subtle steam wisps, serene inviting atmosphere --ar 16:9 --q 2 --style raw" -input.image_url -Required -string(URL) -The URL of the image used to generate video - -File URL after upload, not file content; Accepted types: image/jpeg, image/png, image/webp; Max size: 10.0MB -Example: - -"https://file.aiquickdraw.com/custom-page/akr/section-images/1762340693669m6sey187.webp" -input.resolution -Optional -string -Video resolution - 480p for faster generation, 720p for balance, 1080p for higher quality - -Available options: - -720p -- -720p -1080p -- -1080p -Example: - -"720p" -input.duration -Optional -string -Duration of the video in seconds - -Available options: - -5 -- -5s -10 -- -10s -Example: - -"5" -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": "bytedance/v1-pro-fast-image-to-video", - "callBackUrl": "https://your-domain.com/api/callback", - "input": { - "prompt": "A cinematic close-up sequence of a single elegant ceramic coffee cup with saucer on a rustic wooden table near a sunlit window, hot rich espresso poured in a thin golden stream from above, gradually filling the cup in distinct stages: empty with faint steam, 1/4 filled with dark crema, half-filled with swirling coffee and rising steam, 3/4 filled nearing the rim, perfectly full just below overflow with glossy surface and soft bokeh highlights; ultra-realistic, warm golden-hour light, shallow depth of field, photorealism, detailed textures, subtle steam wisps, serene inviting atmosphere --ar 16:9 --q 2 --style raw", - "image_url": "https://file.aiquickdraw.com/custom-page/akr/section-images/1762340693669m6sey187.webp", - "resolution": "720p", - "duration": "5" - } -} - -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": "bytedance/v1-pro-fast-image-to-video", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"bytedance/v1-pro-fast-image-to-video\",\"input\":{\"prompt\":\"A cinematic close-up sequence of a single elegant ceramic coffee cup with saucer on a rustic wooden table near a sunlit window, hot rich espresso poured in a thin golden stream from above, gradually filling the cup in distinct stages: empty with faint steam, 1/4 filled with dark crema, half-filled with swirling coffee and rising steam, 3/4 filled nearing the rim, perfectly full just below overflow with glossy surface and soft bokeh highlights; ultra-realistic, warm golden-hour light, shallow depth of field, photorealism, detailed textures, subtle steam wisps, serene inviting atmosphere --ar 16:9 --q 2 --style raw\",\"image_url\":\"https://file.aiquickdraw.com/custom-page/akr/section-images/1762340693669m6sey187.webp\",\"resolution\":\"720p\",\"duration\":\"5\"}}", - "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": "bytedance/v1-pro-fast-image-to-video", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"bytedance/v1-pro-fast-image-to-video\",\"input\":{\"prompt\":\"A cinematic close-up sequence of a single elegant ceramic coffee cup with saucer on a rustic wooden table near a sunlit window, hot rich espresso poured in a thin golden stream from above, gradually filling the cup in distinct stages: empty with faint steam, 1/4 filled with dark crema, half-filled with swirling coffee and rising steam, 3/4 filled nearing the rim, perfectly full just below overflow with glossy surface and soft bokeh highlights; ultra-realistic, warm golden-hour light, shallow depth of field, photorealism, detailed textures, subtle steam wisps, serene inviting atmosphere --ar 16:9 --q 2 --style raw\",\"image_url\":\"https://file.aiquickdraw.com/custom-page/akr/section-images/1762340693669m6sey187.webp\",\"resolution\":\"720p\",\"duration\":\"5\"}}", - "remainedCredits": 2510430, - "state": "fail", - "taskId": "bd3a37c523149e4adf45a3ddb5faf1a8", - "updateTime": 1755597097000 - }, - "msg": "Playground task failed." -} \ No newline at end of file diff --git a/docs/KIE_API_SEEDREAM_45_EDIT_SPEC.md b/docs/KIE_API_SEEDREAM_45_EDIT_SPEC.md deleted file mode 100644 index d237a99..0000000 --- a/docs/KIE_API_SEEDREAM_45_EDIT_SPEC.md +++ /dev/null @@ -1,193 +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 -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." -} \ No newline at end of file diff --git a/docs/KIE_API_SEEDREAM_T2I_SPEC.md b/docs/KIE_API_SEEDREAM_T2I_SPEC.md deleted file mode 100644 index d964940..0000000 --- a/docs/KIE_API_SEEDREAM_T2I_SPEC.md +++ /dev/null @@ -1,171 +0,0 @@ -SEEDREAM 4.5 T2I API INFORMATION - -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-text-to-image" -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: - -"A full-process cafe design tool for entrepreneurs and designers. It covers core needs including store layout, functional zoning, decoration style, equipment selection, and customer group adaptation, supporting integrated planning of \"commercial attributes + aesthetic design.\" Suitable as a promotional image for a cafe design SaaS product, with a 16:9 aspect ratio." -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 -curl -X POST "https://api.kie.ai/api/v1/jobs/createTask" \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_API_KEY" \ - -d '{ - "model": "seedream/4.5-text-to-image", - "callBackUrl": "https://your-domain.com/api/callback", - "input": { - "prompt": "A full-process cafe design tool for entrepreneurs and designers. It covers core needs including store layout, functional zoning, decoration style, equipment selection, and customer group adaptation, supporting integrated planning of \"commercial attributes + aesthetic design.\" Suitable as a promotional image for a cafe design SaaS product, with a 16:9 aspect ratio.", - "aspect_ratio": "1:1", - "quality": "basic" - } -}' -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-text-to-image", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"seedream/4.5-text-to-image\",\"input\":{\"prompt\":\"A full-process cafe design tool for entrepreneurs and designers. It covers core needs including store layout, functional zoning, decoration style, equipment selection, and customer group adaptation, supporting integrated planning of \\"commercial attributes + aesthetic design.\\" Suitable as a promotional image for a cafe design SaaS product, with a 16:9 aspect ratio.\",\"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-text-to-image", - "param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"seedream/4.5-text-to-image\",\"input\":{\"prompt\":\"A full-process cafe design tool for entrepreneurs and designers. It covers core needs including store layout, functional zoning, decoration style, equipment selection, and customer group adaptation, supporting integrated planning of \\"commercial attributes + aesthetic design.\\" Suitable as a promotional image for a cafe design SaaS product, with a 16:9 aspect ratio.\",\"aspect_ratio\":\"1:1\",\"quality\":\"basic\"}}", - "remainedCredits": 2510430, - "state": "fail", - "taskId": "bd3a37c523149e4adf45a3ddb5faf1a8", - "updateTime": 1755597097000 - }, - "msg": "Playground task failed." -} \ No newline at end of file diff --git a/docs/KIE_PROMPT_GRID_SPEC.md b/docs/KIE_PROMPT_GRID_SPEC.md deleted file mode 100644 index 6d90392..0000000 --- a/docs/KIE_PROMPT_GRID_SPEC.md +++ /dev/null @@ -1,34 +0,0 @@ -KIE Prompt Grid Parser Spec - -Node name -- KIE Parse Prompt Grid JSON (1..9) - -Inputs -- json_text (STRING, multiline): JSON text from an LLM -- default_prompt (STRING, optional): Fallback prompt when parsing yields no prompts and strict is false -- max_items (INT, optional, default 9): Maximum number of prompts to return (1..9) - -Accepted JSON shapes -a) list[str] - ["Prompt 1", "Prompt 2", "Prompt 3"] - -b) {"prompts": list[str]} - {"prompts": ["Prompt 1", "Prompt 2"]} - -c) Object keys like p1..p9 / prompt1.. / "Prompt 1" / numeric "1".."9" - { - "p1": "Prompt 1", - "prompt2": "Prompt 2", - "Prompt 3": "Prompt 3", - "4": "Prompt 4" - } - -Outputs -- p1..p9 (STRING): Individual prompts (missing entries are empty strings) -- count (INT): Number of prompts parsed -- prompts_list: Raw list of prompts for future automation - -Behavior notes -- Prompts are trimmed and empty strings are dropped. -- Keyed objects are ordered by numeric suffix. -- Parsing failures raise a ValueError unless strict is false and a default_prompt is provided at the node level. diff --git a/docs/MODEL_IMPLEMENTATION_TEMPLATE.md b/docs/MODEL_IMPLEMENTATION_TEMPLATE.md deleted file mode 100644 index a31a113..0000000 --- a/docs/MODEL_IMPLEMENTATION_TEMPLATE.md +++ /dev/null @@ -1,188 +0,0 @@ -i# KIE Model Implementation Template - -This document defines the REQUIRED structure and conventions for adding new -KIE API models to this repository. - -All new models MUST follow this template to ensure: -- ComfyUI compatibility -- shared polling & error handling -- consistent logging -- minimal duplication - ---- - -## File Placement - -Each KIE model MUST live in its own file: - -kie_api/.py - -i -Examples: -- nanobanana.py -- seedream45.py -- veo3.py - ---- - -## Required Imports - -Models MUST reuse shared helpers. Do NOT duplicate logic. - -```python -from typing import Any - -from .auth import _load_api_key -from .credits import _log_remaining_credits -from .jobs import create_task, poll_task_until_complete -from .images import image_bytes_to_comfy_tensor -from .http import TransientKieError -from .log import log - -Required Constants - -Each model MUST define: - -MODEL_NAME = "" - -Optional: - -ASPECT_RATIO_OPTIONS = [...] -RESOLUTION_OPTIONS = [...] -OUTPUT_FORMAT_OPTIONS = [...] - -Required Public Entry Function - -Each model MUST expose exactly ONE public runner: - -def run_( - *, - prompt: str, - image_inputs: list[bytes] | None, - aspect_ratio: str, - resolution: str, - output_format: str, - poll_interval_s: float, - timeout_s: int, - log: bool, -) -> torch.Tensor: - -Rules: - --MUST validate required inputs --MUST create task via create_task(...) --MUST poll via poll_task_until_complete(...) --MUST return ComfyUI IMAGE tensor (BHWC, float32, 0–1) --MUST NOT print directly (use log helper) - -Logging Rules - --Logging is controlled by log: bool --Use shared logger only --Avoid dumping full JSON payloads --Summarize state transitions only - -Good: - -[KIE] Task state: waiting (elapsed=30s) - - -Bad: - -[KIE] Full recordInfo JSON: {...huge...} - -Error Handling Rules -Use RuntimeError when: - --user input is invalid --model fails permanently --decoding output fails -Use TransientKieError when: --API reports temporary failure --retry is reasonable - -Never swallow exceptions silently. - -Image Output Requirements (ComfyUI) - -All image outputs MUST: - --be torch.Tensor --shape: [B, H, W, C] --dtype: float32 --range: 0.0 – 1.0 --reside on CPU - -Use ONLY: - -image_bytes_to_comfy_tensor(...) - - -Forbidden Patterns ❌ - --No polling loops inside nodes.py --No direct requests calls in nodes.py --No torch.frombuffer on raw bytes --No duplicated polling code --No printing directly to console - -Node Layer Responsibility - -Nodes MUST: - --define INPUT_TYPES --define RETURN_TYPES --call exactly one model runner --never perform HTTP or polling logic - -Versioning - -Each model file SHOULD include a header comment: - -# Model: Seedream 4.5 -# API version: 2025-xx -# KIE Docs: - - -## Video Models - -Video-producing models MUST: -- return a local file path (string) -- use kie_api.video helpers -- NOT decode frames -- NOT return tensors - -Public runner signature example: - -```python -def run__video(...) -> str: - """Returns a path to a local video file.""" -yaml - - -This teaches Codex the rule **once**, forever. - ---- - -### 🔹 Step 3 — Create your first KIE video model runner -Now you’re ready for Codex. - -📍 **Use VS Code + Codex** - -**Prompt (copy exactly):** -```text -Add a KIE video model runner following docs/MODEL_IMPLEMENTATION_TEMPLATE.md. - -Tasks: -1. Create kie_api/_video.py -2. Use shared helpers: - - _poll_task_until_complete - - _extract_result_urls - - _download_video - - _write_video_to_temp_file -3. Return a VIDEO file path (string). -4. Do NOT decode video frames. -5. Show diff before applying. - -Always when done add the proper model to nodes.py and adjust the mappings to add this new model - diff --git a/docs/NEW_NODE_CHECKLIST.md b/docs/NEW_NODE_CHECKLIST.md deleted file mode 100644 index 924e6a1..0000000 --- a/docs/NEW_NODE_CHECKLIST.md +++ /dev/null @@ -1,177 +0,0 @@ -✅ The “New KIE Node” Golden Workflow (Save This) -Phase 0 — Clean slate (Terminal) - -Always start here. - --- git status - -If anything is modified: - --commit it or --stash it - -Never add a new node on a dirty tree. - -Phase 1 — Pin the API (VS Code + Codex) - -📍 Tool: VS Code Codex - -Step 1: Add API spec doc - -Create: - --- docs/KIE_API__SPEC.md - -Codex prompt: - -Create docs/KIE_API__SPEC.md pinned to the official KIE documentation. -Include: -- model name -- endpoints -- request payload -- allowed options -- example responses -Do not invent fields. -Show diff before applying. - - -✔ This becomes the single source of truth -✔ Codex will reference this later - -Phase 2 — Implement model runner (VS Code + Codex) - -📍 Tool: VS Code Codex - -Step 2: Add model file - -Create: - -kie_api/.py - -Codex prompt - -Add kie_api/.py following docs/MODEL_IMPLEMENTATION_TEMPLATE.md -and docs/KIE_API__SPEC.md. - -Rules: -- Use shared helpers (auth, jobs, images, credits) -- Do NOT duplicate polling or decoding -- Expose exactly one public function: run_() -- Return ComfyUI IMAGE tensor (BHWC float32 0–1) -Show diff before applying. - -✔ No node UI here -✔ Pure API + data logic - -Phase 3 — Add ComfyUI node wrapper (VS Code + Codex) - -📍 Tool: VS Code Codex - -Step 3: Create node class in nodes.py - -Node = thin wrapper only. - -Codex prompt - -Add a new ComfyUI node class KIE_ to nodes.py. - -Requirements: -- Inputs mirror KIE API fields -- Call run_() only -- Add HELP text using ComfyUI help_page format -- Follow existing node style -Do not restructure the file. -Show diff before applying. - - -✔ This is where: - -dropdowns - -inputs - -help text live - -Phase 4 — REGISTER THE NODE (this is the part people forget) - -📍 Tool: VS Code Codex - -Step 4: Register the node - -Always do this as a separate Codex step. - -Codex prompt - -Register the new node so it appears in ComfyUI. - -Tasks: -1) Ensure the node class is imported in nodes.py -2) Add it to NODE_CLASS_MAPPINGS -3) Add a display name to NODE_DISPLAY_NAME_MAPPINGS -Do not modify other nodes. -Show diff before applying. - - -✔ If this step is skipped → node does NOT exist -✔ This is the #1 missing step you just hit - -Phase 5 — Sanity checks (Terminal) - -📍 Tool: Terminal - -python3 -m py_compile nodes.py -python3 -m py_compile kie_api/.py - - -If this fails → fix before committing. - -Phase 6 — Commit cleanly - -📍 Tool: Terminal - -git add nodes.py kie_api/.py docs/KIE_API__SPEC.md -git commit -m "feat: add node" -git push - - -One model = one commit. - -Phase 7 — Windows ComfyUI test - -📍 Tool: Windows - --git pull --restart ComfyUI --search node by name --run minimal test - -🔁 TL;DR Cheat Sheet - -Every new node: - --📄 Spec doc --⚙️ Model runner (kie_api/*.py) --🧱 Node class (nodes.py) --🔌 Register node in mappings --❓ Add HELP text --✅ Compile --🚀 Commit - -Why this works - --Codex is great at isolated tasks --Registration is always explicit --MODEL_IMPLEMENTATION_TEMPLATE.md prevents drift --Help text is never forgotten --ComfyUI never silently skips your node - -Optional power move (later) - -When you’re ready, you can add: - -docs/NEW_NODE_CHECKLIST.md - - -and literally paste this workflow in it — Codex can even be told: - -“Follow docs/NEW_NODE_CHECKLIST.md exactly.” \ No newline at end of file diff --git a/docs/REPO_RULES.md b/docs/REPO_RULES.md deleted file mode 100644 index a0a20bd..0000000 --- a/docs/REPO_RULES.md +++ /dev/null @@ -1,167 +0,0 @@ -# ComfyUI-Kie-API — Repo Rules (Source of Truth) - -This document is the **single source of truth** for how this repo is structured and how changes must be made. - -If you are using Codex (terminal or VS Code), **read this file before making changes**. - ---- - -## 1) Non-negotiable rules - -- **No manual edits by the user.** All code changes are made via Codex. -- Any change that affects behavior must update **all applicable** areas: - - `kie_api/*.py` (helpers + model code) - - `nodes.py` (node registration) - - `web/docs/*.md` (user-facing node docs) -- Keep code separation clean: - - **Helpers are generic** (shared utilities, HTTP client, polling, conversions, validation) - - **Model files are model-specific** (request payload, endpoints, response parsing) -- ComfyUI image tensors are **BHWC float32 in the range 0..1**. -- **VIDEO outputs must be compatible with ComfyUI `SaveVideo`.** - - Match the repo’s existing return convention used by current video nodes. - ---- - -## 2) Make the repo the source of truth - -Add and maintain these docs so Codex stays aligned without relying on chat history: - -### A) `docs/MODEL_IMPLEMENTATION_TEMPLATE.md` -Keep this file updated. It must include: - -- Required function signature pattern for `run__*` -- Standard logging pattern: `_log(log, "…")` -- Standard retry behavior (what gets retried, backoff, max attempts) -- Standard return types: - - **IMAGE**: tensor (BHWC float32 0..1) - - **VIDEO**: SaveVideo-compatible object (match repo convention) -- “Where to register” checklist: - - `nodes.py` - - `NODE_CLASS_MAPPINGS` - - `NODE_DISPLAY_NAME_MAPPINGS` - - `web/docs/*.md` - -### B) `docs/REPO_RULES.md` -This file (you are reading it) contains the bullet rules and workflow. - ---- - -## 3) Repeatable feature workflow (7-step loop) - -Every new feature follows the same loop: - -1. Create spec doc (1 file): `docs/KIE__SPEC.md` -2. Run Codex to generate/modify code -3. Run `py_compile` on touched modules -4. Restart ComfyUI and confirm node loads -5. Run **1 minimal workflow test** -6. Add/update `web/docs` markdown for the node -7. Commit - -This keeps changes small, testable, and debuggable. - ---- - -## 4) Choose one next feature (don’t bundle) - -Do changes as small PR-sized chunks. Avoid bundling multiple unrelated changes. - -Good next “small chunks” for this repo: - -- Video input validation (duration, resolution) using `ffprobe` fallback (optional) -- Upload util supports generic files (image/video) via one function -- GridSlice: move core slicing logic into `kie_api/grid.py` (if not already) -- Node docs for all current nodes using the `web/docs` system -- Standard “Result URL print” for all video nodes - ---- - -## 5) Codex usage pattern (fast + consistent) - -Use this every time: - -### Terminal -```bash -git checkout -b feature/ -codex -``` - -### Instruction block format (keep it short) -Include: - -- **Files to touch** -- **What to add/change** -- **What not to change** -- **Compile command** - -Example skeleton: - -```text -You are working in ComfyUI-Kie-API. - -Hard rules: -- Do not ask the user to manually edit code; make all edits yourself. -- Preserve ComfyUI image tensor contract: BHWC float32 0..1. -- VIDEO outputs must remain compatible with SaveVideo (match existing repo convention). -- Keep helpers generic and model files model-specific. - -Files to touch: -- kie_api/<...>.py -- nodes.py -- web/docs/<...>.md -- docs/KIE__SPEC.md - -Change: -- - -Do NOT change: -- Existing node return conventions -- Unrelated nodes - -After edits, ensure this compiles: -python3 -m py_compile nodes.py kie_api/*.py -``` - ---- - -## 6) Debugging without flooding chat - -When something breaks, only bring: - -- The **stack trace** -- The **one file name + function** mentioned in the error -- The **NODE_CLASS_MAPPINGS** entry (if it’s a load failure) - -Do not paste the entire `nodes.py` unless the error is inside `nodes.py`. - ---- - -## 7) Verification (required every change) - -### A) Compile check -Run from repo root: - -```bash -python3 -m py_compile nodes.py kie_api/*.py -``` - -### B) Quick ComfyUI checklist - -- Start/restart ComfyUI -- Confirm the node appears in the expected category -- Drop node into a minimal graph -- Queue prompt and confirm: - - No console errors - - Output type is correct (IMAGE/VIDEO) - - VIDEO: wire into **SaveVideo** and confirm it saves successfully - ---- - -## Current nodes (reference) - -- NanoBanana image -- Seedream t2i/edit -- Kling26 i2v -- Kling26 motion-control i2v -- Seedance i2v -- GridSlice diff --git a/docs/TENSOR_IMAGE_CONVERSIONS.md b/docs/TENSOR_IMAGE_CONVERSIONS.md deleted file mode 100644 index 1da6da4..0000000 --- a/docs/TENSOR_IMAGE_CONVERSIONS.md +++ /dev/null @@ -1,4 +0,0 @@ -# Tensor/Image Conversion Rules -Use PIL + numpy. -Never guess tensor shape. -Always batch-safe.