\r \r

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.\r \r

Kling AI\r

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

Invocation\r

\r From repository root:\r \r

node skills/klingai/scripts/kling.mjs \x3Cvideo|image|element|account> [options]\r
```\r
\r
In examples below, `{baseDir}` means the skill directory (for example `skills/klingai`).\r
\r
## Routing priority (OpenClaw)\r
\r
- For Kling/可灵 requests with complex generation requirements, default to this skill (`node {baseDir}/scripts/kling.mjs ...`).\r
- Extension (video-generation tool) is allowed only for simple, unambiguous, low-parameter basics: text-to-video or single-image image-to-video.\r
- Do not use trial-and-error routing ("try extension first, then fallback to skill") unless the user explicitly asks for that flow.\r
\r
## Intent routing (required)\r
\r
Choose subcommand from user intent first. HTTP API path and default `model_name` are determined by **Route & model**.\r
\r
| User intent | Subcommand |\r
| --- | --- |\r
| Video (t2v, i2v, multi-shot, Omni ref/edit clip via `feature`/`base`, subject-in-video, animation) | `video` |\r
| Image (text-to-image, image-to-image, 4K, series, AI drawing) | `image` |\r
| Subject / element (create, manage, list, presets, delete) | `element` |\r
| Account resources, packs, remaining quota / balance (read-only) | `account` (`--costs`, default) |\r
| Credential setup (bind/import) | `account` with `--bind-url` / `--import-env` / `--import-credentials` |\r
\r
Selection rules:\r
- Video-related -> `video`\r
- For simple, unambiguous basic t2v or single-image i2v, extension may be used; for other video cases, prefer this skill.\r
- Image-only -> `image`\r
- Subject CRUD -> `element`\r
- Quota/balance/resource packs -> `account` (default `--costs`)\r
- Use existing subject in generation -> `video`/`image` + `--element_ids`\r
- Create subject first -> `element`\r
\r
Force skill conditions (any hit -> use this skill):\r
- multi-image input (>=2 images)\r
- Omni/frame control (`first_frame`/`end_frame`/`image_types`)\r
- reference video (`--video` + `feature`/`base`) or video editing\r
- subject/element reuse (`--element_ids`)\r
- storyboard/multi-shot (`--multi_shot`, 分镜)\r
- image series (`--result_type series`/`--series_amount`, 组图)\r
- extension parameter gaps or ambiguous/unclear parameter intent\r
\r
Model name strict rule:\r
- `--model` must be canonical lowercase/hyphen names only: `kling-v3`, `kling-v3-omni`, `kling-video-o1`, `kling-image-o1`.\r
- Do not pass aliases as CLI values.\r
- Alias disambiguation: `视频O3`/`图片O3` -> `kling-v3-omni`; only `o1`/`omni1` map to O1 models by intent.\r
\r
When ambiguous (for example video vs image, or v3-omni vs o1), ask user first, then submit.\r
\r
## Preflight checklist (mandatory before submit)\r
\r
Before any billable submit, pass all checks below. If any check fails, stop and ask user or run `--help`.\r
\r
1. Subcommand is confirmed: `video` / `image` / `element` / `account`.\r
2. Route is confirmed by flags: basic vs Omni (from **Route & model**).\r
3. `--model` is canonical (no alias values like `o3`, `omni3`).\r
4. All params come from this SKILL.md or subcommand `--help`; no undocumented flags.\r
5. No conflicting combinations (for example `--multi_shot` + `--image_tail`, `--video` + `--sound on`).\r
6. Query mode and submit mode are not mixed.\r
\r
## Anti-fabrication policy (no guessing)\r
\r
- Do not invent model names, enums, ranges, defaults, request fields, or hidden flags.\r
- Do not infer unsupported values from older/other skills.\r
- If value is uncertain, verify with `node {baseDir}/scripts/kling.mjs \x3Csubcommand> --help`.\r
- If user intent is uncertain, ask first; do not submit trial jobs.\r
- If user uses alias words, map to canonical names and pass canonical only.\r
\r
## Cost and submission rules\r
\r
- Every submit is charged; do not submit speculatively.\r
- Confirm intent first when unclear.\r
- On timeout/failure/unexpected result, ask user whether to wait or retry.\r
- Do not auto-resubmit or silently change intent/parameters.\r
\r
## Agent loop & results\r
\r
- Entry: only `node {baseDir}/scripts/kling.mjs` with `video`/`image`/`element`/`account`.\r
- Default flow: submit -> poll (~10s interval) -> download to `--output_dir`.\r
- Keep user updated on long runs (`submitted -> processing -> succeed/failed`).\r
- `--no-wait` flow (video/image): submit -> get `task_id` -> query by same subcommand `--task_id \x3Cid>` -> add `--download` when succeeded.\r
- Query mode strictness: when using `--task_id`, do not mix submit-only flags (`--prompt`, `--multi_shot`, `--image`, `--element_ids`, `--video`).\r
- Never print secrets (`KLING_TOKEN`, `access_key_id`, `secret_access_key`).\r
\r
Presenting results:\r
- Always return task id + local path(s).\r
- If stdout includes an URL, include markdown link as fallback.\r
\r
## Prerequisites\r
\r
- Runtime: Node.js 18+, no extra packages.\r
- Credential priority: `KLING_TOKEN` (session only) -> stored AK/SK in `.credentials` (JWT per request).\r
- `KLING_TOKEN` is session-only override: not read from env files, and never persisted by `--bind-url`, `--import-env`, `--import-credentials`, or `--configure`.\r
- Permission/auth errors: use bind/rebind flow only; report cause; rebind only after user confirmation.\r
- Storage root: default `~/.config/kling`, optional `KLING_STORAGE_ROOT`.\r
- No token and no AK/SK: CLI auto-starts bind flow.\r
- `account --bind-url`: init -> verify -> print URL (manual open) -> poll.\r
- Bind/auth failures: do not silently switch API base or rewrite network params.\r
- Forced rebind (requires user confirmation):\r
  - `node {baseDir}/scripts/kling.mjs account --bind-url --force`\r
- Manual import fallback:\r
  - `node {baseDir}/scripts/kling.mjs account --import-env`\r
  - `node {baseDir}/scripts/kling.mjs account --import-credentials --access_key_id "\x3CAK>" --secret_access_key "\x3CSK>"`\r
  - `node {baseDir}/scripts/kling.mjs account --configure`\r
- Mask secret values in user-facing text.\r
- Optional behavior (API base, media roots): check subcommand `--help`.\r
\r
## Quick start\r
\r
```bash\r
# Show help\r
node {baseDir}/scripts/kling.mjs --help\r
\r
# Video\r
node {baseDir}/scripts/kling.mjs video --prompt "A cat running on the grass" --output_dir ./output\r
node {baseDir}/scripts/kling.mjs video --image ./photo.jpg --prompt "Wind blowing hair"\r
node {baseDir}/scripts/kling.mjs video --prompt "Match motion of \x3C\x3C\x3Cvideo_1>>>" --video "https://..." --video_refer_type feature\r
node {baseDir}/scripts/kling.mjs video --prompt "Change background to ..." --video "https://..." --video_refer_type base\r
node {baseDir}/scripts/kling.mjs video --multi_shot --shot_type customize --multi_prompt '[{"index":1,"prompt":"Sunrise","duration":"5"}]'\r
node {baseDir}/scripts/kling.mjs video --multi_shot --shot_type intelligence --prompt "A story in three beats: arrival, conflict, resolution"\r
\r
# Image\r
node {baseDir}/scripts/kling.mjs image --prompt "An orange cat on a windowsill"\r
node {baseDir}/scripts/kling.mjs image --prompt "Mountain sunset" --resolution 4k\r
node {baseDir}/scripts/kling.mjs image --prompt "\x3C\x3C\x3Celement_1>>> on the beach" --element_ids 123456\r
\r
# Subject / element\r
node {baseDir}/scripts/kling.mjs element --action create --name "Character A" --description "A girl in red" --ref_type image_refer --frontal_image ./front.jpg\r
node {baseDir}/scripts/kling.mjs element --action list\r
node {baseDir}/scripts/kling.mjs element --action query --task_id \x3Cid>\r
\r
# Account\r
node {baseDir}/scripts/kling.mjs account --help\r
node {baseDir}/scripts/kling.mjs account\r
node {baseDir}/scripts/kling.mjs account --days 90\r
node {baseDir}/scripts/kling.mjs account --resource_pack_name "My resource pack"\r
node {baseDir}/scripts/kling.mjs account --bind-url\r
node {baseDir}/scripts/kling.mjs account --bind-url --force\r
node {baseDir}/scripts/kling.mjs account --import-env\r
node {baseDir}/scripts/kling.mjs account --import-credentials --access_key_id "\x3CAK>" --secret_access_key "\x3CSK>"\r
node {baseDir}/scripts/kling.mjs account --configure\r
\r
# Query existing task\r
node {baseDir}/scripts/kling.mjs video --task_id \x3Cid> --download\r
node {baseDir}/scripts/kling.mjs image --task_id \x3Cid> --download\r
```\r
\r
## Core parameters by subcommand\r
\r
Do not invent values/ranges/enums/defaults. If unsure, check:\r
`node {baseDir}/scripts/kling.mjs \x3Csubcommand> --help`\r
\r
### video (video generation)\r
\r
| Parameter | Description | Default |\r
| --- | --- | --- |\r
| `--prompt` | Non-multi-shot text2video/Omni requires non-empty prompt. With `--multi_shot`, follow `--shot_type` rules. | — |\r
| `--image` | Basic i2v: single image. Omni: image list (comma-separated). With `--aspect_ratio`, route to Omni video. | — |\r
| `--image_types` | Omni only. Per-image type list aligned with `--image`: `first_frame` / `end_frame` / empty. | — |\r
| `--duration` | 3–15 seconds. | 5 |\r
| `--model` | `model_name`; see **Route & model** and **Model catalog**. | route default |\r
| `--mode` | `pro` (1080P) / `std` (720P). | pro |\r
| `--aspect_ratio` | `16:9` / `9:16` / `1:1`. With `--image`, routes to Omni. | 16:9 |\r
| `--sound` | `on` / `off`. `kling-v3` and `kling-v3-omni` support sound; `kling-video-o1` does not. With `--video`, must be `off`. | off |\r
| `--image_tail` | Last-frame image. | — |\r
| `--element_ids` | Subject IDs (comma-separated, Omni). | — |\r
| `--video` | Omni reference clip: public http(s) URL only. | — |\r
| `--video_refer_type` | `feature` (reference) / `base` (edit clip). | base |\r
| `--keep_original_sound` | Omni-only, with `--video`: `yes` / `no`. | — |\r
| `--multi_shot` | Enable multi-shot for storyboard/multi-beat generation across text2video, image2video, and omni-video routes (same core rules). | false |\r
| `--shot_type` | `customize` / `intelligence` (required with `--multi_shot`; CLI default `customize`). | — |\r
| `--multi_prompt` | For `shot_type=customize` only. | — |\r
| `--output_dir` | Output directory. | `./output` |\r
| `--task_id` | Query task id; pair with `--download` for download. | — |\r
\r
Model alias reminder:\r
- `omni3`/`omni v3`/`o3`/`video o3`/`image o3`/`视频O3`/`图片O3` -> `kling-v3-omni`\r
- `o1`/`omni1` -> `kling-video-o1` or `kling-image-o1` by intent\r
\r
Multi-shot (`--multi_shot`) rules (text2video / image2video / omni-video share the same request semantics):\r
- `multi_shot=false`: `shot_type` and `multi_prompt` ignored.\r
- `multi_shot=true`: `--shot_type` required (`customize` default); do not use `--image_tail`.\r
- `shot_type=customize`: `--multi_prompt` required (JSON array, 1–6 shots, per-shot `index`/`prompt`/`duration`, durations sum to `--duration`).\r
- `shot_type=intelligence`: non-empty `--prompt` required; do not pass `--multi_prompt`.\r
\r
Omni `image_list` rules (video):\r
- `image_url` cannot be empty (URL or Base64).\r
- `type` is intent-driven: `first_frame` / `end_frame` only when user asks frame control.\r
- `--image_tail` requires `--image`.\r
- With `--video`: max 4 images. Without `--video`: max 7.\r
- `kling-video-o1`: when image count > 2, no `end_frame`.\r
- Frame generation cannot combine with `--video_refer_type base`.\r
\r
Omni `element_list` rules (video):\r
- `element_id` cannot be empty.\r
- Frame generation supports up to 3 subjects.\r
- First+last frame with `kling-video-o1`: subjects unsupported.\r
- With `--video`: `image_count + element_count \x3C= 4`; otherwise `\x3C= 7`.\r
- With `--video`, video-role subjects are not supported by API; CLI cannot pre-validate subject role from `element_id` alone.\r
\r
Omni `video_list` rules (video):\r
- Max one video URL.\r
- `--video_refer_type`: `feature` / `base` (default `base`).\r
- `--keep_original_sound`: `yes` / `no`.\r
- If `refer_type=base`, do not define first/end frame (`first_frame`/`end_frame`/`--image_tail`).\r
- When `--video` is used, `--sound` must be `off`.\r
\r
Compact examples:\r
\r
```bash\r
# explicit frame marking by intent\r
node {baseDir}/scripts/kling.mjs video --model kling-v3-omni --image a.jpg,b.jpg,c.jpg --image_types first_frame,,end_frame --prompt "..."\r
\r
# with reference video: image count \x3C= 4\r
node {baseDir}/scripts/kling.mjs video --video "https://..." --video_refer_type feature --image a.jpg,b.jpg --prompt "..."\r
```\r
\r
### image (image generation)\r
\r
| Parameter | Description | Default |\r
| --- | --- | --- |\r
| `--model` | `model_name`; see **Route & model** and **Model catalog**. | route default |\r
| `--prompt` | Image prompt (required). | — |\r
| `--image` | Basic: single image. Omni: image list (comma-separated). | — |\r
| `--resolution` | `1k` / `2k` / `4k`; `4k` routes to Omni. | 1k |\r
| `--aspect_ratio` | `16:9` / `9:16` / `1:1` / `auto` (`auto` Omni only). | basic: `16:9`; Omni: `auto` |\r
| `--n` | Result count 1–9 (`result_type=single`). | 1 |\r
| `--negative_prompt` | Basic API only. | — |\r
| `--result_type` | `single` / `series` (`series` is Omni and i2i-only). | single |\r
| `--series_amount` | 2–9 for `result_type=series`. | 4 |\r
| `--element_ids` | Subject IDs (comma-separated, Omni). | — |\r
| `--output_dir` | Output directory. | `./output` |\r
| `--task_id` | Query task id; pair with `--download`. | — |\r
\r
Notes:\r
- `n` and `series_amount` apply to different modes.\r
- `series` is i2i-only, so `--result_type series` requires `--image`.\r
\r
Omni refs rules (image):\r
- `image` cannot be empty (URL or Base64).\r
- `element_id` cannot be empty.\r
- `image_count + element_count \x3C= 10`.\r
\r
### element (subject management)\r
\r
Manage custom subjects: create from image/video, query task, list custom/preset, delete.\r
Use `element_id` in `video`/`image` with `--element_ids` for reusable subject consistency.\r
\r
| Parameter | Description |\r
| --- | --- |\r
| `--action create` | Create subject; requires `--name` (\x3C=20), `--description` (\x3C=100), `--ref_type` |\r
| `--ref_type` | `image_refer` (requires `--frontal_image`) / `video_refer` (requires `--video`) |\r
| `--frontal_image` | Front reference image (`image_refer`) |\r
| `--refer_images` | Other reference images (comma-separated, 1–3) |\r
| `--video` | Reference video (`video_refer`) |\r
| `--action query --task_id \x3Cid>` | Query creation task |\r
| `--action list` | List custom subjects |\r
| `--action list-presets` | List preset subjects |\r
| `--action delete --element_id \x3Cid>` | Delete subject |\r
\r
### account (resource & quota inquiry, optional credential setup)\r
\r
| Flag | Purpose |\r
| --- | --- |\r
| `--costs` (default) | Read-only quota/resource packs via `GET /account/costs`. |\r
| `--bind-url` | Device bind with polling; prints URL for manual open; optional `--force`. |\r
| `--import-env` | Read `KLING_ACCESS_KEY_ID` + `KLING_SECRET_ACCESS_KEY` and persist. |\r
| `--import-credentials` | Persist keys from `--access_key_id` + `--secret_access_key`. |\r
| `--configure` | Interactive key input and save credentials. |\r
\r
All bind/account files persist under storage root (`~/.config/kling` by default, or `KLING_STORAGE_ROOT`).\r
\r
`--costs` query params:\r
\r
| Query param (API) | CLI | Default |\r
| --- | --- | --- |\r
| `start_time` (required, Unix ms) | `--start_time` | if omitted: `end_time - days` |\r
| `end_time` (required, Unix ms) | `--end_time` | if omitted: now |\r
| — | `--days` | 30 (only when `--start_time` omitted) |\r
| `resource_pack_name` (optional) | `--resource_pack_name` | — |\r
\r
Run `node {baseDir}/scripts/kling.mjs account --help` for details.\r
Run `node {baseDir}/scripts/kling.mjs video --help`, `image --help`, or `element --help` for full params.\r
\r
## Route & model (CLI: `kling.mjs` + flags -> default `model_name`)\r
\r
Agents call `node {baseDir}/scripts/kling.mjs \x3Cvideo|image|element|account>` with flags.\r
`--model` sets `model_name` for selected route and must be exact canonical spelling.\r
If `--model` is omitted, route defaults apply.\r
CLI guardrails reject incompatible model/route and invalid `sound` combinations before submit.\r
\r
### Routing decision tree (must follow)\r
\r
1. Choose subcommand from intent: `video` / `image` / `element` / `account`.\r
2. Determine route triggers:\r
   - any Omni trigger -> Omni route\r
   - otherwise -> basic route\r
3. Validate model-route compatibility:\r
   - Omni route accepts only Omni-capable canonical models\r
   - basic route rejects Omni-only models\r
4. Validate strict parameter combos (`sound`, `multi_shot`, frame rules, ref limits).\r
5. If uncertain, run `--help` or ask user; never guess-submit.\r
\r
### Video (`video` subcommand)\r
\r
Omni routing triggers (any of these -> omni-video API route):\r
- `--element_ids`\r
- `--video`\r
- comma in `--image`\r
- `--image` + `--aspect_ratio`\r
- explicit `--model kling-v3-omni` or `--model kling-video-o1`\r
\r
Otherwise:\r
- basic text2video (T2V): no `--image`\r
- basic image2video (I2V): single `--image` (optional `--image_tail`)\r
\r
`--multi_shot` does not force Omni; storyboard mode still follows the same routing triggers above.\r
\r
| Video routing (CLI) | Default if `--model` omitted | Allowed `--model` (examples) |\r
| --- | --- | --- |\r
| Basic T2V | `kling-v3` | `kling-v2-6`, `kling-v3` |\r
| Basic I2V | `kling-v3` | `kling-v2-6`, `kling-v3` |\r
| Omni | `kling-v3-omni` | `kling-v3-omni` (default), `kling-video-o1` (explicit) |\r
\r
### Image (`image` subcommand)\r
\r
Omni routing triggers (any of these -> omni-image API route):\r
- explicit `--model kling-v3-omni` or `--model kling-image-o1`\r
- `--element_ids`\r
- `--result_type series`\r
- `--resolution 4k`\r
- `--aspect_ratio auto`\r
- comma in `--image`\r
\r
Else -> basic generations route (text-to-image / image-to-image).\r
\r
| Image routing (CLI) | Default if `--model` omitted | Allowed `--model` (examples) |\r
| --- | --- | --- |\r
| Basic | `kling-v3` | `kling-v3` by default; use canonical basic-route models supported by current CLI (`image --help`) |\r
| Omni | `kling-v3-omni` | `kling-v3-omni` (default), `kling-image-o1` (explicit) |\r
\r
### Model catalog (by name)\r
\r
Common aliases (understanding only; do not pass aliases to `--model`):\r
- `omni3`, `omni v3`, `视频O3`, `O3`, `o3`, `图片O3` -> `kling-v3-omni`\r
- `o1`, `omni1` -> `kling-video-o1` or `kling-image-o1` by intent\r
\r
`--model` input rule: pass only canonical names from this table.\r
\r
| Model | Valid on | Notes |\r
| --- | --- | --- |\r
| `kling-v2-6` | Basic T2V / I2V only | Not Omni video. |\r
| `kling-v3` | Basic video / basic image | Default for basic routes. |\r
| `kling-v3-omni` | Omni video / Omni image | Default for Omni routes. With `--video`, `sound` must be `off`. |\r
| `kling-video-o1` | Omni video only | No `sound`. |\r
| `kling-image-o1` | Omni image only | Optional explicit Omni-image model. |\r
\r
Principle:\r
- Set task flags first (`--image`, `--element_ids`, `--video`, `--multi_shot`, ...).\r
- Omit `--model` to use route defaults.\r
- If `--model` is explicit, it must match route implied by flags.\r
\r
## When to use Omni; element vs image reference\r
\r
Which route: follow **Route & model** triggers.\r
Prefer Omni when you need multi-image composition, images + elements, 4K/series modes, or edit-style instructions.\r
Use prompt placeholders `\x3C\x3C\x3C...>>>` for Omni media/subject references.\r
\r
Prefer plain image reference for simple tasks.\r
Create element first only when user explicitly wants reusable subject consistency across outputs.\r
\r
## Prompt template syntax (video / image Omni)\r
\r
In Omni, pass media/subjects by flags; reference in `--prompt` with placeholders:\r
- `\x3C\x3C\x3Cimage_1>>>` -> first `--image` (`\x3C\x3C\x3Cimage_2>>>`, ...)\r
- `\x3C\x3C\x3Celement_1>>>` -> first `--element_ids` (`\x3C\x3C\x3Celement_2>>>`, ...)\r
- `\x3C\x3C\x3Cvideo_1>>>` -> `--video` clip (`video` subcommand only)\r
\r
## Notes\r
\r
- Timing: video ~1–5+ min; image ~20–60 s; subject creation ~30 s–2 min.\r
- Retention: platform may remove assets after ~30 days; save outputs locally.\r
\r
## Reference\r
\r
- Official developer docs (CN): https://app.klingai.com/cn/dev/document-api\r
- Official developer docs (Global): https://kling.ai/document-api/quickStart/productIntroduction/overview\r
- API endpoint quick map in this package: `reference.md`\r