muapi-ai-clipping

AI クリッピング

API を 1 回呼び出すだけで、長尺動画を入力し、評価順に並んだ縦型ショートクリップを出力します。

各クリップには、バイラルスコア（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 秒の場面を抽出します。
• ffmpeg をローカルで実行せずに、顔を追跡した縦型（9:16）、正方形（1:1）、またはポートレート（4:5）のクロップを取得します。

独自のレンダラーでタイムスタンプだけが必要な場合は、--coords-only を設定してクロップをスキップし、ハイライトの範囲だけを取得します。

---

エージェント実行プロトコル

ステップ 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 エンドポイントは、エージェント側での処理が不要になるよう、パイプライン全体を内部で実行します。

• Whisper で文字起こしします。
• コンテンツの種類を分類します（ポッドキャスト／インタビュー／チュートリアル／Vlog／講義／モノローグ）。
• バイラリティのフレームワークを使ってハイライトを評価します。
  • フックとなる場面 — スクロールを止める、印象的な冒頭の一言
  • 感情のピーク — 笑い、怒り、弱さ、畏敬
  • 意見の爆弾 — 刺激的で、反論を招き、議論を引き起こす意見
  • 意外な発見の場面 — 「えっ、そうなの？」という視点の転換
  • 対立 — 意見の相違、緊張、批判
  • 引用に適した一言 — 短く、スクリーンショットにしたくなる表現
  • ストーリーのピーク — 物語の山場
  • 実用的な価値 — 視聴者が保存したくなる、すぐに実践できる知見
• スコアに基づいて、重複する候補を除去します。
• 上位 N 件を選択し、指定されたアスペクト比に合わせて顔を追跡しながら自動クロップします。

このスキルが小規模なのは、重い処理を API が担うためです。

---

クイック実行パターン

デフォルト — 9:16 のクリップを 3 本：

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

バッチ — 1 行につき 1 つの URL を記載した urls.txt：

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

---

アスペクト比の選択

プラットフォーム	比率	最適な長さ
TikTok / Reels / YouTube Shorts	9:16	30～75秒
Instagram フィード	1:1	15～45秒
Pinterest / ポートレート	4:5	30～60秒

プラットフォームが指定されていない場合は、デフォルトで 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 で再実行する — クリップ作成をやり直すのではなく、同じ request_id を使って muapi predict wait <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 が指定されている場合、ファイルが存在し、解析できること。