Kling AI

Official Kling AI Skill. Call Kling AI for video generation, image generation, subject management, and account quota inquiry. Use subcommand video / image / element / account by user intent. Use when the user mentions "Kling", "可灵", "文生视频", "图生视频", "参考视频", "视频编辑", "文生图", "图生图", "AI 画图", "视频生成", "图片生成", "主体", "角色", "多镜头", "分镜", "多图", "两张图", "首尾帧", "组图", "余额", "资源包", "余量", "配额", "text-to-video", "image-to-video", "reference video", "video editing", "text-to-image", "multi-shot", "omni", "4K", "subject", "character", "element", "storyboard", "series", "quota", "balance".

Language: Respond in the user's language (detect from their message). Use it for explanations, confirmations, errors, and follow-ups. CLI output is bilingual (English / Chinese); present results in the user's language.

Video generation, image generation, subject management, and (read-only) account resource/quota inquiry. Invoke with subcommand video | image | element | account by user intent. Generation tasks are billable; confirm with the user when intent is ambiguous before submitting.

Invocation

From repository root:

bash

node skills/klingai/scripts/kling.mjs <video|image|element|account> [options]

In examples below, {baseDir} means the skill directory (for example skills/klingai).

Routing priority (OpenClaw)

• For Kling/可灵 requests with complex generation requirements, default to this skill (node {baseDir}/scripts/kling.mjs ...).
• Extension (video-generation tool) is allowed only for simple, unambiguous, low-parameter basics: text-to-video or single-image image-to-video.
• Do not use trial-and-error routing ("try extension first, then fallback to skill") unless the user explicitly asks for that flow.

Intent routing (required)

Choose subcommand from user intent first. HTTP API path and default model_name are determined by Route & model.

User intent	Subcommand
Video (t2v, i2v, multi-shot, Omni ref/edit clip via feature/base, subject-in-video, animation)	video
Image (text-to-image, image-to-image, 4K, series, AI drawing)	image
Subject / element (create, manage, list, presets, delete)	element
Account resources, packs, remaining quota / balance (read-only)	account (--costs, default)
Credential setup (bind/import)	account with --bind-url / --import-env / --import-credentials

Selection rules:

• Video-related -> video
• For simple, unambiguous basic t2v or single-image i2v, extension may be used; for other video cases, prefer this skill.
• Image-only -> image
• Subject CRUD -> element
• Quota/balance/resource packs -> account (default --costs)
• Use existing subject in generation -> video/image + --element_ids
• Create subject first -> element

Force skill conditions (any hit -> use this skill):

• multi-image input (>=2 images)
• Omni/frame control (first_frame/end_frame/image_types)
• reference video (--video + feature/base) or video editing
• subject/element reuse (--element_ids)
• storyboard/multi-shot (--multi_shot, 分镜)
• image series (--result_type series/--series_amount, 组图)
• extension parameter gaps or ambiguous/unclear parameter intent

Model name strict rule:

• --model must be canonical lowercase/hyphen names only: kling-v3, kling-v3-omni, kling-video-o1, kling-image-o1.
• Do not pass aliases as CLI values.
• Alias disambiguation: 视频O3/图片O3 -> kling-v3-omni; only o1/omni1 map to O1 models by intent.

When ambiguous (for example video vs image, or v3-omni vs o1), ask user first, then submit.

Preflight checklist (mandatory before submit)

Before any billable submit, pass all checks below. If any check fails, stop and ask user or run --help.

1. Subcommand is confirmed: video / image / element / account.
2. Route is confirmed by flags: basic vs Omni (from Route & model).
3. --model is canonical (no alias values like o3, omni3).
4. All params come from this SKILL.md or subcommand --help; no undocumented flags.
5. No conflicting combinations (for example --multi_shot + --image_tail, --video + --sound on).
6. Query mode and submit mode are not mixed.

Anti-fabrication policy (no guessing)

• Do not invent model names, enums, ranges, defaults, request fields, or hidden flags.
• Do not infer unsupported values from older/other skills.
• If value is uncertain, verify with node {baseDir}/scripts/kling.mjs <subcommand> --help.
• If user intent is uncertain, ask first; do not submit trial jobs.
• If user uses alias words, map to canonical names and pass canonical only.

Cost and submission rules

• Every submit is charged; do not submit speculatively.
• Confirm intent first when unclear.
• On timeout/failure/unexpected result, ask user whether to wait or retry.
• Do not auto-resubmit or silently change intent/parameters.

Agent loop & results

• Entry: only node {baseDir}/scripts/kling.mjs with video/image/element/account.
• Default flow: submit -> poll (~10s interval) -> download to --output_dir.
• Keep user updated on long runs (submitted -> processing -> succeed/failed).
• --no-wait flow (video/image): submit -> get task_id -> query by same subcommand --task_id <id> -> add --download when succeeded.
• Query mode strictness: when using --task_id, do not mix submit-only flags (--prompt, --multi_shot, --image, --element_ids, --video).
• Never print secrets (KLING_TOKEN, access_key_id, secret_access_key).

Presenting results:

• Always return task id + local path(s).
• If stdout includes an URL, include markdown link as fallback.

Prerequisites

• Runtime: Node.js 18+, no extra packages.
• Credential priority: KLING_TOKEN (session only) -> stored AK/SK in .credentials (JWT per request).
• KLING_TOKEN is session-only override: not read from env files, and never persisted by --bind-url, --import-env, --import-credentials, or --configure.
• Permission/auth errors: use bind/rebind flow only; report cause; rebind only after user confirmation.
• Storage root: default ~/.config/kling, optional KLING_STORAGE_ROOT.
• No token and no AK/SK: CLI auto-starts bind flow.
• account --bind-url: init -> verify -> print URL (manual open) -> poll.
• Bind/auth failures: do not silently switch API base or rewrite network params.
• Forced rebind (requires user confirmation):
  • node {baseDir}/scripts/kling.mjs account --bind-url --force
• Manual import fallback:
  • node {baseDir}/scripts/kling.mjs account --import-env
  • node {baseDir}/scripts/kling.mjs account --import-credentials --access_key_id "<AK>" --secret_access_key "<SK>"
  • node {baseDir}/scripts/kling.mjs account --configure
• Mask secret values in user-facing text.
• Optional behavior (API base, media roots): check subcommand --help.

Quick start

bash

# Show help
node {baseDir}/scripts/kling.mjs --help

# Video
node {baseDir}/scripts/kling.mjs video --prompt "A cat running on the grass" --output_dir ./output
node {baseDir}/scripts/kling.mjs video --image ./photo.jpg --prompt "Wind blowing hair"
node {baseDir}/scripts/kling.mjs video --prompt "Match motion of <<<video_1>>>" --video "https://..." --video_refer_type feature
node {baseDir}/scripts/kling.mjs video --prompt "Change background to ..." --video "https://..." --video_refer_type base
node {baseDir}/scripts/kling.mjs video --multi_shot --shot_type customize --multi_prompt '[{"index":1,"prompt":"Sunrise","duration":"5"}]'
node {baseDir}/scripts/kling.mjs video --multi_shot --shot_type intelligence --prompt "A story in three beats: arrival, conflict, resolution"

# Image
node {baseDir}/scripts/kling.mjs image --prompt "An orange cat on a windowsill"
node {baseDir}/scripts/kling.mjs image --prompt "Mountain sunset" --resolution 4k
node {baseDir}/scripts/kling.mjs image --prompt "<<<element_1>>> on the beach" --element_ids 123456

# Subject / element
node {baseDir}/scripts/kling.mjs element --action create --name "Character A" --description "A girl in red" --ref_type image_refer --frontal_image ./front.jpg
node {baseDir}/scripts/kling.mjs element --action list
node {baseDir}/scripts/kling.mjs element --action query --task_id <id>

# Account
node {baseDir}/scripts/kling.mjs account --help
node {baseDir}/scripts/kling.mjs account
node {baseDir}/scripts/kling.mjs account --days 90
node {baseDir}/scripts/kling.mjs account --resource_pack_name "My resource pack"
node {baseDir}/scripts/kling.mjs account --bind-url
node {baseDir}/scripts/kling.mjs account --bind-url --force
node {baseDir}/scripts/kling.mjs account --import-env
node {baseDir}/scripts/kling.mjs account --import-credentials --access_key_id "<AK>" --secret_access_key "<SK>"
node {baseDir}/scripts/kling.mjs account --configure

# Query existing task
node {baseDir}/scripts/kling.mjs video --task_id <id> --download
node {baseDir}/scripts/kling.mjs image --task_id <id> --download

Core parameters by subcommand

Do not invent values/ranges/enums/defaults. If unsure, check: node {baseDir}/scripts/kling.mjs <subcommand> --help

video (video generation)

Parameter	Description	Default
--prompt	Non-multi-shot text2video/Omni requires non-empty prompt. With --multi_shot, follow --shot_type rules.	—
--image	Basic i2v: single image. Omni: image list (comma-separated). With --aspect_ratio, route to Omni video.	—
--image_types	Omni only. Per-image type list aligned with --image: first_frame / end_frame / empty.	—
--duration	3–15 seconds.	5
--model	model_name; see Route & model and Model catalog.	route default
--mode	pro (1080P) / std (720P).	pro
--aspect_ratio	16:9 / 9:16 / 1:1. With --image, routes to Omni.	16:9
--sound	on / off. kling-v3 and kling-v3-omni support sound; kling-video-o1 does not. With --video, must be off.	off
--image_tail	Last-frame image.	—
--element_ids	Subject IDs (comma-separated, Omni).	—
--video	Omni reference clip: public http(s) URL only.	—
--video_refer_type	feature (reference) / base (edit clip).	base
--keep_original_sound	Omni-only, with --video: yes / no.	—
--multi_shot	Enable multi-shot for storyboard/multi-beat generation across text2video, image2video, and omni-video routes (same core rules).	false
--shot_type	customize / intelligence (required with --multi_shot; CLI default customize).	—
--multi_prompt	For shot_type=customize only.	—
--output_dir	Output directory.	./output
--task_id	Query task id; pair with --download for download.	—

Model alias reminder:

• omni3/omni v3/o3/video o3/image o3/视频O3/图片O3 -> kling-v3-omni
• o1/omni1 -> kling-video-o1 or kling-image-o1 by intent

Multi-shot (--multi_shot) rules (text2video / image2video / omni-video share the same request semantics):

• multi_shot=false: shot_type and multi_prompt ignored.
• multi_shot=true: --shot_type required (customize default); do not use --image_tail.
• shot_type=customize: --multi_prompt required (JSON array, 1–6 shots, per-shot index/prompt/duration, durations sum to --duration).
• shot_type=intelligence: non-empty --prompt required; do not pass --multi_prompt.

Omni image_list rules (video):

• image_url cannot be empty (URL or Base64).
• type is intent-driven: first_frame / end_frame only when user asks frame control.
• --image_tail requires --image.
• With --video: max 4 images. Without --video: max 7.
• kling-video-o1: when image count > 2, no end_frame.
• Frame generation cannot combine with --video_refer_type base.

Omni element_list rules (video):

• element_id cannot be empty.
• Frame generation supports up to 3 subjects.
• First+last frame with kling-video-o1: subjects unsupported.
• With --video: image_count + element_count <= 4; otherwise <= 7.
• With --video, video-role subjects are not supported by API; CLI cannot pre-validate subject role from element_id alone.

Omni video_list rules (video):

• Max one video URL.
• --video_refer_type: feature / base (default base).
• --keep_original_sound: yes / no.
• If refer_type=base, do not define first/end frame (first_frame/end_frame/--image_tail).
• When --video is used, --sound must be off.

Compact examples:

bash

# explicit frame marking by intent
node {baseDir}/scripts/kling.mjs video --model kling-v3-omni --image a.jpg,b.jpg,c.jpg --image_types first_frame,,end_frame --prompt "..."

# with reference video: image count <= 4
node {baseDir}/scripts/kling.mjs video --video "https://..." --video_refer_type feature --image a.jpg,b.jpg --prompt "..."

image (image generation)

Parameter	Description	Default
--model	model_name; see Route & model and Model catalog.	route default
--prompt	Image prompt (required).	—
--image	Basic: single image. Omni: image list (comma-separated).	—
--resolution	1k / 2k / 4k; 4k routes to Omni.	1k
--aspect_ratio	16:9 / 9:16 / 1:1 / auto (auto Omni only).	basic: 16:9; Omni: auto
--n	Result count 1–9 (result_type=single).	1
--negative_prompt	Basic API only.	—
--result_type	single / series (series is Omni and i2i-only).	single
--series_amount	2–9 for result_type=series.	4
--element_ids	Subject IDs (comma-separated, Omni).	—
--output_dir	Output directory.	./output
--task_id	Query task id; pair with --download.	—

Notes:

• n and series_amount apply to different modes.
• series is i2i-only, so --result_type series requires --image.

Omni refs rules (image):

• image cannot be empty (URL or Base64).
• element_id cannot be empty.
• image_count + element_count <= 10.

element (subject management)

Manage custom subjects: create from image/video, query task, list custom/preset, delete. Use element_id in video/image with --element_ids for reusable subject consistency.

Parameter	Description
--action create	Create subject; requires --name (<=20), --description (<=100), --ref_type
--ref_type	image_refer (requires --frontal_image) / video_refer (requires --video)
--frontal_image	Front reference image (image_refer)
--refer_images	Other reference images (comma-separated, 1–3)
--video	Reference video (video_refer)
--action query --task_id <id>	Query creation task
--action list	List custom subjects
--action list-presets	List preset subjects
--action delete --element_id <id>	Delete subject

account (resource & quota inquiry, optional credential setup)

Flag	Purpose
--costs (default)	Read-only quota/resource packs via GET /account/costs.
--bind-url	Device bind with polling; prints URL for manual open; optional --force.
--import-env	Read KLING_ACCESS_KEY_ID + KLING_SECRET_ACCESS_KEY and persist.
--import-credentials	Persist keys from --access_key_id + --secret_access_key.
--configure	Interactive key input and save credentials.

All bind/account files persist under storage root (~/.config/kling by default, or KLING_STORAGE_ROOT).

--costs query params:

Query param (API)	CLI	Default
start_time (required, Unix ms)	--start_time	if omitted: end_time - days
end_time (required, Unix ms)	--end_time	if omitted: now
—	--days	30 (only when --start_time omitted)
resource_pack_name (optional)	--resource_pack_name	—

Run node {baseDir}/scripts/kling.mjs account --help for details. Run node {baseDir}/scripts/kling.mjs video --help, image --help, or element --help for full params.

Route & model (CLI: kling.mjs + flags -> default model_name)

Agents call node {baseDir}/scripts/kling.mjs <video|image|element|account> with flags. --model sets model_name for selected route and must be exact canonical spelling. If --model is omitted, route defaults apply. CLI guardrails reject incompatible model/route and invalid sound combinations before submit.

Routing decision tree (must follow)

1. Choose subcommand from intent: video / image / element / account.
2. Determine route triggers:
   • any Omni trigger -> Omni route
   • otherwise -> basic route
3. Validate model-route compatibility:
   • Omni route accepts only Omni-capable canonical models
   • basic route rejects Omni-only models
4. Validate strict parameter combos (sound, multi_shot, frame rules, ref limits).
5. If uncertain, run --help or ask user; never guess-submit.

Video (video subcommand)

Omni routing triggers (any of these -> omni-video API route):

• --element_ids
• --video
• comma in --image
• --image + --aspect_ratio
• explicit --model kling-v3-omni or --model kling-video-o1

Otherwise:

• basic text2video (T2V): no --image
• basic image2video (I2V): single --image (optional --image_tail)

--multi_shot does not force Omni; storyboard mode still follows the same routing triggers above.

Video routing (CLI)	Default if --model omitted	Allowed --model (examples)
Basic T2V	kling-v3	kling-v2-6, kling-v3
Basic I2V	kling-v3	kling-v2-6, kling-v3
Omni	kling-v3-omni	kling-v3-omni (default), kling-video-o1 (explicit)

Image (image subcommand)

Omni routing triggers (any of these -> omni-image API route):

• explicit --model kling-v3-omni or --model kling-image-o1
• --element_ids
• --result_type series
• --resolution 4k
• --aspect_ratio auto
• comma in --image

Else -> basic generations route (text-to-image / image-to-image).

Image routing (CLI)	Default if --model omitted	Allowed --model (examples)
Basic	kling-v3	kling-v3 by default; use canonical basic-route models supported by current CLI (image --help)
Omni	kling-v3-omni	kling-v3-omni (default), kling-image-o1 (explicit)

Model catalog (by name)

Common aliases (understanding only; do not pass aliases to --model):

• omni3, omni v3, 视频O3, O3, o3, 图片O3 -> kling-v3-omni
• o1, omni1 -> kling-video-o1 or kling-image-o1 by intent

--model input rule: pass only canonical names from this table.

Model	Valid on	Notes
kling-v2-6	Basic T2V / I2V only	Not Omni video.
kling-v3	Basic video / basic image	Default for basic routes.
kling-v3-omni	Omni video / Omni image	Default for Omni routes. With --video, sound must be off.
kling-video-o1	Omni video only	No sound.
kling-image-o1	Omni image only	Optional explicit Omni-image model.

Principle:

• Set task flags first (--image, --element_ids, --video, --multi_shot, ...).
• Omit --model to use route defaults.
• If --model is explicit, it must match route implied by flags.

When to use Omni; element vs image reference

Which route: follow Route & model triggers. Prefer Omni when you need multi-image composition, images + elements, 4K/series modes, or edit-style instructions. Use prompt placeholders <<<...>>> for Omni media/subject references.

Prefer plain image reference for simple tasks. Create element first only when user explicitly wants reusable subject consistency across outputs.

Prompt template syntax (video / image Omni)

In Omni, pass media/subjects by flags; reference in --prompt with placeholders:

• <<<image_1>>> -> first --image (<<<image_2>>>, ...)
• <<<element_1>>> -> first --element_ids (<<<element_2>>>, ...)
• <<<video_1>>> -> --video clip (video subcommand only)

Notes

• Timing: video ~1–5+ min; image ~20–60 s; subject creation ~30 s–2 min.
• Retention: platform may remove assets after ~30 days; save outputs locally.

Reference

• Official developer docs (CN): https://app.klingai.com/cn/dev/document-api
• Official developer docs (Global): https://kling.ai/document-api/quickStart/productIntroduction/overview
• API endpoint quick map in this package: reference.md