video-clips

クリップ、ハイライト、ソーシャル向けの短い動画

利用する方法

1. VideoDB コネクターツールがある場合（generate_clip、create_highlight_clip、compile_clips、reframe_video、upload_mediaなど）：それらを使用します。Claude のウェブ、デスクトップ、モバイルでのチャット、および Cowork ではこの方法を使います。何もインストールせず、API キーも尋ねないでください。
2. VideoDB ツールはないものの、シェルを使える場合（Claude Code、Cowork、Python を実行できるエージェント）：親しみやすい一言で VideoDB API キーを尋ねます（https://console.videodb.io で無料、20 ドル分のクレジット付き、カード不要）。ユーザーがチャットなどでキーを渡したら、自分でプロジェクトの .env に VIDEO_DB_API_KEY として保存し、決して表示せず、このファイルの末尾にある Python SDK の方法を続けます。Claude Code では、/mcp を実行してから videodb を認証する方法も使えます。
3. VideoDB ツールもシェルもない場合：Claude のチャットを使用しています。リクエストに合わせて調整した、次の文だけを返信します。「VideoDB はまだ接続されていません。Settings → Connectors を開き、VideoDB を探して Connect をクリックし、ログインしてください（無料、カード不要）。それからもう一度このリクエストを送っていただければ、あとは対応します。」ここでは API キー、.env、シェル、Claude Code、/mcp について触れないでください。チャットではいずれも該当せず、チャットに貼り付けられたキーもコードを実行できないため使用できません。

ユーザーとのやり取りでは、返信に「index」「indexed」「indexing」と書かないでください。「検索可能」（「話された内容や映像に映っている内容で検索できるようになりました」）と表現し、ジョブの名前ではなく「文字起こし」と言ってください。ステータスは一度に一行だけ伝え、その後に結果を示します。

すべてのカットは時間のかかるジョブです。呼び出しは status: processing を返します。返信には output_url と、ポーリングに使うツール名（poll_with、古いサーバーでは retry_with）が含まれます。done になるまで、そのツールに output_url を渡して呼び出してください。processing が何度か続くのは正常です（10 分の YouTube アップロードなら約 5 分かかります）。結果が空の done 返信が返った場合は、もう一度ポーリングしてください。書き込み処理を再実行しないでください。2 つ目のジョブが開始されます。完了結果には stream_url と player_url が含まれます。player_url を共有してください。どのブラウザーでも開けます。

コネクタツールを使う場合

動画を取得します。 まず、動画のタイトルまたはリンクに含まれる語句で search_videos_by_title(query) を実行します。すでにアカウントに動画がある場合は、再アップロードせずに m- ID を再利用します。それ以外の場合、YouTube のリンクまたは公開 URL であれば upload_media(url) を実行し、done になるまでポーリングします。m- ID と length を記録します。ローカルファイルはコネクタ経由では受け取れません。ユーザーが https://console.videodb.io にアップロードし、m- ID を共有します。

ユーザーの希望	呼び出し
1 本の動画から 1 つ、または複数をつなげた範囲	generate_clip(video_id, timeline=[[10, 25], [60, 90]])（秒）
説明に一致する場面	generate_transcript(media_id) を 1 回実行し、次に create_highlight_clip(video_id, prompt="every product demo") を実行してから、返されたショットで compile_clips を実行します
どの場面を採用するかを自分で決める	generate_transcript(media_id) を実行してポーリングし、get_transcript(media_id, timestamped=true, segmenter="sentence") で文字起こしを取得します。範囲を選び、generate_clip を実行します（詳細は video-search スキルを参照）
複数の動画をつないだリール	compile_clips(clips=[{"video_id": "m-a", "shots": [[5, 20]]}, {"video_id": "m-b", "shots": [[0, 12]]}])
Shorts、Reels、TikTok 向けの縦型、または正方形	reframe_video(video_id, start, end, target="vertical")（"square"、"landscape"、または {"width", "height"}）。mode="smart" は被写体に合わせて追従します
サムネイル	generate_thumbnail(video_id, time_seconds=42)
MP4 ファイル	download_stream(stream_url, name="demo-reel.mp4") を実行してポーリングし、ダウンロード URL を共有します

再試行を減らすための注意事項：

• create_highlight_clip はデフォルトで発話内容に一致する場面を探します。発話が文字起こしまたはインデックス化されていない動画では、空の shots リストを返します。先に文字起こしを行ってください。返されるのはショットであり、ストリームではありません。compile_clips でレンダリングしてください。
• reframe_video は時間がかかります。必ずユーザーが希望する区間の start と end を指定してください。新しい動画がコレクションに保存されます。字幕や追加のカットは、新しい m- ID の動画に対して行います。一部のサーバーでは、最初の done の応答に reframe_id しか含まれず、新しい動画が後から表示されることがあります。同じ output_url をポーリングし続け、最大約 5 分間、list_videos に新しいエントリーが表示されるか確認してください。動画が表示されない場合は、縦型のカットは VideoDB 側でまだレンダリング中であると伝え、すぐに利用できるよう、同じ範囲の横型クリップを generate_clip で作成して提示してください。
• クリップに字幕を付ける場合：先にリフレームし、新しい動画で generate_transcript を実行してから、add_subtitles を実行します（video-subtitles スキル）。
• ユーザーが指定した mm:ss 形式のタイムスタンプは、呼び出しの前に秒に変換します。

納品します。 player_url と使用した範囲を共有し、MP4 も提供できることを伝えます。

Python SDK を使う場合（Claude Code）

import videodb が失敗する場合は、まず /videodb:setup でセットアップします。完全なリファレンス：${CLAUDE_PLUGIN_ROOT}/python/SKILL.md および ${CLAUDE_PLUGIN_ROOT}/python/reference/editor.md。

from dotenv import load_dotenv; load_dotenv(".env")
import videodb
from videodb import ReframeMode
conn = videodb.connect(); coll = conn.get_collection()
video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")
stream_url = video.generate_stream(timeline=[(10, 30), (45, 60)])        # ranges joined, no re-encode
vertical = video.reframe(start=10, end=30, target="vertical", mode=ReframeMode.smart)
print(f"https://console.videodb.io/player?url={stream_url}")