Kling CLI

可灵（Kling）AI 官方命令行工具：文生图 / 参考图生图 / 文生视频 / 图生视频（含 Omni 模型）。

• CLI 形态的 MCP client：命令与可灵后端 MCP 工具一一对应（text_to_image、query_tasks …），CLI 只做参数翻译、登录、轮询与上传。
• 跨平台：macOS / Linux / Windows，仅需 Node.js 18+，无其它依赖。
• Agent 友好：所有输出为 JSON，非交互环境自动免提问。配套的 Agent 使用技能（SKILL.md）独立托管、单独分发，不随本包发布。

安装

可灵分国内站与海外站，对应两个安装包，端点已各自内置；按账号区域二选一（命令名均为 kling）：

# 国内站（账号登录 klingai.com）
npm i -g @klingai/cli-cn --registry=https://registry.npmjs.org

# 海外站（global）
npm i -g @klingai/cli-global --registry=https://registry.npmjs.org

kling <command>

要求 Node.js >= 18。两个包发布到 npm 官方 registry。下文示例统一用 kling。

升级

# 升级到最新（按已装区域包替换包名；勿用 npm update -g，可能不会跳大版本）
npm i -g @klingai/cli-cn@latest --registry=https://registry.npmjs.org

kling --version              # 查看当前版本

快速开始

# 1. 登录（端点已内置，开箱即用；打开浏览器完成 OAuth 授权，凭据保存在本地，不会打印）
kling login

# 2. 能力发现（身份 + 各生成命令的可用模型与参数规格，新会话建议先调）
kling who_am_i

# 3. 文生图，--poll 60 表示最多等待 60 秒直接返回结果
kling text_to_image "一只柴犬坐在咖啡馆窗边" --poll 60

# 4. 或者先提交、再用返回的 generation_id 查询
kling text_to_image "一只柴犬坐在咖啡馆窗边"
kling query_tasks <generationId> --poll

生成成功后，从输出 JSON 的 works[].url 取图片/视频地址（无水印版本为 works[].url_without_watermark）。

命令一览

生成与查询命令和可灵后端 MCP 工具同名（snake_case），无别名：

| # | 命令名 | 分组 | 同步性 | 触达下游 | 一句话说明 | |---|--------|------|--------|----------|------------| | 1 | --help（或不带参数） | 能力发现 | 同步 | 否 | 打印全部命令与用法；<command> --help 查看单命令参数（纯本地，不联网） | | 2 | who_am_i | 能力发现 | 同步 | 否 | 返回当前用户身份 + 每个生成命令的可用模型与参数规格；首次调用先打它 | | 3 | text_to_image <prompt> | 生成 | 异步 | 是 | 文生图，返回 generation_id，需轮询 query_tasks（或加 --poll 一步出结果） | | 4 | image_to_image --image <url\|path> <prompt> | 生成 | 异步 | 是 | 参考图 + prompt 生新图，返回 generation_id（本地图片自动上传） | | 5 | text_to_video <prompt> | 生成 | 异步 | 是 | 文生视频，返回 generation_id，需轮询 query_tasks | | 6 | image_to_video --image <url\|path> <prompt> | 生成 | 异步 | 是 | 图生视频（让图动起来），返回 generation_id | | 7 | query_tasks <generationId> | 任务查询 | 同步 | 是 | 按 generation_id 查询生成状态与最终资源 URL（works[].url） | | 8 | file_upload <path> | 文件上传 | 同步 | 是 | 两步式上传（申请一次性票据 + 上传文件字节），返回公网 URL | | 9 | account | 商业化 | 同步 | 是（kRPC） | 会员类型 + 可用灵感值（query_membership_and_credits，身份取自 JWT） | | 10 | tool_list | 能力发现 | 同步 | 否 | 列出后端 MCP server 当前暴露的工具（MCP tools/list）：name / description / inputSchema | | 11 | login | 鉴权 | 同步 | 否（仅 OAuth 服务） | 浏览器 OAuth 登录（DCR + PKCE），token 写入本地 .credentials | | 12 | logout | 鉴权 | 同步 | 否（仅 OAuth 服务） | 吊销（尽力）并清除当前端点的本地登录态 |

端点已内置（src/config.ts 的 DEFAULT_BASE_URL，端点唯一来源，发布时定稿），开箱即用；无外部覆盖口子（无 KLING_BASE_URL、无 .env），换端点须改该常量后重新发布。凭据按端点 host 分段保存，多端点可共存。

全局 flag（所有命令通用）：

| Flag | 作用 | |------|------| | --model <名称> | 指定模型（除非使用 --omni，否则生成命令必填；可用模型见 who_am_i） | | --omni | 选用 omni 系模型（生成命令） | | --skill-name <n> / --skill-version <v> | 可选遥测：标识调用方 skill（随请求上报服务端，不影响功能） | | --poll [N] | 提交后原地轮询最多 N 秒（裸 flag 默认 60，0 关闭） | | --quiet / -q | 紧凑单行 JSON 输出（便于管道处理） | | --help / -h | 查看帮助（顶层或单命令） | | --version / -v | 查看版本 |

任意命令加 --help 可查看该命令的参数说明，如 kling image_to_video --help。对 MCP-backed 命令，单命令 help 会尽量拉取实时 tools/list 声明（工具说明 + inputSchema），离线或未登录时回退到本地静态用法。

模型与参数：以 who_am_i 为准

可用模型、每个参数的必填性 / 默认值 / 合法取值全部由服务端声明，运行 kling who_am_i 即可查看。生成命令必须显式传 --model <名称>，或明确使用 --omni；其他未传参数由服务端回填默认值。传了未声明的参数或非法取值，服务端会在扣费前报错并列出问题项。

常用示例

文生图 text_to_image

kling text_to_image --model kling-image-v3_0 "赛博朋克城市夜景" \
  --aspectRatio 16:9 --imgResolution 2k --imageCount 4 --poll 120

# 指定模型 / 选 omni 系模型
kling text_to_image --model kling-image-v3_0 "水彩风格的富士山" --poll
kling text_to_image --omni "水彩风格的富士山" --poll

参考图生图 image_to_image

# --image 可传公网 URL 或本地路径（本地文件自动上传），可重复
kling image_to_image --model kling-image-v3_0 --image ./cat.jpg --image ./style.png \
  "图片1 的猫换成 图片2 的画风" --poll 120

文生视频 text_to_video

kling text_to_video --model kling-video-v1 "无人机视角掠过雪山之巅" \
  --duration 10 --aspectRatio 16:9 --poll 300

图生视频 image_to_video

kling image_to_video --model kling-video-v1 --image ./first.jpg --tailImage ./last.jpg \
  "镜头缓缓推近" --duration 6 --poll 300

任务查询与文件上传

kling query_tasks <generationId>            # 查询一次
kling query_tasks <generationId> --poll 120 # 轮询直到出结果（最多 120 秒）
kling file_upload ./photo.jpg               # 两步式上传，返回公网 URL
kling account                               # 账户身份 + 会员类型

输出与退出码

• 默认输出格式化 JSON；--quiet 输出紧凑单行 JSON。进度等提示信息写到 stderr，不污染 stdout。
• 退出码：0 成功；1 失败（参数错误 / 未登录 / 服务端报错等）；130 用户取消（Ctrl+C）。
• 提交返回 generation_id（轮询凭据）与 credits_consumed（本次消耗灵感值）；生成结果在 query_tasks 的 works[] 中，works[].url 即产物地址（无水印为 works[].url_without_watermark）。

在 AI Agent 中使用

本包是纯 CLI，不含 Agent 使用技能。配套的 kling-cli 使用技能（Agent 行为规范：意图路由 / 轮询纪律 / 计费纪律 + 接口示例）独立托管、单独分发——让 Agent 安装该技能并按其中指引调用已全局安装的 kling 命令即可。

非交互环境（Agent / 管道 / CI）下 CLI 不会停下来提问：缺参数或未登录时直接报错并以非零码退出。也可设置 KLING_NONINTERACTIVE=1 强制关闭交互。

注意事项

• 每次生成都会消耗灵感值，提交前请确认参数；失败/超时请先查询任务状态，不要盲目重试。
• 登录凭据保存在本地文件中，CLI 任何时候都不会打印 token / 密钥；logout 可清除。
• 命令没有别名：一个命令一个名字，与 MCP 工具同名（snake_case）。

License

详见包内 LICENSE 文件。