语言: 根据用户消息自动检测语言，用于解释、确认、错误提示和后续对话。CLI 输出为中英文双语；结果以用户语言呈现。

Kling AI

支持视频生成、图像生成、主体管理以及（只读）账户资源/配额查询。

根据用户意图调用子命令 video | image | element | account。

生成任务会产生费用；当意图不明确时，需在提交前向用户确认。

调用方式

从仓库根目录执行：

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

以下示例中，{baseDir} 指技能目录（例如 skills/klingai）。

路由优先级（OpenClaw）

• 对于具有复杂生成需求的可灵（Kling）请求，默认使用本技能（node {baseDir}/scripts/kling.mjs ...）。
• 扩展工具仅允许用于简单、明确且参数较少的基础场景：文本到视频或单图转视频。
• 除非用户明确要求，否则不得使用“尝试扩展工具，失败后回退到技能”的试探性路由流程。

意图路由（必须）

根据用户意图首先选择子命令。HTTP API 路径和默认 model_name 由 路由与模型 决定。

选择规则：

• 涉及视频相关操作 → 使用 video
• 简单、明确的基本文本到视频或单图转视频 → 可使用扩展工具；其他视频场景优先使用本技能
• 仅涉及图像操作 → 使用 image
• 主体增删改查 → 使用 element
• 查询配额/余额/资源包 → 使用 account（默认 --costs）
• 生成时复用已有主体 → 在 video/image 命令中使用 --element_ids
• 首次创建主体 → 使用 element

强制使用本技能的条件（任一满足即触发）：

• 输入图片数量 ≥2 张
• Omni 或帧控制（first_frame/end_frame/image_types）
• 参考视频（--video + feature/base）或视频编辑
• 主体/元素复用（--element_ids）
• 分镜或多镜头（--multi_shot，分镜）
• 图像系列生成（--result_type series / --series_amount，组图）
• 扩展工具参数缺失或参数意图模糊/不清晰

模型名称严格规则：

• --model 必须为标准小写连字符格式：kling-v3、kling-v3-omni、kling-video-o1、kling-image-o1。
• 不得在 CLI 中传入别名。
• 别名解析规则：视频O3/图片O3 → kling-v3-omni；仅 o1/omni1 映射为 O1 模型。

当存在歧义（如视频 vs 图像，或 v3-omni vs o1）时，应先询问用户，再提交。

预检清单（提交前必做）

在任何计费提交前，必须通过以下所有检查。若任一检查失败，停止并提示用户或运行 --help。

1. 子命令已确认：video / image / element / account。
2. 路由已确认：基础模式 vs Omni 模式（来自 路由与模型）。
3. --model 为标准命名（禁止使用 o3、omni3 等别名）。
4. 所有参数均来自本 SKILL.md 或子命令 --help；不得使用未记录的标志。
5. 无冲突组合（如 --multi_shot + --image_tail，--video + --sound on）。
6. 查询模式与提交模式不混合使用。

反伪造政策（禁止猜测）

• 不得虚构模型名称、枚举值、取值范围、默认值、请求字段或隐藏标志。
• 不得从旧版或其他技能推断不支持的值。
• 若值不确定，应通过 node {baseDir}/scripts/kling.mjs <subcommand> --help 验证。
• 若用户意图不明确，应先询问，不得提交试运行任务。
• 若用户使用别名词汇，应映射为标准名称，并仅传递标准名称。

成本与提交规则

• 每次提交均计费；不得随意提交。
• 意图不明确时，必须先确认。
• 遇超时/失败/异常结果时，询问用户是否等待或重试。
• 不得自动重试或无声更改意图/参数。

代理循环与结果处理

• 入口：仅接受 node {baseDir}/scripts/kling.mjs 搭配 video/image/element/account。
• 默认流程：提交 → 轮询（约每 10 秒一次）→ 下载至 --output_dir。
• 长时间运行时，持续向用户更新状态（submitted -> processing -> succeed/failed）。
• --no-wait 流程（视频/图像）：提交 → 获取 task_id → 使用相同子命令 --task_id <id> 查询 → 成功后添加 --download。
• 查询模式严格性：使用 --task_id 时，不得混用仅提交类标志（--prompt、--multi_shot、--image、--element_ids、--video）。
• 严禁输出敏感信息（KLING_TOKEN、access_key_id、secret_access_key）。

结果呈现要求：

• 始终返回任务 ID 和本地路径。
• 若输出包含 URL，提供 Markdown 链接作为备用。

前置条件

• 运行时：Node.js 18+，无需额外包。
• 凭证优先级：KLING_TOKEN（仅会话）→ 存储在 .credentials 中的 AK/SK（每次请求使用 JWT）。
• KLING_TOKEN 为仅会话覆盖：不从环境文件读取，且不会被 --bind、--import-env、--import-credentials 或 --configure 持久化。
• 权限/认证错误：仅使用绑定/重新绑定流程；报告原因；需用户确认后方可重新绑定。
• 存储根目录：默认为 ~/.config/kling，可选配置 KLING_STORAGE_ROOT。
• 无令牌且无 AK/SK：CLI 自动启动绑定流程。
• account --bind：初始化 → 验证 → 自动打开浏览器 → 轮询。
• account --bind-url：初始化 → 验证 → 输出 URL（手动打开）→ 轮询。
• 绑定/认证失败：不得静默切换 API 基地址或重写网络参数。
• 强制重新绑定（需用户确认）：

- node {baseDir}/scripts/kling.mjs account --bind --force

- 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

• 用户界面文本中对密钥值进行遮蔽处理。
• 可选行为（API 基地址、媒体根路径）：检查子命令 --help 获取详情。

快速开始

# 显示帮助
node {baseDir}/scripts/kling.mjs --help

# 视频生成
node {baseDir}/scripts/kling.mjs video --prompt "一只猫在草地上奔跑" --output_dir ./output
node {baseDir}/scripts/kling.mjs video --image ./photo.jpg --prompt "风吹动头发"
node {baseDir}/scripts/kling.mjs video --prompt "匹配 <<<video_1>>> 的运动轨迹" --video "https://..." --video_refer_type feature
node {baseDir}/scripts/kling.mjs video --prompt "将背景改为 ..." --video "https://..." --video_refer_type base
node {baseDir}/scripts/kling.mjs video --multi_shot --shot_type customize --multi_prompt '[{"index":1,"prompt":"日出","duration":"5"}]'
node {baseDir}/scripts/kling.mjs video --multi_shot --shot_type intelligence --prompt "一个三段式故事：登场、冲突、解决"

# 图像生成
node {baseDir}/scripts/kling.mjs image --prompt "一只橙色的猫坐在窗台上"
node {baseDir}/scripts/kling.mjs image --prompt "山间日落" --resolution 4k
node {baseDir}/scripts/kling.mjs image --prompt "<<<element_1>>> 在海滩上" --element_ids 123456

# 主体 / 元素管理
node {baseDir}/scripts/kling.mjs element --action create --name "角色A" --description "一个穿红衣的女孩" --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>

# 账户管理
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 "我的资源包"
node {baseDir}/scripts/kling.mjs account --bind
node {baseDir}/scripts/kling.mjs account --bind-url
node {baseDir}/scripts/kling.mjs account --bind --force
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

# 查询已有任务
node {baseDir}/scripts/kling.mjs video --task_id <id> --download
node {baseDir}/scripts/kling.mjs image --task_id <id> --download

各子命令核心参数

请勿自行编造值、范围、枚举或默认值。如有不确定，请参考：

node {baseDir}/scripts/kling.mjs <subcommand> --help

video（视频生成）

模型别名提醒：

• omni3/omni v3/o3/video o3/image o3/视频O3/图片O3 → kling-v3-omni
• o1/omni1 → 根据意图选择 kling-video-o1 或 kling-image-o1

多镜头（--multi_shot）规则（文本生成视频 / 图像生成视频 / Omni 视频共享相同请求语义）：

• multi_shot=false：忽略 shot_type 和 multi_prompt。
• multi_shot=true：--shot_type 必须指定；不可使用 --image_tail。
• shot_type=customize：--multi_prompt 必须提供（JSON 数组，1–6 个镜头，每个镜头包含 index/prompt/duration，总持续时间等于 --duration）。
• shot_type=intelligence：--prompt 必须非空；不可传入 --multi_prompt。

Omni image_list 规则（视频）：

• image_url 不能为空（URL 或 Base64 编码）。
• type 由意图驱动：仅当用户明确要求帧控制时，才可使用 first_frame / end_frame。
• --image_tail 需配合 --image 使用。
• 使用 --video 时，最多支持 4 张图片；不使用 --video 时，最多支持 7 张。
• 使用 kling-video-o1 模型时，若图片数量超过 2 张，则禁止使用 end_frame。
• 帧生成功能不可与 --video_refer_type base 同时使用。

Omni element_list 规则（视频）：

• element_id 不能为空。
• 帧生成最多支持 3 个主体。
• 使用 kling-video-o1 时，首帧和末帧不支持主体。
• 使用 --video 时，image_count + element_count <= 4；否则 <= 7。
• 使用 --video 时，API 不支持视频角色主体；CLI 无法仅凭 element_id 预先验证主体角色。

Omni video_list 规则（视频）：

• 最多允许一个视频 URL。
• --video_refer_type 可选值为 feature / base（默认为 base）。
• --keep_original_sound 可选值为 yes / no。
• 当 refer_type=base 时，不得定义首帧/末帧（即 first_frame / end_frame / --image_tail）。
• 使用 --video 时，--sound 必须设为 off。

紧凑示例：

# 显式通过意图标记帧
node {baseDir}/scripts/kling.mjs video --model kling-v3-omni --image a.jpg,b.jpg,c.jpg --image_types first_frame,,end_frame --prompt "..."

# 使用参考视频：图片数量 ≤ 4
node {baseDir}/scripts/kling.mjs video --video "https://..." --video_refer_type feature --image a.jpg,b.jpg --prompt "..."

image（图像生成）

注意事项：

• n 和 series_amount 适用于不同模式。
• series 模式仅支持 i2i，因此使用 --result_type series 时必须提供 --image。

Omni 引用规则（图像）：

• image 不能为空（URL 或 Base64 编码）。
• element_id 不能为空。
• image_count + element_count <= 10。

element（主体管理）

用于管理自定义主体：从图像或视频创建主体、查询任务、列出自定义/预设主体、删除主体。

在 video / image 中使用 --element_ids 时，可通过 element_id 实现主体的一致性复用。

account（资源与配额查询，可选绑定）

所有绑定/账户相关文件均持久化存储于存储根目录（默认为 ~/.config/kling，或由 KLING_STORAGE_ROOT 环境变量指定）。

--costs 查询参数：

运行 node {baseDir}/scripts/kling.mjs account --help 查看详细信息。

运行 node {baseDir}/scripts/kling.mjs video --help、image --help 或 element --help 查看完整参数列表。

路由与模型（CLI：kling.mjs + 标志 → 默认 model_name）

各代理通过执行 node {baseDir}/scripts/kling.mjs <video|image|element|account> 并传入标志来调用服务。

--model 用于设置选定路由的 model_name，必须为精确的规范拼写。

若未指定 --model，将使用路由默认值。

CLI 在提交前会进行防护校验，拒绝不兼容的模型/路由组合以及无效的 sound 组合。

路由决策树（必须遵循）

1. 根据意图选择子命令：video / image / element / account。
2. 确定路由触发条件：

- 出现任意 Omni 触发条件 → 进入 Omni 路由。

- 否则 → 进入基础路由。

1. 验证模型与路由的兼容性：

- Omni 路由仅接受具备 Omni 能力的规范模型。

- 基础路由拒绝仅支持 Omni 的模型。

1. 验证严格参数组合（如 sound、multi_shot、帧规则、引用限制等）。
2. 若存在不确定性，应运行 --help 或询问用户；绝不应猜测提交。

Video（video 子命令）

Omni 路由触发条件（任一满足即进入 omni-video API 路由）：

• --element_ids
• --video
• --image 中包含逗号
• --image 与 --aspect_ratio 同时使用
• 显式指定 --model kling-v3-omni 或 --model kling-video-o1

否则：

• 基础文本生成视频（T2V）：不使用 --image
• 基础图像生成视频（I2V）：单张 --image（可选 --image_tail）

--multi_shot 不强制使用 Omni 模式；故事板模式仍遵循上述路由触发规则。

图像生成（image 子命令）

Omni 路由触发条件（满足任意一项 → 使用 Omni 图像 API 路由）：

• 显式指定 --model kling-v3-omni 或 --model kling-image-o1
• 使用 --element_ids
• 指定 --result_type series
• 设置 --resolution 4k
• 设置 --aspect_ratio auto
• 在 --image 中包含逗号

否则 → 使用基础生成路由（文生图 / 图生图）。

模型目录（按名称）

通用别名（仅用于理解，不要在 --model 中使用别名）：

• omni3、omni v3、视频O3、O3、o3、图片O3 → kling-v3-omni
• o1、omni1 → 根据意图选择 kling-video-o1 或 kling-image-o1

--model 输入规则：仅可传入本表中的规范名称。

核心原则：

• 首先设置任务标志（如 --image、--element_ids、--video、--multi_shot 等）
• 省略 --model 以使用路由默认模型
• 若显式指定 --model，其必须与标志所隐含的路由一致

何时使用 Omni 模式；元素与图像引用的区别

选择路由：请依据 路由与模型 触发条件。

当需要多图合成、图像+元素组合、4K/系列模式或编辑类指令时，建议使用 Omni 模式。

使用提示词占位符 <<<...>>> 来引用 Omni 模式的媒体或主体。

对于简单任务，推荐使用普通图像引用。

仅当用户明确希望在多个输出中保持主体一致性时，才创建元素。

提示词模板语法（视频 / 图像 Omni 模式）

在 Omni 模式下，通过标志传递媒体/主体，可在 --prompt 中通过占位符引用：

• <<<image_1>>> → 第一个 --image（<<<image_2>>> 等依次类推）
• <<<element_1>>> → 第一个 --element_ids（<<<element_2>>> 等依次类推）
• <<<video_1>>> → --video 视频片段（仅限 video 子命令）

注意事项

• 生成耗时：视频约 1–5+ 分钟；图像约 20–60 秒；主体创建约 30 秒 – 2 分钟
• 数据保留：平台可能在约 30 天后删除资产，请及时本地保存输出结果

参考资料

• 官方开发者文档（中文）：https://app.klingai.com/cn/dev/document-api
• 官方开发者文档（全球版）：https://kling.ai/document-api/quickStart/productIntroduction/overview
• 本包内 API 端点快速对照表：reference.md