---
name: motion-control
description: "用一段参考视频的动作驱动一张人物图，输出该人物按相同动作运动的视频（kling motion-control）。触发场景：用户给一张人物图 + 一段动作参考视频，说'让这个人按这个动作动起来'/'用这个视频的动作做我这张图的视频'/'motion transfer'/'动作克隆'/'让 X 跳这段舞'。范围：画面里有真人/角色按参考动作做身体运动；不是讲话（讲话走 digital-human）、不是产品演示（走 video-gen）。"
version: 1.0.0
owner_repo: Optima-Chat/optima-gen
---

# Motion Control Skill

把「一张人物图 + 一段动作参考视频」变成「人物图里的角色按参考动作动起来」的视频。kling-2.6/motion-control 驱动，720p，$0.10/秒。

> **CLI 版本要求**：`@optima-chat/gen-cli ≥ 2.2.0`（含 `gen video motion-control` 子命令）。报 `unknown command` → 引导用户升级，**不**自己拼接 HTTP 调用。

> **用户向输出原则**：status / 错误 / 总结里**不出现上游品牌名**，统一用「动作驱动视频生成中」「视频生成完成」等中性描述。

## 不是这个 skill 的场景（先路由出去）

| 用户意图 | 走哪里 |
|---|---|
| 真人/数字人**讲话** | `digital-human` |
| **产品**视频（PDP / 社媒投放 / 复刻爆款） | `video-gen` |
| 纯文生 / 图生**非人物**视频（风景、动物） | `gen video`（基础视频） |
| 翻译已有口播视频 | `video-translate` |
| 剪辑已有视频 | `video-edit` |

motion-control **只管**：有具体人物图 + 想让 ta 按某段动作运动。

## 输入要求（不满足先问）

- **人物图**：jpeg/png，≥300px，长宽比 2:5 到 5:2（即不能比 5:2 更窄或更宽）。**单一清晰主角**——背景人物 / 多人会被服务端拒。
- **参考视频**：mp4/mov/mkv，3-30 秒，≤100MB，**镜头里要有完整可识别的上半身**——服务端会做人体检测，没识别到上半身会以 `No complete upper body detected` 报错。
- **缺其中之一** → 问用户补齐，不要硬上。

## 工作流（极简）

1. **确认两个输入都有**（本地路径或 http(s) URL 都行）
2. **告知预估成本**：
   - 本地视频：`ffprobe` 取时长 `D`
   - URL：必须问用户视频多长（CLI 不能自动 probe URL）
   - 成本 = `D × $0.10`，告诉用户 + 等"继续"
3. **执行**：`gen video motion-control --image <img> --reference-video <vid> [--character-orientation image|video] [--prompt "..."]`
   - duration 不传 → CLI 自动 ffprobe 本地视频；URL 必须显式 `--duration`
   - `character-orientation`：默认 `video`（输出时长 = 参考视频）；用户说「保持角色形象优先」→ `image`（输出截到 ≤10s）
4. **下载 + 展示**：CLI 自动 download 到 `./gen-output/motion_<id>.mp4`，告诉用户路径
5. **失败处理**见下表

## 错误处理

| 服务端错误 | 含义 + 处理 |
|---|---|
| `No complete upper body detected in the video` | 参考视频里没识别到完整上半身。让用户换段更清晰的动作视频，或截出有上半身的片段 |
| `file format not support` | 极少触发（已修，走 kie File Upload API）。再现 → 报 bug，不要自己重试 |
| `duration out of range` | duration 不在 3-30s（或 image-orientation 时超 10s）。截短参考视频或换 orientation 重试 |
| `INSUFFICIENT_CREDITS` | 用户积分不足，告知充值 |
| 任务超时 / 网络故障 | 用 `gen task get <id>` 查最新状态；服务端真正完成但 CLI poll 超时是正常的，结果还在 |

## 不要做的事

- **不要自己跑 ffmpeg** 拼/剪/转码 motion-control 的输出——这个 skill 只管「生成那条 motion-control 视频」，后期编辑走 `video-edit`
- **不要给"改第 N 段"做支持**——motion-control 是单次原子生成，没有 storyboard / 多段概念。用户要改 → 重新生成一发
- **不要传 `--mode`**——服务端锁 720p，传了 CLI 会过但没意义
- **不要给商家用作产品视频**——product 视频走 `video-gen`，motion-control 不适合「让产品旋转一圈」这种纯物体场景（参考视频必须有人）

## 相关工具

- `gen video motion-control` — 本 skill 唯一执行命令
- `gen task get <id>` — 查任务状态（轮询超时后用）
- `ffprobe` — 取本地视频时长，CLI 内部已用，skill 一般不直接调
