可灵 AI 官方图片/视频生成、主体(Element)与动作控制
语言与回复风格
- 面向用户的解释、确认、错误说明:跟随用户语言(中文用户用中文回复,英文用户用英文回复)。
- 技术字段名(
generationId、status、works[].url等)保留英文原样。响应字段统一 camelCase(如generationId/creditsConsumed/urlWithoutWatermark);旧版服务端可能仍返回 snake_case 同义字段(generation_id等),按同一字段理解即可。
能力介绍
固定欢迎语(文案本身无需调用命令),适用于以下场景。
- 用户刚完成本 skill 或 CLI 的安装/登录,环境确认可用时;
- 用户询问可灵能做什么 / 有哪些能力 / 怎么用等能力咨询类意图(没有具体生成任务)时。
展示要求(保留结构与 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)
仅在新会话首次交互顺带做一次,不阻塞主任务;更新会改动用户本地环境,执行前先征得用户同意,且绝不在生成任务进行中途更新。任一步失败(离线 / 无权限 / 网络异常)→ 静默跳过、继续主任务,不反复重试。
- 更新 skill 自身:重新运行安装命令即可按内容哈希覆盖到最新(已是最新则无操作):
npx skills add klingai-tech/skills
它覆盖的是磁盘上的 skill 文件,对下一次会话生效;当前会话已加载的内容不会因此热更新。
- 检查 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)
⚠️ 与可灵的一切交互必须且只能通过
klingCLI 命令完成。
- 禁止直接 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(需登录),离线/未登录时回退本地静态用法 |
| 2 | who_am_i | 能力发现 | 同步 | 否 | 返回当前用户身份 + 每个生成命令的可用模型与参数规格;首次调用先打它 |
| 3 | text_to_image <prompt> | 生成 | 异步 | 是 | 文生图,返回 generationId,需轮询 query_tasks(或加 --poll 一步出结果) |
| 4 | image_to_image --image <url|path> <prompt> | 生成 | 异步 | 是 | 参考图 + prompt 生新图,返回 generationId(本地图片自动上传) |
| 5 | text_to_video <prompt> | 生成 | 异步 | 是 | 文生视频,返回 generationId,需轮询 query_tasks |
| 6 | image_to_video [--image <url|path>] [prompt] | 生成 | 异步 | 是 | 图生视频 / 关键帧;输入与 prompt 必填性依模型声明,返回 generationId |
| 7 | omni_ref_video <prompt> | 生成 | 异步 | 是 | 混合图片、视频、音频或 Element 参考,类型以模型声明为准,返回 generationId |
| 8 | query_tasks <generationId> | 任务查询 | 同步 | 是 | 按 generationId 查询生成状态与最终资源 URL(works[].url) |
| 9 | file_upload <filePath> | 文件上传 | 同步 | 是 | 两步式上传(申请一次性票据 + 上传文件字节),返回公网 URL |
| 10 | element_create | 主体素材 | 同步 | 是 | 从图片组或视频创建可复用 Element,返回 element id |
| 11 | element_list / element_get | 主体素材 | 同步 | 是 | 列出 Element;按 id 获取完整类型与资源详情 |
| 12 | element_update / element_delete | 主体素材 | 同步 | 是 | 按字段更新或删除 Element;图片主图由 CLI 自动保留 |
| 13 | motion_library_list | 动作素材 | 同步 | 是 | 列出已保存动作,获得 motionId 与可播放 URL |
| 14 | motion_control | 生成 | 异步 | 是 | 用主体图 + 动作视频或 motionId 生成视频,返回 generationId |
| 15 | feedback | 反馈 | 同步 | 是 | 上报卡住、模糊错误、计费异常或意外结果;不负责重试/退款/修复 |
| 16 | account | 商业化 | 同步 | 是 | 会员类型 + 可用灵感值(query_membership_and_credits,身份取自 JWT) |
| 17 | tool_list | 能力发现 | 同步 | 否 | 列出后端 MCP server 当前暴露的工具(MCP tools/list):每个工具的 name / description / inputSchema(排障 / 确认服务端实际提供哪些 tools 用) |
| 18 | login | 鉴权 | 同步 | 否(仅 OAuth 服务) | 浏览器 OAuth 登录(DCR + PKCE),token 写入本地 .credentials |
| 19 | logout | 鉴权 | 同步 | 是 | 调用 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)。
- 新会话先
kling who_am_i:一次拿到身份 + 每个生成命令的可用模型与参数规格(必填 / 默认值 / 值域)。后续选模型、配参数都以它为准。 - 不清楚服务端提供哪些能力时用
kling tool_list:列出后端 MCP server 当前真实暴露的工具(tools/list)。适合排障、确认某能力是否上线,需已登录、不扣费。 - 查某个命令怎么传参用
kling <command> --help:对生成命令尽量读取实时who_am_i模型参数与输入槽位,其他 MCP 命令读取tools/list(工具说明 + inputSchema);离线 / 未登录时回退本地静态用法。完整模型与参数仍以who_am_i为准。 - 生成必须显式选模型:
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 等非交互环境则在扣费前报错。 - 素材直接传本地路径或公网 URL:按所选命令的帮助传图片、视频或音频素材;本地文件由 CLI 自动
file_upload,无需手动上传;公网 URL(外部 CDN / 外链,或此前可灵任务返回的works[].url)直接透传给服务端,无需先下载、重新上传或本地校验。素材的格式 / 大小等限制以工具实时声明为准(kling <command> --help/kling tool_list)。 - 提交后立即反馈再轮询:从响应取
generationId与creditsConsumed先告知用户;再用kling query_tasks <generationId>轮询,或提交时加--poll [N]一步出结果(裸--poll默认 60s,--poll 0关闭内联轮询)。 - 结果在
works[]:提取原片链接并按「结果展示」交付。视频有独立预览时优先用预览播放。 - 余额 / 会员看
account:余额不足时展示服务端动态返回的充值链接(勿写死)。 - 失败不自动改参重投:参数类报错先对照
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,勿写死,见「余额不足与充值」) |
| 登出 / 退出当前账号 | logout | MCP 注销成功后清除本地登录态;成功即结束,不自动重新登录 |
| 切换账号 / 换一个账号登录 | 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 主体工作流与兼容约束
- 创建:图片 Element 用
--cover+ 1–3 个--secondary;视频 Element 只用--video,两种资源不可混传。两者都至少带一个--tag,标签必须从当前区域element_create的实时工具 description 中选择并原样传入;创建和更新都不要按对话语言翻译标签或硬编码某一区域的目录。可选.mp3--voice。本地文件自动上传。 - 绑定前先确认类型与兼容性:先
element_list找 id,再element_get <id>看完整resource,并同时核对实时工具 description 的主体类型限制和who_am_i的模型参数。目标模型必须声明elements;图片主体不能仅因模型名是kling-image-o1就被拒绝。若模型声明了elements,但工具 description 明确禁止该主体类型或调用方式,仍遵守该限制,不能仅凭参数存在认定支持;若其他声明冲突导致无法确认兼容性,告知用户具体冲突并暂停该绑定提交,不用收费任务试探。兼容模型需符合用户意图,切换模型前遵循重试与选型规则。 - 绑定写法:prompt 中用
<<<id>>>标记主体,同时按who_am_i声明传--elements '[{"id":"<id>","bindName":"<name>","type":"<element_get 返回的类型>"}]'。不得只写占位符却漏传elements,也不得对不兼容工具/模型硬传。 - 更新只传变更字段:用户不需要手工补全现有字段,也不要传
--cover。真实 TTY 缺少elementId时会先提示输入;但 Agent 场景下,Agent 须从已知 Element 中获取 id 并显式传入。