muapi-ai-clipping

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Clipping

AI剪辑

One API call: long video in → ranked vertical short clips out.

Each clip ships with a viral score (0–100), an opening hook line, a one-sentence "why it works" reason, and a hosted mp4 URL.

Underlying API: https://muapi.ai/playground/ai-clipping Reference implementation (open source): https://github.com/SamurAIGPT/AI-Youtube-Shorts-Generator

一次API调用：输入长视频 → 输出已排名的垂直短视频。

每个片段都会附带传播度分数（0–100）、开场钩子文案、一句“为何有效”的说明，以及托管的mp4链接。

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

When to Use

适用场景

Auto-clip a podcast, interview, lecture, vlog, or stream into TikTok / Reels / Shorts.
Extract the best 30–75s moments from any hosted video URL.
Get face-tracked vertical (9:16), square (1:1), or portrait (4:5) crops without running ffmpeg locally.

If you only need raw timestamps for your own renderer, set

--coords-only

to skip cropping and just get the highlight ranges.

将播客、采访、讲座、vlog或直播自动剪辑为TikTok / Reels / Shorts格式的短视频。
从任何托管视频链接中提取最佳的30–75秒片段。
无需本地运行ffmpeg，即可获取人脸追踪的垂直（9:16）、方形（1:1）或竖屏（4:5）裁剪视频。

如果您只需要原始时间戳用于自定义渲染，可设置

--coords-only

参数跳过裁剪，仅获取精彩片段的时间范围。

Agent Execution Protocol

Agent执行流程

Step 1 — Collect Inputs

步骤1 — 收集输入

Input	Required	Default	Notes
`--video`	yes	—	Hosted mp4 URL, or local file path (auto-uploaded), or YouTube URL (if backend supports it)
`--num-clips`	no	`3`	Number of highlights to extract
`--aspect-ratio`	no	`9:16`	`9:16` \| `1:1` \| `4:5`
`--coords-only`	no	off	Return just the highlight time ranges, skip cropping

If the user gave only a video URL, run with defaults — don't block on questions.

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

如果用户仅提供了视频链接，使用默认参数运行，无需额外询问。

Step 2 — Verify Prerequisites

步骤2 — 验证前置条件

```
muapi-cli
```
installed and authed (
```
muapi auth configure
```
)
```
MUAPI_API_KEY
```
available (env var or
```
muapi auth status
```
passes)

That's it. No

ffmpeg

, no Python, no Whisper install, no LLM keys. Everything runs server-side.

已安装并授权
```
muapi-cli
```
（执行
```
muapi auth configure
```
）
```
MUAPI_API_KEY
```
可用（环境变量或
```
muapi auth status
```
验证通过）

仅此而已。无需

ffmpeg

、Python、Whisper安装或LLM密钥。所有处理均在服务器端完成。

Step 3 — Run the Skill

步骤3 — 运行该技能

bash

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

The script:

Resolves
```
--video
```
to a hosted URL (uploads local files via
```
muapi upload file
```
if needed).
Calls
```
muapi edit clipping
```
with the supported parameters.
Polls until the job is done (or returns the
```
request_id
```
immediately under
```
--async
```
).
Prints a ranked summary and, if
```
--output-json
```
is set, writes the full result.

bash

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

该脚本会：

将
```
--video
```
解析为托管链接（若为本地文件，会通过
```
muapi upload file
```
自动上传）。
使用支持的参数调用
```
muapi edit clipping
```
。
轮询直到任务完成（若设置
```
--async
```
则立即返回
```
request_id
```
）。
打印已排名的摘要，若设置
```
--output-json
```
则写入完整结果。

What Happens Server-Side

服务器端处理流程

The

/ai-clipping

endpoint internally runs the full pipeline so the agent doesn't have to:

Transcribe with Whisper.
Classify content type (podcast / interview / tutorial / vlog / lecture / monologue).
Rank highlights through the virality framework:
- Hook moments — strong opening line that stops the scroll
- Emotional peaks — laughter, anger, vulnerability, awe
- Opinion bombs — spicy, contrarian, debate-bait takes
- Revelation moments — "wait, what?" reframes
- Conflict — disagreement, tension, callouts
- Quotable lines — tight, screenshot-worthy phrasing
- Story peaks — climax of a narrative arc
- Practical value — actionable insight a viewer will save
Dedupe overlapping candidates by score.
Top-N select and face-track auto-crop to the requested aspect ratio.

This is why the skill is small: the heavy lifting is on the API.

/ai-clipping

端点在内部运行完整流程，无需Agent处理：

转录：使用Whisper完成。
内容类型分类（播客/采访/教程/vlog/讲座/独白）。
精彩片段排名：通过传播度框架完成：
- 钩子时刻 — 能吸引用户停留的强力开场
- 情感峰值 — 笑声、愤怒、脆弱、惊叹等时刻
- 争议观点 — 尖锐、逆向、引发讨论的言论
- 揭秘时刻 — 颠覆认知的观点
- 冲突 — 分歧、紧张、指责等场景
- 金句 — 简洁、适合截图传播的语句
- 故事高潮 — 叙事弧的顶点
- 实用价值 — 用户会保存的可操作见解
去重：按分数去除重叠候选片段。
Top-N选择与人脸追踪自动裁剪：裁剪至指定宽高比。

这就是该技能体积小巧的原因：繁重的计算都由API完成。

Quick Invocation Patterns

快速调用示例

Defaults — three 9:16 clips:

bash

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

Podcast — more clips, view in player:

bash

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

Square clips for Instagram feed:

bash

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

Just the timestamps (build your own renderer):

bash

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

Async submit (returns request_id, poll later):

bash

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

Local file:

bash

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

Batch —
urls.txt
with one URL per line:

bash

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

默认配置 — 3个9:16格式片段：

bash

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

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

bash

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

适合Instagram Feed的方形片段：

bash

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

仅获取时间戳（自定义渲染）：

bash

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

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

bash

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

本地文件：

bash

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

批量处理 —
urls.txt
每行一个链接：

bash

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

Aspect Ratio Picker

宽高比选择指南

Platform	Ratio	Sweet-spot duration
TikTok / Reels / YouTube Shorts	`9:16`	30–75s
Instagram Feed	`1:1`	15–45s
Pinterest / portrait	`4:5`	30–60s

Default to

9:16

unless the platform is specified.

平台	宽高比	最佳时长
TikTok / Reels / YouTube Shorts	`9:16`	30–75秒
Instagram Feed	`1:1`	15–45秒
Pinterest / 竖屏	`4:5`	30–60秒

除非指定平台，否则默认使用

9:16

。

Output Schema

输出格式

json

{
  "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"
    }
  ]
}

When

--coords-only

is set, each entry has

start_time

end_time

but no

clip_url

— render locally with ffmpeg.

When reporting back to the user, surface for each clip: rank, score, time range, title, hook, and clip URL.

json

{
  "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本地渲染。

向用户反馈时，需展示每个片段的排名、分数、时间范围、标题、钩子文案及视频链接。

Common Mistakes to Avoid

需避免的常见错误

Wrong aspect ratio for the platform — Shorts / TikTok / Reels are
```
9:16
```
. Default to that.
Padding to hit
num_clips
— if the API returns fewer survivors than requested, return what you have. Don't pretend.
Re-running on a 404'd clip URL — the same
```
request_id
```
can be re-fetched with
```
muapi predict wait <id>
```
rather than re-clipping.
Trying to tune Whisper / chunk size / LLM prompts — those knobs aren't exposed; the endpoint handles them.

平台宽高比错误 — Shorts / TikTok / Reels使用
```
9:16
```
。默认使用该比例。
凑数达到
num_clips
数量 — 如果API返回的有效片段少于请求数量，返回实际结果即可，不要伪造。
重新调用已失效的片段链接 — 可通过
```
muapi predict wait <id>
```
重新获取同一个
```
request_id
```
的结果，无需重新剪辑。
尝试调整Whisper/分块大小/LLM提示词 — 这些参数未对外开放，由端点自行处理。

Failure Modes

故障场景

API key missing or rejected — surface the exact error; never fabricate a key.
Job timed out — bump poll timeout (
```
--poll-timeout
```
) and retry.
Source URL not reachable from the backend — upload locally with
```
muapi upload file <path>
```
first, then pass the returned URL.
Fewer clips returned than requested — the source had fewer rankable highlights. Return what came back with a note.

API密钥缺失或被拒绝 — 显示具体错误；切勿伪造密钥。
任务超时 — 增加轮询超时时间（
```
--poll-timeout
```
）并重试。
后端无法访问源链接 — 先使用
```
muapi upload file <path>
```
上传本地文件，再传入返回的链接。
返回片段数量少于请求数量 — 源视频中可排名的精彩片段不足。返回实际结果并附带说明。

Done Criteria

完成标准

The skill is done when:

result.shorts

has up to

num_clips

entries, each with a working

clip_url

(or

start_time

end_time

under

--coords-only

The user has been shown the ranked list (score, time range, title, hook, URL).
If
```
--output-json
```
was set, the file exists and parses.

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

```
result.shorts
```
包含最多
```
num_clips
```
个条目，每个条目均有可用的
```
clip_url
```
（或设置
```
--coords-only
```
时包含
```
start_time
```
/
```
end_time
```
）。
已向用户展示已排名的列表（分数、时间范围、标题、钩子文案、链接）。
若设置
```
--output-json
```
，文件已存在且可正常解析。