# Comfyui-Kling-Wrapper Comfyui-Kling-Wrapper is a ComfyUI custom node pack for calling the Kling AI API directly inside ComfyUI. It bundles image generation, text-to-video, image-to-video, multi-image video, advanced custom elements, motion control, advanced lip sync, Avatar image-to-video, text/video to audio, TTS, custom voice creation, effects, virtual try-on, image expansion, and local preview helpers under the `Comfyui-Kling-Wrapper` category. ## Highlights - Direct Kling API access from ComfyUI workflows - New-system features such as `element_list`, advanced custom elements, reference video, and motion control - Built-in `voice_preset` dropdown for models that support native audio generation - Custom voice creation plus returned trial audio preview flow - Importable example workflows in [examples/README.md](./examples/README.md) ## Current model visibility The plugin keeps the visible model dropdowns aligned with models confirmed for the active integration paths. Visible image generation models: - `kling-v1` - `kling-v1-5` - `kling-v2` - `kling-v2-new` - `kling-v2-1` - `kling-v3` Visible text-to-video models: - `kling-v1` - `kling-v1-6` - `kling-v2-master` - `kling-v2-1-master` - `kling-v2-5-turbo` - `kling-v2-6` - `kling-v3` - `kling-v3-omni` Visible image-to-video models: - `kling-v1` - `kling-v1-5` - `kling-v1-6` - `kling-v2-master` - `kling-v2-1` - `kling-v2-1-master` - `kling-v2-5-turbo` - `kling-v2-6` - `kling-v3` - `kling-v3-omni` Visible multi-image video models: - `kling-v2-1` - `kling-v2-5-turbo` - `kling-v3` - `kling-v3-omni` Visible video generation modes: - `std` - `pro` - `4k` (`kling-v3` and `kling-v3-omni` text-to-video, image-to-video, and multi-image video; the API uses `mode: "4k"`) Documented newer models such as `kling-image-o1` and `kling-video-o1` still exist in the internal capability map, but are hidden from the UI until live endpoint support is confirmed for normal accounts. ## Important limitations - Native 4K video output is exposed through the video `mode` dropdown. Models that do not support `mode=4k` will be rejected by the node capability checks before submission. - Native preset and cloned voices are available for `kling-v2-6`; `Image2Video.custom_voice_id` sends cloned voice control through `voice_list`. The active API rejects this field for `kling-v3`. - `kling-v3-omni` is visible for text-to-video, image-to-video, and multi-image video comparison. It can combine `voice_list`/`custom_voice_id` with `element_list`; reference-video requests remain guarded because native audio and `mode=4k` are rejected when `reference_video` is provided. - `kling-video-o1` remains hidden until live endpoint support is confirmed for normal accounts. - `Advanced Element Create` requires 1 frontal subject image plus 1-3 additional reference images of the same subject. Background images do not count as reference images. - `Advanced Element Create` also enforces `element_name <= 20` characters and `element_description <= 100` characters. - If you need both strong subject consistency and voiced output, the reliable flow on the current endpoint is usually: generate the bound subject video first, then add speech with `Lip Sync`, `TextToAudio`, or `Video2Audio`. ## Requirements Before using these nodes, you need a Kling API key: - [Kling API key documentation](https://docs.qingque.cn/d/home/eZQA6m4cRjTB1BBiE5eJ4lyvL?identityId=1oEER8VjdS8) Python dependencies are listed in [requirements.txt](./requirements.txt). ## Installation ### Manual installation 1. Open your `ComfyUI/custom_nodes` directory. 2. Clone this repository: ```bash git clone https://github.com/magicwang1111/Comfyui-Kling-Wrapper.git ``` 3. Install dependencies: Windows (portable ComfyUI): ```bash python -m pip install -r ComfyUI\custom_nodes\Comfyui-Kling-Wrapper\requirements.txt ``` Linux or macOS: ```bash cd Comfyui-Kling-Wrapper pip install -r requirements.txt ``` 4. Create `config.local.json` in the repository root. You can copy [config.example.json](./config.example.json) and fill in your Kling credentials: ```json { "provider_default": "official", "api_key": "", "access_key": "", "secret_key": "", "poll_interval": 1.0, "request_timeout": 30, "area": "global", "oss_endpoint": "", "oss_access_key_id": "", "oss_access_key_secret": "", "oss_bucket": "", "oss_prefix": "kling_uploads", "oss_signed_url_expires": 86400, "vapeur_api_key": "", "vapeur_base_url": "https://api.vapeur.ai", "vapeur_poll_interval": 5.0, "vapeur_request_timeout": 120, "vapeur_max_wait_seconds": 3600 } ``` Notes: - `api_key` is the newer Kling official static Bearer token. When it is set, the official client uses `Authorization: Bearer ` and does not require `access_key`/`secret_key` JWT signing. - `provider_default` accepts `official`, `tencent_vod`, or `vapeur`. Provider selection remains backend-only and is not stored in ComfyUI workflows. - Vapeur uses only `vapeur_api_key` (or `VAPEUR_API_KEY`) and never falls back to official or Tencent credentials. Its default base URL is `https://api.vapeur.ai`. - Vapeur model IDs are isolated from official Kling model IDs. The verified catalog currently maps `kling-v2-6` to `kling-v2-6-cn` and `kling-v3` to `kling-v3-cn`; other models fail locally instead of submitting an unauthorized task. - Vapeur supports Text2Video, Image2Video, Multi Images To Video, Motion Control, Video Extender, Custom Voice Create/Query, and Advanced Element Create/Query. Nodes absent from the supplied Vapeur API, plus MultiModal Video Edit (`kling-v3-omni` is unavailable), image generation, image expansion, virtual try-on, lip sync, avatar, effects, audio generation, TTS, and element deletion, fail explicitly instead of falling back to another provider. - `access_key` and `secret_key` remain supported for the older AK/SK signing flow. - `config.local.json` is ignored by git and should hold your real private keys. - `config.example.json` is only a template and is never read as live config. - Legacy [config.ini](./config.ini) is still accepted as a fallback for `KLINGAI_API_ACCESS_KEY` and `KLINGAI_API_SECRET_KEY`. 5. Restart ComfyUI and search for nodes prefixed with `Comfyui-Kling-Wrapper`. ## Node list - `Comfyui-Kling-Wrapper Image Generator` - `Comfyui-Kling-Wrapper Image Expander` - `Comfyui-Kling-Wrapper Text2Video` - `Comfyui-Kling-Wrapper Image2Video` - `Comfyui-Kling-Wrapper Multi Images To Video` - `Comfyui-Kling-Wrapper Virtual Try On` - `Comfyui-Kling-Wrapper Video Extender` - `Comfyui-Kling-Wrapper Lip Sync` - `Comfyui-Kling-Wrapper Lip Sync Text Input` - `Comfyui-Kling-Wrapper Lip Sync Audio Input` - `Comfyui-Kling-Wrapper Avatar` - `Comfyui-Kling-Wrapper Effects` - `Comfyui-Kling-Wrapper TextToAudio` - `Comfyui-Kling-Wrapper TTS` - `Comfyui-Kling-Wrapper Custom Voice Create` - `Comfyui-Kling-Wrapper Custom Voice Query` - `Comfyui-Kling-Wrapper Custom Voice List Builder` - `Comfyui-Kling-Wrapper Video2Audio` - `Comfyui-Kling-Wrapper Advanced Element Create` - `Comfyui-Kling-Wrapper Advanced Element Query` - `Comfyui-Kling-Wrapper Element List Builder` - `Comfyui-Kling-Wrapper Motion Control` - `Comfyui-Kling-Wrapper Preview Video` - `Comfyui-Kling-Wrapper Preview Audio` ## Lip sync notes `Lip Sync` now calls `/v1/videos/identify-face` followed by `/v1/videos/advanced-lip-sync`. Leave `face_id` empty to select the first detected face, or enter a returned face ID explicitly. `Lip Sync Audio Input` accepts exactly one of a ComfyUI `AUDIO` connection, Kling `audio_id`, local `audio_file`, or public `audio_url`. ComfyUI audio supplies its duration automatically; URL, file, and ID inputs must provide `sound_end_time_ms` when the duration cannot be inferred. `Lip Sync` accepts generated `video_id`, public `video_url`, local `video_file`, ComfyUI `VIDEO`, or `video_frames` plus `video_info` from `VHS_LoadVideo`. Local video inputs are uploaded through the same temporary media relay used by motion control. For a Video Helper Suite workflow, connect `LoadAudio` -> `Lip Sync Audio Input.audio`, then connect `VHS_LoadVideo.IMAGE` -> `Lip Sync.video_frames` and `VHS_LoadVideo.video_info` -> `Lip Sync.video_info`. `Lip Sync Text Input` remains supported. The node first creates preset-voice audio through `/v1/audio/tts`, then sends the resulting `audio_id` to Advanced Lip Sync. ## Avatar notes `Avatar` calls `/v1/videos/avatar/image2video` with one ComfyUI `IMAGE` and exactly one of `AUDIO`, `audio_id`, `audio_file`, or `audio_url`. Local ComfyUI audio is validated to be between 2 and 300 seconds before submission. ## Custom voice and TTS notes `Custom Voice Create` accepts one source at a time: a ComfyUI `AUDIO` input, a local `voice_file`, a public `voice_url`, or a Kling `video_id`. Local audio/files are uploaded through the same temporary media relay used by other media inputs. The custom voice API returns a reusable `voice_id` plus a `trial_url` when the task succeeds. To audition the cloned voice, connect `Custom Voice Create.trial_url` or `Custom Voice Query.trial_url` directly to `Preview Audio.audio_url`. Kling currently returns `Voice id not found` when a custom voice ID from `Custom Voice Create` is sent to `/v1/audio/tts`. Use `TTS` with official or preset voice IDs; use `trial_url` to preview custom voices. Kling requires clean single-speaker source media between 5 and 30 seconds for voice cloning. Connect `Custom Voice Create.voice_id` to `Image2Video.custom_voice_id` and select `kling-v2-6` to use the cloned voice. Set `mode=pro`, `sound=on`, use a 5- or 10-second duration, and reference the voice as `<<>>` in the prompt. Custom voice mode rejects simultaneous `voice_preset` or `element_list` input. ## Motion control notes `Motion Control` now accepts reference video only from workflow inputs: - `reference_video_input`: connect a node that outputs `VIDEO` - `reference_video_frames` + `reference_video_info`: connect an uploaded video loader that outputs decoded frames plus timing metadata - `reference_video`: pass an existing public http(s) video URL directly Reference images and local reference videos must be reachable by Kling before generation starts. If OSS settings are present in `config.local.json` or environment variables (`OSS_ENDPOINT`, `OSS_ACCESS_KEY_ID`, `OSS_ACCESS_KEY_SECRET`, `OSS_BUCKET`, `OSS_PREFIX`), the wrapper uploads media to Aliyun OSS first and sends Kling a signed temporary download URL. Without OSS, it falls back to public temporary hosts: `tmpfiles.org`, then `catbox.moe`. The visible `model_name` dropdown for motion control is: - `kling-v2-6` - `kling-v3` `duration` is now a dropdown with: - `auto` - `3` - `5` - `10` - `15` - `30` When `duration` is set to `auto`, the node tries to match the uploaded reference video's duration using the connected video metadata or the `VIDEO` input object. `character_orientation` controls whether subject orientation follows the reference image or the reference video: - `image`: keep orientation from the reference image while transferring motion from the video - `video`: follow both motion and orientation from the reference video ## Voice presets `Text2Video` and `Image2Video` expose a `voice_preset` dropdown. `Image2Video` additionally accepts a connected `custom_voice_id` for one custom voice, or a connected `custom_voice_list` from `Custom Voice List Builder` for multiple custom voices. The selected preset is converted to: ```json [{"voice_id":"..."}] ``` These presets are mainly intended for models that support native audio generation on the active endpoint, especially `kling-v2-6`. For multiple custom voices, connect one or more `Custom Voice Create.voice_id` outputs to `Custom Voice List Builder`, then connect its `custom_voice_list` output to `Image2Video.custom_voice_list`. Set `sound=on` and reference each voice in order with prompt markers such as `<<>>` and `<<>>`. `custom_voice_list`, `custom_voice_id`, and `voice_preset` are mutually exclusive. For official or manually supplied preset voice IDs, use the dedicated `TTS` node. It calls `/v1/audio/tts` and returns an `audio_url` that can be saved or previewed with `Preview Audio`. ## Kling v3 Turbo notes `kling-v3-turbo` is available in the `Text2Video` and `Image2Video` model dropdowns for the official Kling provider. It uses the newer `/text-to-video/kling-3.0-turbo`, `/image-to-video/kling-3.0-turbo`, and `/tasks` API shape with static Bearer-token auth. The node keeps the existing front-end `mode` values for workflow compatibility: - `std` sends `settings.resolution=720p` - `pro` sends `settings.resolution=1080p` - `4k` is accepted but also sends `settings.resolution=1080p`, because the v3 Turbo API currently documents only `720p` and `1080p` Use `duration` values from `3` through `15`. For multi-shot v3 Turbo prompts, write the shot structure directly in the prompt text; the older `shot_type=intelligence`, separate `negative_prompt`, `cfg_scale`, `camera_control`, `sound`, `voice_list`, `image_list`, `element_list`, and `reference_video` controls are not sent for this model. ## Examples Example workflows and small Python snippets live in [examples/README.md](./examples/README.md). The workflow JSON files no longer depend on a front-end `Client` node. Prepare `config.local.json` first, then import the workflow you want to run. ## Official references - [Kling new-system API documentation](https://docs.qingque.cn/d/home/eZQAyImcbaS0fz-8ANjXvU5ed?identityId=2E1MlYrrPk4) - [Kling TTS API documentation](https://klingai.com/document-api/apiReference/model/TTS) - [Kling custom voice API documentation](https://klingai.com/document-api/apiReference/model/customVoices) - [Kling advanced lip-sync API documentation](https://klingai.com/document-api/api/video/lip-sync) - [Kling Avatar API documentation](https://klingai.com/document-api/api/video/avatar) - [Kling 3.0 custom voice documentation](https://klingai.com/document-api/api/video/3-0-omni/voice-customization) - [Kling 3.0 Turbo text-to-video documentation](https://klingai.com/document-api/api/video/3-0-turbo/text-to-video) - [Kling 3.0 series capability map](https://docs.qingque.cn/d/home/eZQCedMeoI1MTquS1SFRihz4S?identityId=1oEFzU43FYK) - [Kling V2.6 API documentation](https://docs.qingque.cn/d/home/eZQB6Bbl5WgW8eIVN--duPVl1?identityId=1oEFzU43FYK) - [Kling pricing](https://klingai.com/api/pricing) ## Notes The nodes log `final_unit_deduction` when the API returns billing information. This is useful when checking the real unit cost of newer Kling endpoints and workflows.

Name	Type	Description
element_id	STRING	—
request_id	STRING	—

Comfyui-Kling-Wrapper Advanced Element Delete

Inputs (1)

Outputs (2)