muapi-ai-clipping

AI Clipping

一次 API 调用：输入长视频 → 输出按排名排列的竖屏短片段。

每个片段都包含病毒传播评分（0–100）、开场钩子句、一句话说明“为什么有效”，以及托管的 mp4 URL。

底层 API：https://muapi.ai/playground/ai-clipping 参考实现（开源）：https://github.com/SamurAIGPT/AI-Youtube-Shorts-Generator

---

适用场景

• 将播客、访谈、讲座、vlog 或直播自动剪辑成 TikTok / Reels / Shorts 短片。
• 从任何托管视频 URL 中提取最佳的 30–75 秒片段。
• 获取带人脸追踪的竖屏（9:16）、方形（1:1）或纵向（4:5）裁剪，无需在本地运行 ffmpeg。

如果你只需要用于自定义渲染器的原始时间戳，请设置 --coords-only，跳过裁剪，仅获取精彩片段的时间范围。

---

Agent 执行协议

第 1 步 — 收集输入

输入	必填	默认值	备注
--video	是	—	托管的 mp4 URL、本地文件路径（自动上传）或 YouTube URL（如果后端支持）
--num-clips	否	3	要提取的精彩片段数量
--aspect-ratio	否	9:16	9:16 | 1:1 | 4:5
--coords-only	否	关闭	仅返回精彩片段的时间范围，跳过裁剪

如果用户只提供了视频 URL，则使用默认值运行，不要因提问而阻塞。

---

第 2 步 — 验证先决条件

• 已安装并完成身份验证的 muapi-cli（muapi auth configure）
• 可用的 MUAPI_API_KEY（环境变量，或 muapi auth status 检查通过）

就这些。无需 ffmpeg、Python、Whisper 安装，也无需 LLM 密钥。所有操作都在服务端运行。

---

第 3 步 — 运行技能

bash library/edit/ai-clipping/scripts/run-ai-clipping.sh \
  --video "https://example.com/podcast.mp4" \
  --num-clips 5 \
  --aspect-ratio 9:16 \
  --view

脚本会：

1. 将 --video 解析为托管 URL（如有需要，通过 muapi upload file 上传本地文件）。
2. 使用受支持的参数调用 muapi edit clipping。
3. 轮询直到任务完成（或在使用 --async 时立即返回 request_id）。
4. 输出排名摘要；如果设置了 --output-json，则写入完整结果。

---

服务端执行的操作

/ai-clipping 端点会在内部运行完整流程，因此 Agent 无需自行处理：

• 使用 Whisper 转录。
• 识别内容类型（播客 / 访谈 / 教程 / vlog / 讲座 / 独白）。
• 通过病毒传播评估框架为精彩片段排序：
  • 钩子时刻 — 有力的开场句，让人停止滑动
  • 情绪高潮 — 笑声、愤怒、脆弱、敬畏
  • 争议观点 — 刺激、反主流、引发争论的观点
  • 揭秘时刻 — 让人“等等，什么？”的重新解读
  • 冲突 — 意见不合、紧张关系、点名批评
  • 值得引用的句子 — 简练、适合截图的措辞
  • 故事高潮 — 叙事弧线的高潮
  • 实用价值 — 观众会收藏的可操作见解
• 按评分对重叠的候选片段去重。
• 选出排名靠前的 N 个片段，并进行人脸追踪自动裁剪，以适配所需的宽高比。

因此，这项技能很精简：繁重工作都由 API 完成。

---

快速调用示例

默认设置 — 三个 9:16 片段：

bash run-ai-clipping.sh --video "https://example.com/long.mp4"

播客 — 更多片段，在播放器中查看：

bash run-ai-clipping.sh --video "<URL>" --num-clips 8 --view

适用于 Instagram 信息流的方形片段：

bash run-ai-clipping.sh --video "<URL>" --aspect-ratio 1:1 --num-clips 3

仅获取时间戳（自建渲染器）：

bash run-ai-clipping.sh --video "<URL>" --coords-only --output-json result.json

异步提交（返回 request_id，稍后轮询）：

REQUEST_ID=$(bash run-ai-clipping.sh --video "<URL>" --async --output-json - | jq -r '.request_id')
muapi predict wait "$REQUEST_ID" --download ./outputs

本地文件：

bash run-ai-clipping.sh --video ./recording.mp4 --num-clips 5 --view

批量处理 — urls.txt 中每行一个 URL：

xargs -a urls.txt -I{} bash run-ai-clipping.sh --video "{}"

---

宽高比选择器

平台	比例	最佳时长
TikTok / Reels / YouTube Shorts	9:16	30–75s
Instagram 信息流	1:1	15–45s
Pinterest / 纵向	4:5	30–60s

除非指定了平台，否则默认使用 9:16。

---

输出结构

{
  "source_video_url": "...",
  "shorts": [
    {
      "title": "The one mistake that cost me $50K",
      "start_time": 124.3,
      "end_time": 187.6,
      "score": 92,
      "hook_sentence": "Nobody talks about this, but it killed my first startup...",
      "virality_reason": "Opens with a number + regret, peaks on a contrarian lesson",
      "clip_url": "https://.../short_1.mp4"
    }
  ]
}

设置 --coords-only 时，每个条目都会包含 start_time/end_time，但不包含 clip_url — 使用 ffmpeg 在本地渲染。

向用户反馈时，为每个片段展示：排名、评分、时间范围、标题、钩子和片段 URL。

---

应避免的常见错误

1. 平台的宽高比错误 — Shorts / TikTok / Reels 的宽高比为 9:16。默认使用该比例。
2. 为凑足 num_clips 而填充结果 — 如果 API 返回的可用片段少于请求数量，就返回已有结果。不要弄虚作假。
3. 对返回 404 的片段 URL 重新运行 — 可以使用 muapi predict wait <id> 重新获取同一个 request_id，而不必重新剪辑。
4. 尝试调整 Whisper / 分块大小 / LLM 提示词 — 这些参数不可用；端点会处理。

---

失败情况

• 缺少或被拒绝的 API 密钥 — 呈现确切错误；绝不要伪造密钥。
• 作业超时 — 增加轮询超时时间（--poll-timeout）并重试。
• 后端无法访问源 URL — 先使用 muapi upload file <path> 在本地上传，再传入返回的 URL。
• 返回的片段少于请求数量 — 源内容中可供排名的精彩片段较少。返回已有结果并附上说明。

---

完成标准

满足以下条件时，技能即完成：

1. result.shorts 最多包含 num_clips 个条目，每个条目都有可用的 clip_url（或在使用 --coords-only 时包含 start_time / end_time）。
2. 已向用户展示排名列表（分数、时间范围、标题、钩子、URL）。
3. 如果设置了 --output-json，文件存在且可解析。