@klingai/plugin-global 0.0.0-stage → 0.0.2-beta

package/skills/kling-ai-plugin/api-examples.md

@@ -0,0 +1,328 @@
+# 可灵 MCP 工具协议与示例
+
+CLI 是可灵后端 MCP server 的薄客户端：业务调用由 CLI 统一封装并发往后端 MCP 工具（传输与鉴权细节由 CLI 处理，无需关心）。本文档是工具协议速查；字段速查见 [`reference.md`](./reference.md)。
+
+## 工具清单
+
+| # | 工具名 | 分组 | 同步性 | 触达下游 | 一句话说明 |
+|---|--------|------|--------|----------|------------|
+| 1 | `who_am_i` | 能力发现 | 同步 | 否 | 身份 + 各生成工具可用模型与参数规格；**新会话先调** |
+| 2 | `text_to_image` | 生成 | **异步** | 是 | 文生图，返回 `generationId`，需轮询 `query_tasks` |
+| 3 | `image_to_image` | 生成 | **异步** | 是 | 参考图 + prompt 生图（需 inputs），返回 `generationId` |
+| 4 | `text_to_video` | 生成 | **异步** | 是 | 文生视频，返回 `generationId`，需轮询 `query_tasks` |
+| 5 | `image_to_video` | 生成 | **异步** | 是 | 图生视频（需 inputs），返回 `generationId` |
+| 6 | `omni_ref_video` | 生成 | **异步** | 是 | 全能参考混排（图/视频/音频/主体），返回 `generationId` |
+| 7 | `query_tasks` | 任务查询 | 同步 | 是 | 按 `generationId` 查询生成状态与最终资源 URL |
+| 8 | `file_upload` | 文件上传 | 同步 | 是 | 申请一次性上传票据；文件字节由调用方自行上传（两步式，见下） |
+| 9 | `element_create` / `element_list` / `element_get` / `element_update` / `element_delete` | 主体素材 | 同步 | 是 | 可复用 Element 的完整生命周期 |
+| 10 | `motion_library_list` | 动作素材 | 同步 | 是 | 列出当前用户保存的动作素材 |
+| 11 | `motion_control` | 生成 | **异步** | 是 | 主体图 + 动作视频或 motionId 生成视频 |
+| 12 | `feedback` | 反馈 | 同步 | 是 | 上报卡住、计费异常或意外结果 |
+| 13 | `query_membership_and_credits` | 商业化 | 同步 | 是 | 查询会员身份与可用灵感值（身份取自 JWT，无参数） |
+
+> `kling-plugin <command> --help` 对上述 MCP-backed 命令会尽量实时读取该工具的 `tools/list` 声明（工具说明 + inputSchema）；完整模型清单与参数规格仍以 `who_am_i` 为准。示例：`kling-plugin image_to_image --help`。
+
+## who_am_i
+
+请求参数：无（身份取自 JWT）。返回示例：
+
+```json
+{
+  "user": { "userId": 10000001 },
+  "availableModels": {
+    "text_to_image": [
+      {
+        "model": "kling-image-v3_0",
+        "arguments": [
+          { "name": "prompt", "required": true, "description": "Text prompt describing the image to generate" },
+          { "name": "kolors_version", "required": false, "default": "3.0" },
+          { "name": "img_resolution", "required": false, "default": "2k" },
+          { "name": "aspect_ratio", "required": false, "default": "3:4" },
+          { "name": "imageCount", "required": false, "default": "1", "description": "Number of images, max 9" }
+        ],
+        "inputs": []
+      }
+    ]
+  },
+  "authMode": "oauth"
+}
+```
+
+- 模型名、参数、默认值均以**运行时返回**为准（服务端配置）。
+- `arguments[]`：`required` 必填恒无默认值；`allowedValues` 不出现表示不限制；选填缺省时服务端回填 `default`。
+
+## 生成类工具通用协议
+
+6 个生成工具（含 `omni_ref_video` / `motion_control`）共用同一套入参信封与返回结构：
+
+```json
+{
+  "model": "kling-image-v3_0",
+  "arguments": [
+    { "name": "prompt", "value": "two kids singing while running" },
+    { "name": "imageCount", "value": "1" }
+  ],
+  "inputs": [
+    { "name": "input", "inputType": "URL", "url": "https://cdn.example.com/ref.png" }
+  ]
+}
+```
+
+- `model` 必填，必须来自 who_am_i 该工具的清单。
+- `arguments[].value` **一律为字符串**；省略选填项由服务端回填默认值。
+- `inputs[].inputType` 当前仅 `"URL"`；`url` 须公网可访问：外部公网 URL（CDN / 外链、此前任务返回的 `works[].url`）直接使用，本地文件先 `file_upload` 换取 URL。`text_to_*` 通常无 inputs。
+- 可选追踪参数（纯埋点、不参与校验、不透传下游；以 `tool_list` 的 inputSchema 声明为准）：`taskTraceId`（全部工具；CLI 全局 flag `--task-trace-id`，同一任务链复用同一 ID，不传时 CLI 静默生成 UUIDv7（标准带连字符格式））、`rationale`（6 个生成工具；CLI flag `--rationale`，说明创作意图与参数理由，不传时 CLI 自动传空串）。
+
+服务端在转发下游（扣费）前做本地校验，任一不过即报参数错误（**聚合列出所有问题项**）：model 在清单内、argument 名非空/不重复/已声明、必填不缺、值域命中、inputs 同理。
+
+返回（GenerationSubmitResult）：
+
+```json
+{
+  "generationId": "Qk1Zb3VyT3BhcXVlR2VuZXJhdGlvbklkRXhhbXBsZQ",
+  "status": "submitted",
+  "creditsConsumed": 10,
+  "message": "Generation submitted. Poll query_tasks with this generationId to get the result."
+}
+```
+
+## V4 Preview
+
+标准版和 Flash 均提供 `text_to_video`、`image_to_video`、`omni_ref_video` 三个入口，显式选择对应模型：
+
+| 模型 | `--model` |
+|---|---|
+| 标准版 | `kling-video-v4_0` |
+| Flash | `kling-video-v4_0_flash` |
+
+先用 `kling-plugin who_am_i` 确认目标模型可用、参数和限制。以下按当前国内站 MCP `1.3.3` 的模型声明核对；可用值可能随账号和服务端配置变化。
+
+### 三个入口
+
+| 入口 | prompt | 标准版素材输入 | Flash 素材输入 | 两者的宽高比参数 |
+|---|---|---|---|---|
+| `text_to_video` | 必填 | 无参考素材、无主体参数 | 无参考素材、无主体参数 | `auto`（默认）、`16:9`、`9:16`、`1:1`、`21:9` |
+| `image_to_video` | 字段必填，允许显式空字符串（以实时模型为准） | `first_image`、`tail_image`、`keyframe_1..10` 均可选，图片合计最多 10 张 | 仅一个 `first_image`，必填；不接尾帧、中间帧或主体 | `16:9`、`9:16`、`1:1`、`21:9`；有首帧时省略参数以跟随首帧，不接受 `auto` |
+| `omni_ref_video` | 必填 | 图、视频、主体均可选，合计最多 15 个 | 图、视频、主体均可选，合计最多 15 个 | `auto`（默认）、`16:9`、`9:16`、`1:1`、`21:9` |
+
+### 参数与限制对照
+
+| 参数或限制 | 标准版 | Flash |
+|---|---|---|
+| `duration`（三个入口） | 3–30 秒，默认 10 | 3–20 秒，默认 10 |
+| `resolution`（三个入口） | 720p/1080p，默认 720p，按账号权限 | 仅 720p，默认 720p |
+| `imageCount`（三个入口） | 1–4，默认 1 | 1–4，默认 1 |
+| 全能参考图片槽位 | `image_1..10`，最多 10 张 | `image_1..10`，最多 10 张 |
+| 全能参考视频槽位 | `video_1..5`，最多 5 段 | `video_1..5`，最多 5 段 |
+| 全能参考主体 | 最多 7 个，其中视频主体最多 3 个 | 最多 7 个，其中视频主体最多 3 个 |
+| 全能参考合计上限 | 图、视频、主体合计最多 15 个 | 图、视频、主体合计最多 15 个 |
+| 全能参考输入视频时长 | 每段 3–30 秒；视频与视频主体合计 3–30 秒 | 每段 3–20 秒；视频与视频主体合计 3–20 秒 |
+
+`imageCount` 表示输出视频数，不是输入图片数。两者当前都不支持 4K；用户未指定参数时由服务端补默认值。
+
+全能参考另有以下参数；两个模型的文生视频和图生视频入口均未声明这些参数：
+
+| 参数 | 两个模型的当前声明 |
+|---|---|
+| `elements` | 可选；JSON 数组，每项 `{id, bindName, type}`，先 `element_get` 确认 `type` 为 `image` 或 `video`，在 prompt 中用 `<<<id>>>` 引用 |
+| `prefer_multi_shots` | 默认 `true`，当前只允许 `true` |
+| `enable_audio` | 默认 `true`，允许 `true` / `false`，表示生成新的同步音频 |
+| `keepOriginalSound` | 默认 `false`，允许 `true` / `false`，表示保留参考视频原声 |
+
+`enable_audio` 与 `keepOriginalSound` 不能同时为 true。保留原声时显式传 `--keepOriginalSound true --enableAudio false`；生成新音频时用 `--enableAudio true --keepOriginalSound false`。
+
+### 标准版示例
+
+```bash
+# 文生视频
+kling-plugin text_to_video --model kling-video-v4_0 "无人机掠过雪山" --poll 300
+
+# 仅尾帧：首帧可选；prompt 字段必填但允许空字符串，组合由服务端校验
+kling-plugin image_to_video --model kling-video-v4_0 --tailImage ./last.jpg --prompt "" --poll 300
+
+# 首帧、中间帧、尾帧自由组合，图片总数最多 10 张
+kling-plugin image_to_video --model kling-video-v4_0 \
+  --input first_image=./first.jpg --input keyframe_1=./middle.jpg \
+  --input tail_image=./last.jpg "镜头平滑推进" --poll 300
+
+# 各帧 required:false 不代表服务端接受无图组合；普通纯文本需求走文生视频
+kling-plugin text_to_video --model kling-video-v4_0 "雨夜霓虹街道" --poll 300
+
+# 全能参考：图 + 视频，保留参考视频原声
+kling-plugin omni_ref_video --model kling-video-v4_0 --image ./ref.jpg --video ./clip.mp4 \
+  --keepOriginalSound true --enableAudio false "图片1的角色跟随视频1的运镜" --poll 300
+
+# 全能参考：素材可选，也可只传提示词
+kling-plugin omni_ref_video --model kling-video-v4_0 "海边日落的长镜头" --poll 300
+```
+
+### Flash 示例
+
+```bash
+# 文生视频
+kling-plugin text_to_video --model kling-video-v4_0_flash "无人机掠过雪山" --poll 300
+
+# 图生视频：必须提供首帧；模型要求 prompt 字段但允许空值时，显式传空字符串
+kling-plugin image_to_video --model kling-video-v4_0_flash --image ./first.jpg --prompt "" --poll 300
+
+# 全能参考：图 + 视频，保留参考视频原声
+kling-plugin omni_ref_video --model kling-video-v4_0_flash --image ./ref.jpg --video ./clip.mp4 \
+  --keepOriginalSound true --enableAudio false "图片1的角色跟随视频1的运镜" --poll 300
+
+# 全能参考：素材可选，也可只传提示词
+kling-plugin omni_ref_video --model kling-video-v4_0_flash "海边日落的长镜头" --poll 300
+```
+
+Flash 的 `image_to_video` 不支持 `--tailImage`、`keyframe_*`、多张 `--image` 或不带首帧的纯文本调用。Flash 的多图、视频和主体参考走 `omni_ref_video`，素材限制按该入口单独计算。
+
+两个模型的 `image_to_video` 都不能混用 `--input` 与 `--image` / `--tailImage`。有首帧时默认跟随首帧比例；除非用户要求，否则不传宽高比。标准版通过 `--input` 指定中间帧；Flash 若用 `--input`，只能指定必填的 `first_image`。
+
+### 全能参考的共同约束
+
+- 两者均支持由 `element_get` 确认类型的图片/视频主体；使用 `elements` 绑定。文生视频和关键帧入口不绑定主体。
+- 独立音频按所选模型的实时 `audio_N` 槽位判断：新声明中标准 4.0 支持 `audio_1..3`，Flash 未声明；尚未上线音频的连接仍不能传音频。CLI 自动上传本地音频，公网 URL 直接透传。音画同步和保留视频原声由上面的音频参数控制，与独立音频槽位分开。
+- 输入图片每张最多 30MB，视频每段最多 300MB；模型说明中的素材比例范围为 2:5–5:2。视频时长按上表区分标准版与 Flash，文件时长、大小、比例由服务端校验。
+- **两个模型的全能参考都按秒计费，提交前需告知用户：输入视频时长也纳入总计费时长。**
+
+所有限制以 `who_am_i` 的实时模型声明为准。
+
+```bash
+# 先确认标准 4.0 声明 audio_1、audio_2；本地音频自动上传，计入素材合计上限
+kling-plugin who_am_i --tools omni_ref_video
+kling-plugin omni_ref_video --model kling-video-v4_0 --image ./ref.jpg \
+  --audio ./voice.mp3 --input audio_2=./music.mp3 \
+  "图片1的角色按音频1说话，使用音频2的音乐" --poll 300
+```
+
+## query_tasks
+
+请求：`{ "generationId": "<generationId 原值>" }`。返回（已完成，实测状态为大写）：
+
+```json
+{
+  "generationId": "AIUbOyYx...",
+  "status": "COMPLETED",
+  "createTime": 1781164986117,
+  "finishTime": 1781165014373,
+  "works": [
+    {
+      "status": "COMPLETED",
+      "contentType": "image",
+      "url": "https://cdn.example.com/.../out.png",
+      "urlWithoutWatermark": "https://.../out_clean.png",
+      "coverUrl": "https://.../cover.jpg",
+      "coverUrlWithoutWatermark": "https://.../cover_clean.jpg"
+    }
+  ]
+}
+```
+
+- `status` 为下游透传字符串，**按大小写不敏感处理**；中间态 `QUEUING`/`RUNNING`/`submitted`/`processing`，成功 `COMPLETED`/`PARTIAL_COMPLETED`/`succeed`。
+- `generationId` 非法或非本人 → `Generation not found. Please verify the generationId.`
+
+## file_upload（两步式）
+
+第一步（MCP 工具，参数均选填但建议提供）：
+
+```json
+{ "filename": "photo.png", "contentType": "image/png", "size": 102400 }
+```
+
+返回 `{ "ticket": "...", "uploadUrl": "...", "expireAt": 1733900000 }`。
+
+第二步（调用方自行执行，CLI 已封装）：向 `uploadUrl` 发 `multipart/form-data` POST，字段 `ticket`（票据）+ `file`（文件字节）。上传响应含文件 URL，可作为 `inputs[].url`。票据单次有效、过期作废。
+
+## Element 主体
+
+图片 Element 创建示例（本地路径由 CLI 先自动上传）：
+
+```bash
+kling-plugin element_create --name "Alice" --description "红发侦探" --tag 角色 \
+  --cover ./front.png --secondary ./side.png
+```
+
+对应 MCP payload：
+
+```json
+{
+  "name": "Alice",
+  "description": "红发侦探",
+  "resource": {
+    "cover": "https://cdn.example/front.png",
+    "secondary": [
+      { "inputType": "URL", "name": "secondary_1", "url": "https://cdn.example/side.png" }
+    ]
+  },
+  "tags": ["角色"]
+}
+```
+
+视频 Element 将 `resource` 换为 `{ "video": "https://..." }`，可选 `voice`。`element_list` 无参数；`element_get` / `element_delete` 传 `{ "id": "..." }`。CLI 的 `element_update` 接受可选变更字段，内部先调用 `element_get` 并合成完整 payload；图片 Element 始终使用 `element_get` 返回的原 `cover`，用户不传 `--cover`。
+
+## 动作库与动作控制
+
+```bash
+kling-plugin motion_library_list
+kling-plugin motion_control --model kling-video-v3_0 --image ./subject.png --motionId 123 \
+  --motionDirection image_direction --poll 300
+```
+
+`motion_control` 信封和其他生成工具相同。`inputs` 第一项为主体 `image`；使用动作视频时第二项为 `video`，使用动作库时在 `arguments` 中传 `motionId`。两种动作来源必须二选一。
+
+## feedback
+
+```bash
+kling-plugin feedback --summary "Generation completed with an empty works list" \
+  --category EMPTY_OR_PARTIAL_RESULT --triggerMode user_initiated \
+  --tool image_to_video --tool query_tasks --generationId <id>
+```
+
+该工具只上报反馈，不重试、不退款、不修复原任务；同一问题不要循环上报。
+
+## query_membership_and_credits
+
+请求参数：无业务参数（身份取自 JWT；实时 schema 可声明追踪字段 `taskTraceId`）。返回示例：
+
+```json
+{ "userId": 10000001, "membershipType": "NORMAL", "availableRemainCredits": 0 }
+```
+
+`membershipType`：`NORMAL` / `VIP` / `SVIP` / `SSVIP` / `SSSVIP`；`availableRemainCredits` 为用户可见的灵感值，无需换算。
+
+> CLI 的 `account` 命令即此工具的直通调用。
+
+```bash
+kling-plugin account  # 查询已登录账号余额，不选择工作区
+```
+
+当前响应不标识工作区或计费归属，不能据此认定是个人 / 团队余额。不要给此命令添加工作区参数：已发布 0.2.3 会忽略额外参数，成功响应不表示选择生效。指定工作区的余额查询与扣费须等待服务端明确声明选择、权限和计费契约；验证流程见 [SKILL.md 的工作区边界](SKILL.md#个人--团队工作区权限与计费边界)。
+
+## 工具发现（CLI `tool_list`）
+
+用于查看后端 MCP server 当前实际暴露的工具元数据（`tools/list`），便于排障、确认灰度能力或读取工具 description 中的动态说明。
+
+```bash
+kling-plugin tool_list
+```
+
+返回示例：
+
+```json
+{
+  "ok": true,
+  "status": 200,
+  "body": {
+    "tools": [
+      {
+        "name": "text_to_image",
+        "description": "Submit text-to-image generation.",
+        "inputSchema": { "type": "object", "properties": { "prompt": { "type": "string" } } }
+      }
+    ]
+  }
+}
+```
+
+## 鉴权
+
+鉴权全程由 `kling-plugin login`（浏览器 OAuth）封装，token 由 CLI 自动管理与续期。获取凭据**只有 `kling-plugin login` 这一种合法方式**，Agent 无需也不应手工构造任何鉴权请求或读取凭据内容。