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

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

Python dependencies are listed in requirements.txt.

Installation

Manual installation

1. Open your ComfyUI/custom_nodes directory.

2. Clone this repository:

   git clone https://github.com/magicwang1111/Comfyui-Kling-Wrapper.git
   

3. Install dependencies:

   Windows (portable ComfyUI):

   python -m pip install -r ComfyUI\custom_nodes\Comfyui-Kling-Wrapper\requirements.txt
   

   Linux or macOS:

   cd Comfyui-Kling-Wrapper
   pip install -r requirements.txt
   

4. Create config.local.json in the repository root.

   You can copy config.example.json and fill in your Kling credentials:

   {
     "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 <api_key> 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 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 <<<voice_1>>> 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:

[{"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 <<<voice_1>>> and <<<voice_2>>>. 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.

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
• Kling TTS API documentation
• Kling custom voice API documentation
• Kling advanced lip-sync API documentation
• Kling Avatar API documentation
• Kling 3.0 custom voice documentation
• Kling 3.0 Turbo text-to-video documentation
• Kling 3.0 series capability map
• Kling V2.6 API documentation
• Kling 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.