Communitygithub.com

kling-cli

通过可灵 AI 官方 CLI,直接在终端生成图片与视频、管理可复用主体与动作控制。

kling-cli 是什么?

kling-cli 是可灵 AI 的官方命令行工具,允许开发者和 AI 代理在终端中直接完成图片生成、视频生成、可复用主体(Element)管理与动作控制等任务。它支持文生图/视频、参考图生图/视频、关键帧与混合参考等多种创作用户方式,并集成了文件上传、任务查询、账户与灵感值管理等功能。该工具通过 `kling` 命令统一交互,采用 OAuth 浏览器登录鉴权,所有业务调用均通过 CLI 进行,禁止直接请求后端 API。CLI 支持同步与异步命令,异步生成任务返回 `generationId` 后需轮询 `query_tasks` 获取结果。用户需根据区域(中国区 `klingai.com` 或海外站 `kling.ai`)安装对应 npm 包,并通过 `who_am_i` 和 `tool_list` 获取实时模型、参数与工具清单,确保参数以服务端声明为准。意图路由决策表清晰映射用户需求到具体命令,避免无谓的配额消耗。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/klingai-tech/skills/tree/main

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

可灵 AI 官方图片/视频生成、主体(Element)与动作控制

语言与回复风格

  • 面向用户的解释、确认、错误说明:跟随用户语言(中文用户用中文回复,英文用户用英文回复)。
  • 技术字段名(generationId、status、works[].url 等)保留英文原样。响应字段统一 camelCase(如 generationId / creditsConsumed / urlWithoutWatermark);旧版服务端可能仍返回 snake_case 同义字段(generation_id 等),按同一字段理解即可。

能力介绍

固定欢迎语(文案本身无需调用命令),适用于以下场景。

  1. 用户刚完成本 skill 或 CLI 的安装/登录,环境确认可用时;
  2. 用户询问可灵能做什么 / 有哪些能力 / 怎么用等能力咨询类意图(没有具体生成任务)时。

展示要求(保留结构与 emoji。当前账号可用能力另见下方):

  • 中文用户:原样输出中文版。
  • 非中文用户:必须翻译,不得输出中文版——优先以英文版为底稿翻译成用户语言(日语用户给日语、西语用户给西语等,示例引语一并翻译);无法可靠翻译的语种至少原样输出英文版。
  • 若环境尚未就绪(未安装 CLI 或未登录),把首行「可灵已就绪!/ Kling is ready!」换成对应语言的引导语(如「可灵还差一步就绪」/ "Kling is one step away"),并在文案后给出安装/登录下一步。

中文版:

可灵已就绪!

你可以用可灵做这些事:

📷 生成图片
   · 文生图 — "帮我画一只赛博朋克风格的猫"
   · 参考图生图 — "用这张图做参考,改成水彩风格"

🎬 生成视频
   · 文生视频 — "生成一段日落海边的 5 秒视频"
   · 图生视频 — "让这张图动起来"
   · 关键帧 — "用这两张图指定开头和结尾"(取决于模型)
   · 全能参考 — "保留图片里的角色,参考这段视频的运镜"

🧩 可复用主体 — 创建和管理角色、动物、道具等 Element
🎭 动作控制 — 用动作视频或动作库驱动主体图片

📤 上传素材 — 可直接使用本地图片、视频和音频,具体类型依所选入口而定
📋 任务和账户 — 查生成进度、作品、会员和灵感值余额

也可以结合 agent 及 skill 能力去实现一些复杂的创作流程。比如做个广告片、故事短片、批量创作一批素材等。

英文版(非中文用户的翻译底稿;英文用户直接原样输出此版):

Kling is ready!

Here's what you can do with Kling:

📷 Generate images
   · Text to image — "Draw me a cyberpunk-style cat"
   · Image to image — "Use this image as a reference and restyle it in watercolor"

🎬 Generate videos
   · Text to video — "Generate a 5-second video of a sunset over the sea"
   · Image to video — "Bring this image to life"
   · Keyframes — "Use these two images as the opening and closing frames" (model dependent)
   · Omni Reference — "Keep the character from this image and use the camera movement from this video"

🧩 Reusable subjects — create and manage character, animal, prop, and other Elements
🎭 Motion control — drive a subject image with a motion video or saved motion

📤 Upload assets — use local images, videos, and audio where supported
📋 Jobs and account — check generation progress, results, membership, and credit balance

You can also combine agent and skill capabilities to build more complex creative workflows — like making an ad spot, a short story film, or batch-producing a set of assets.

当前账号可用能力

  • 用户问「现在能做什么」「有哪些能力」时,展示欢迎语,并用只读的 kling who_am_i 补充当前账号可用模型。安装或登录后展示欢迎语时,可直接使用本次验证已取得的清单。
  • 按图片、视频分组,用用户语言展示 availableModels 中的模型名称(优先使用易读的 alias,否则用 model)。同一模型出现在多个入口时合并展示,并标明各入口支持的创作方式。
  • 用户问具体模型、用途或参数时,只展示相关项。按对应入口核对素材类型与数量、时长、分辨率等限制,并在相关时说明参考素材的计费规则。比较时保留入口之间的差异,例如生成音轨和上传音频参考是两项能力。
  • 用户问当前账号能用哪些工具,或想确认主体库、动作库等工具是否开放时,另查只读的 kling tool_list,用创作用途说明服务端实际提供的工具。模型和参数以 who_am_i 为准。
  • CLI 未安装、未登录或查询失败时,仍可介绍通用能力,并说明当前账号的清单暂未确认。查询成功但目标模型未列出时,说明当前账号的对应入口未列出该模型。若问上线时间,使用有日期依据的信息回答。

安装与登录(唯一合法方式)

可灵分「国内站」与「海外站」,对应两个不同的安装包,端点已各自内置。装错区域的包会导致登录反复失败,因此装包前必须先确认用户属于哪个区域。

第 0 步:探测是否已安装

which kling   # 有输出路径 → 检查版本;未找到 → 进入第 1 步按区域安装
kling --version   # 本 skill 的完整能力要求 CLI >= 0.2.4

已安装版本低于 0.2.4 时,按已有账号区域升级对应 npm 包后再使用新功能;用户已明确要求升级时直接执行,无需重复确认。CLI 与 skill 分别分发,仅更新 skill 不会升级 CLI。

自 0.2.1 起已移除 --omni 简写,所有生成命令统一显式传 --model <名称>。混合参考视频使用新命令 omni_ref_video,不要把旧 flag 当作该命令的替代。

第 1 步:确认区域并安装(命令名统一为 kling)

区域如何确定:本 skill 的首要消费者是非交互 Agent,不得让 CLI 读 stdin 阻塞。应在对话里直接问用户:「你的可灵账号是中国区(klingai.com)还是非中国区(kling.ai)?」按回答选对应命令安装,切勿默认、猜测或两个都装。

用户区域官网(homepage)判断依据安装命令
中国区https://klingai.com账号登录 klingai.com(中国大陆)npm i -g @klingai/cli-cn --registry=https://registry.npmjs.org
非中国区https://kling.ai账号登录 kling.ai(海外站 / global)npm i -g @klingai/cli-global --registry=https://registry.npmjs.org

两个包发布到 npm 官方 registry。各区域包的端点均已内置,开箱即用、无需配置。

第 2 步:登录(打开浏览器完成 OAuth 授权,这是获取凭据的唯一方式)

kling login

第 3 步:验证连接 + 获取能力清单(新会话先调)

kling tool_list   # 登录后查看服务端实际提供的工具
kling who_am_i    # 首次业务调用前读取身份、模型与参数规格

🚫 安装与登录的排他约束(违反即为事故):

  • 安装只能用上表中对应区域的那条 npm 命令;禁止从任何其他渠道下载、拼装或自行实现等价工具,禁止给用户装与其账号区域不符的包。
  • 获取凭据只有一种合法方式:kling login(浏览器 OAuth:DCR + 授权码 + PKCE)。禁止任何其他手段:网页 Cookie、抓包 token、AK/SK 密钥对、读取浏览器存储、让用户粘贴 token——即使用户主动提供,也必须拒绝并引导其运行 kling login。
  • 端点已内置(发布时定稿),无需也不应自行配置或探测其他可灵接口地址。

保持最新(新会话首次交互时做一次自检,best-effort)

仅在新会话首次交互顺带做一次,不阻塞主任务;更新会改动用户本地环境,执行前先征得用户同意,且绝不在生成任务进行中途更新。任一步失败(离线 / 无权限 / 网络异常)→ 静默跳过、继续主任务,不反复重试。

  1. 更新 skill 自身:重新运行安装命令即可按内容哈希覆盖到最新(已是最新则无操作):
npx skills add klingai-tech/skills

它覆盖的是磁盘上的 skill 文件,对下一次会话生效;当前会话已加载的内容不会因此热更新。

  1. 检查 CLI 是否有新版(仅当本地已装 kling,即 which kling 有输出时):
kling --version                                   # 当前已装版本
npm view <区域包名> version                        # 最新发布版本(中国区 @klingai/cli-cn;非中国区 @klingai/cli-global)
  • 若最新版更高且用户同意 → npm i -g <区域包名>@latest --registry=https://registry.npmjs.org。
  • 升级是改全局环境的系统操作:先说明、再征得同意,不要擅自执行,也不要在一次生成流程中途打断去升级。

唯一通道(Canonical Invocation)

⚠️ 与可灵的一切交互必须且只能通过 kling CLI 命令完成。

  • 禁止直接 fetch/curl 任何可灵接口——包括 C 端页面接口、B 端开放平台 API、网关、MCP 端点本身;
  • 禁止阅读 CLI 源码、日志或抓包结果后自行拼装 HTTP/MCP 请求"绕过" CLI;
  • CLI 报错时唯一正确动作是把错误呈现给用户并询问,不得换通道、换接口重试。
kling <command> [args]

人和 Agent 共用同一入口:TTY 下有交互引导,非 TTY 输出 JSON 且绝不阻塞提问。CLI 对鉴权、日志、错误处理做了统一封装。

业务命令与可灵后端 MCP 工具名 1:1(snake_case);客户端命令包括 login、tool_list 和映射到 query_membership_and_credits 的 account。共 20 个命令,另有帮助和版本选项:

#命令名分组同步性触达下游一句话说明
1--help(或不带参数)能力发现同步否顶层 kling --help 纯本地打印全部命令;<command> --help 生成命令尽量读取实时 who_am_i 模型声明,其他 MCP 命令读取 tools/list(需登录),离线/未登录时回退本地静态用法
2who_am_i能力发现同步否返回当前用户身份 + 每个生成命令的可用模型与参数规格;首次调用先打它
3text_to_image <prompt>生成异步是文生图,返回 generationId,需轮询 query_tasks(或加 --poll 一步出结果)
4image_to_image --image <url|path> <prompt>生成异步是参考图 + prompt 生新图,返回 generationId(本地图片自动上传)
5text_to_video <prompt>生成异步是文生视频,返回 generationId,需轮询 query_tasks
6image_to_video [--image <url|path>] [prompt]生成异步是图生视频 / 关键帧;输入与 prompt 必填性依模型声明,返回 generationId
7omni_ref_video <prompt>生成异步是混合图片、视频、音频或 Element 参考,类型以模型声明为准,返回 generationId
8query_tasks <generationId>任务查询同步是按 generationId 查询生成状态与最终资源 URL(works[].url)
9file_upload <filePath>文件上传同步是两步式上传(申请一次性票据 + 上传文件字节),返回公网 URL
10element_create主体素材同步是从图片组或视频创建可复用 Element,返回 element id
11element_list / element_get主体素材同步是列出 Element;按 id 获取完整类型与资源详情
12element_update / element_delete主体素材同步是按字段更新或删除 Element;图片主图由 CLI 自动保留
13motion_library_list动作素材同步是列出已保存动作,获得 motionId 与可播放 URL
14motion_control生成异步是用主体图 + 动作视频或 motionId 生成视频,返回 generationId
15feedback反馈同步是上报卡住、模糊错误、计费异常或意外结果;不负责重试/退款/修复
16account商业化同步是会员类型 + 可用灵感值(query_membership_and_credits,身份取自 JWT)
17tool_list能力发现同步否列出后端 MCP server 当前暴露的工具(MCP tools/list):每个工具的 name / description / inputSchema(排障 / 确认服务端实际提供哪些 tools 用)
18login鉴权同步否(仅 OAuth 服务)浏览器 OAuth 登录(DCR + PKCE),token 写入本地 .credentials
19logout鉴权同步是调用 MCP logout 注销服务端授权,并清除本地登录态,以便重新授权或切换账号

端点已内置:对应区域包安装后开箱即用、无需配置;不存在任何外部配置口子(无环境变量、无 .env、无 config 命令),也不要尝试探测或指定其他可灵接口地址。

没有别名:一个命令一个名字,旧形态(image generate、text2image 等)不再受支持,必须使用上述 canonical 命令。

运行 kling(不带参数)或无效子命令时会打印完整 Usage 帮助。


推荐用法(最佳实践,Agent 须遵循)

目标:少试错、不浪费灵感值、参数永远以服务端为准。

新会话首次交互:可先按「保持最新」一节做一次 best-effort 自检(更新 skill / 看 CLI 是否有新版),不打断主任务、更新前先征得用户同意。

最简三步:① kling login 登录 → ② kling tool_list 看工具,kling who_am_i 看身份与模型规格 → ③ kling <command> 执行(6 个生成命令均必须显式带 --model)。

  1. 新会话先 kling who_am_i:一次拿到身份 + 每个生成命令的可用模型与参数规格(必填 / 默认值 / 值域)。后续选模型、配参数都以它为准。
  2. 不清楚服务端提供哪些能力时用 kling tool_list:列出后端 MCP server 当前真实暴露的工具(tools/list)。适合排障、确认某能力是否上线,需已登录、不扣费。
  3. 查某个命令怎么传参用 kling <command> --help:对生成命令尽量读取实时 who_am_i 模型参数与输入槽位,其他 MCP 命令读取 tools/list(工具说明 + inputSchema);离线 / 未登录时回退本地静态用法。完整模型与参数仍以 who_am_i 为准。
  4. 生成必须显式选模型:text_to_image / image_to_image / text_to_video / image_to_video / omni_ref_video / motion_control 均必须带 --model <名称>(取自对应工具的 who_am_i 清单)。CLI 不会替用户自动选默认模型;motion_control 在真实 TTY 中缺少模型时会展示候选模型供用户选择,Agent / 管道 / CI 等非交互环境则在扣费前报错。
  5. 素材直接传本地路径或公网 URL:按所选命令的帮助传图片、视频或音频素材;本地文件由 CLI 自动 file_upload,无需手动上传;公网 URL(外部 CDN / 外链,或此前可灵任务返回的 works[].url)直接透传给服务端,无需先下载、重新上传或本地校验。素材的格式 / 大小等限制以工具实时声明为准(kling <command> --help / kling tool_list)。
  6. 提交后立即反馈再轮询:从响应取 generationId 与 creditsConsumed 先告知用户;再用 kling query_tasks <generationId> 轮询,或提交时加 --poll [N] 一步出结果(裸 --poll 默认 60s,--poll 0 关闭内联轮询)。
  7. 结果在 works[]:提取原片链接并按「结果展示」交付。视频有独立预览时优先用预览播放。
  8. 余额 / 会员看 account:余额不足时展示服务端动态返回的充值链接(勿写死)。
  9. 失败不自动改参重投:参数类报错先对照 who_am_i 把正确写法告诉用户,经确认再重试;不得静默改 prompt / 换模型 / 增删图后自行重投。

典型顺序:登录后 tool_list → who_am_i →(按需 <command> --help)→ text_to_* / image_to_* / omni_ref_video / motion_control 带 --model 提交 → query_tasks 轮询 → 展示 works[].url。


模型与参数:以 who_am_i 为准(核心心智)

  • 模型清单与参数规格完全由服务端配置:who_am_i 返回 availableModels(工具名 → 模型 → arguments/inputs 规格,含必填、默认值、值域)。
  • 单命令帮助会优先读取实时声明:对 who_am_i / 生成 / 查询 / 上传 / 账户等 MCP-backed 命令,kling <command> --help 对生成命令尽量读取实时 who_am_i 模型参数与输入槽位,其他 MCP 命令读取 tools/list(工具说明 + inputSchema);离线或未登录时回退本地静态用法。完整模型清单与参数规格仍以 who_am_i 为准。
  • 6 个生成命令均须显式传 --model <名称>。用户指定模型时,按创作意图选择命令,在该命令的 who_am_i 清单中用名称或别名(alias)定位模型,传返回的 model 值。若无法唯一匹配,或该模型不支持所需输入或参数,向用户说明并确认后再提交;不要自行换模型。
  • 图片默认首选 Kling Image 4.0:用户未指定模型时,在 text_to_image 或 image_to_image 的实时清单中优先选满足本次需求的 Kling Image 4.0,显式传入该条目的 model 值。该模型不可用或不满足所需参数、素材时,从对应命令的清单选择支持本次需求的模型。
  • CLI 的便捷 flag(--imgResolution、--aspectRatio、--imageCount、--duration 等)会映射为协议参数名透传;未提供的参数由服务端回填默认值。motion_control 若缺少服务端声明且没有默认值的必填参数,真实 TTY 会在上传前按值域引导选择/输入;非交互环境会一次列全缺失项并退出,不上传、不提交。
  • 输入按声明映射:先用命令帮助确认 CLI 写法,再按 who_am_i 的 inputs 与 arguments 核对资源类型、槽位名和必填性;不要假设所有图生入口都必须有首帧,或所有生成命令都允许省略 prompt。使用具名输入时不得重复占用槽位,是否能与便捷 flag 混用以该命令帮助为准。各命令的映射和示例见 api-examples.md。
  • 六个生成命令中,--poll 可以省略选项值。其他生成选项需要显式传值,素材选项需与命令匹配。CLI 在上传前检查选项和必填素材。
  • 按声明设置参数并核对组合限制:根据创作意图选择入口,再按当前账号的 who_am_i 和工具说明检查所选模型的参数、默认值、可用组合与输入兼容性。用户明确要求的规格应显式传入相应参数。如果当前入口或模型无法满足,说明限制,等用户确认可用规格后再提交。
  • 图片生成:按所选模型的 arguments 核对分辨率、出图张数和生成模式,按 inputs 核对参考图数量和槽位。用户要连贯组图时,按声明设置组图模式和出图张数,并在提示词中说明每张图的内容和共用的主体、风格。
  • 输入除单类数量外,还可能有 combinedItemCap 合计上限(跨输入槽位与 elements 等数组参数)。image_to_video / omni_ref_video 会在上传前校验相关槽位、必填输入和合计数量;不要把各类上限相加后当作允许总量。字段见 reference.md。
  • 参数校验(必填、值域、未声明参数)由服务端在扣费前完成,报错信息会列出问题项;遇到参数类报错应把服务端信息翻译给用户。

意图路由(必选决策表)

用户意图命令说明
问可灵能做什么 / 有哪些能力(无具体任务)who_am_i展示通用能力和当前账号可用模型,见上方「能力介绍」
查可用模型 / 指定模型是否可用 / 参数规格who_am_i直接展示与问题相关的能力和限制
查账号开放的工具 / 主体库或动作库是否可用tool_list根据服务端实际返回说明工具用途
生成图片 / 出图 / 文生图text_to_image提交后轮询 query_tasks
参考图生图 / 带参考图image_to_image--image 可重复,提交后轮询
生成视频 / 文生视频text_to_video提交后轮询
图生视频 / 让图动起来 / 首中尾关键帧image_to_video按模型声明传 --image / --tailImage 或具名 --input;prompt 可选性依模型声明,提交后轮询
图片、视频、音频、主体混合参考生成视频omni_ref_video按模型声明传 --image / --video / --audio / --elements;prompt 必填,提交后轮询
创建/列出/查看/更新/删除可复用主体element_create / element_list / element_get / element_update / element_delete更新只传变更字段;删除前需用户明确确认
动作控制 / 动作迁移motion_control主体 --image + --video 或 --motionId 二选一;提交后轮询
查看已保存动作motion_library_list取 motionId 后可交给 motion_control
上报卡住、模糊错误、计费异常、意外结果feedback只反馈,不会重试、退款或修复原任务
明确指定模型或系列按创作意图选命令,再传完整 --model用对应命令的实时模型清单解析名称或别名
上传本地素材file_upload仅本地文件需要上传(返回公网 URL);已是公网 URL 的素材无需上传,直接作 --image 传给生成命令
查会员 / 账户身份 / 查余额account返回 userId + membership + 可用灵感值(直接展示)
查询或选择个人 / 团队工作区who_am_i → tool_list核对实时能力。仅在能确认所需工作区和计费归属时提交生成。
充值 / 余额不足 / 开通会员account展示服务端返回的充值/会员链接(动态取自 MCP,勿写死,见「余额不足与充值」)
登出 / 退出当前账号logoutMCP 注销成功后清除本地登录态;成功即结束,不自动重新登录
切换账号 / 换一个账号登录logout → login → who_am_i必须按顺序执行;logout 或 login 任一步失败都立即停止;新授权完成后验证账号
仅说「用可灵生成」等模糊意图—先问清是图还是视频,再提交

如果用户意图不明确,必须先确认再提交,不得擅自假设。

登出与切换账号

  • 仅登出:用户明确要求退出当前账号时,执行 kling logout。成功后结束;不得自动触发新的浏览器授权。
  • 切换账号:必须依次执行 kling logout → kling login → kling who_am_i。只有 logout 成功后才能继续 login;浏览器授权时由用户选择目标账号;登录成功后用 who_am_i 展示并确认当前身份。
  • logout 失败必须立即停止:保留本地登录态以便重试,并把原错误告知用户;不得跳过失败直接 login。
  • login 失败必须立即停止:报告登录错误,不得继续 who_am_i,也不得改用 Cookie、token 粘贴、抓包或其他授权方式。
  • 不要用 login 代替切换流程:login 只负责本地 OAuth 授权,单独执行不能保证服务端旧授权已注销。用户明确说"切换账号"时必须先走 logout。

个人与团队工作区

使用 who_am_i 确认登录身份,使用 tool_list 检查实时工具和参数。CLI 0.2.4 的 account 查询账号余额,会拒绝工作区选项。只有服务端明确声明工作区选择并能验证扣费归属时,才可提交用户要求从指定工作区扣费的任务。

Element 主体工作流与兼容约束

  1. 创建:图片 Element 用 --cover + 1–3 个 --secondary;视频 Element 只用 --video,两种资源不可混传。两者都至少带一个 --tag,标签必须从当前区域 element_create 的实时工具 description 中选择并原样传入;创建和更新都不要按对话语言翻译标签或硬编码某一区域的目录。可选 .mp3 --voice。本地文件自动上传。
  2. 绑定前先确认类型与兼容性:先 element_list 找 id,再 element_get <id> 看完整 resource,并同时核对实时工具 description 的主体类型限制和 who_am_i 的模型参数。目标模型必须声明 elements;图片主体不能仅因模型名是 kling-image-o1 就被拒绝。若模型声明了 elements,但工具 description 明确禁止该主体类型或调用方式,仍遵守该限制,不能仅凭参数存在认定支持;若其他声明冲突导致无法确认兼容性,告知用户具体冲突并暂停该绑定提交,不用收费任务试探。兼容模型需符合用户意图,切换模型前遵循重试与选型规则。
  3. 绑定写法:prompt 中用 <<<id>>> 标记主体,同时按 who_am_i 声明传 --elements '[{"id":"<id>","bindName":"<name>","type":"<element_get 返回的类型>"}]'。不得只写占位符却漏传 elements,也不得对不兼容工具/模型硬传。
  4. 更新只传变更字段:用户不需要手工补全现有字段,也不要传 --cover。真实 TTY 缺少 elementId 时会先提示输入;但 Agent 场景下,Agent 须从已知 Element 中获取 id 并显式传入。

相关技能