動画理解スキル
このスキルは、z-ai-web-dev-sdk パッケージを使用して、動画コンテンツの解析、説明、情報抽出(動作、時間的シーケンス、シーンチェンジを含む)を行うための専門的な機能を提供します。
スキルパス
スキル場所: {project_path}/skills/video-understand
このスキルは、上記のプロジェクト内のパスにあります。
参考スクリプト: テストと参考のためのサンプルテストスクリプトが {Skill Location}/scripts/ ディレクトリにあります。動作例については {Skill Location}/scripts/video-understand.ts を参照してください。
概要
Video Understanding は動画コンテンツ解析に特化しており、以下の機能を提供します。
- 動画シーンの理解と説明
- アクションとモーションの検出
- 時間的シーケンスの分析
- 動画内のイベント検出
- 動画コンテンツの要約
- シーンチェンジ検出
- フレーム間での人物や物体の追跡
- 音声・視覚コンテンツの分析(該当する場合)
重要: z-ai-web-dev-sdk はバックエンドコードでのみ使用する必要があります。クライアントサイドコードで使用しないでください。
前提条件
z-ai-web-dev-sdk パッケージは既にインストールされています。以下の例に示すようにインポートしてください。
CLI の使用法(簡単なタスク向け)
簡単な動画解析タスクには、コードを書く代わりに z-ai CLI を使用できます。これは、簡単な動画説明、テスト、自動化に最適です。
基本的な動画解析
# URLから動画を解析
z-ai vision --prompt "この動画で何が起こっているか要約してください" --image "https://example.com/video.mp4"
# 注意: 動画URLにも --image フラグを使用します
z-ai vision -p "主要なイベントを説明してください" -i "https://example.com/presentation.mp4"
ローカル動画の解析
# ローカルの動画ファイルを解析
z-ai vision -p "この動画ではどのような活動が示されていますか?" -i "./recording.mp4"
# レスポンスをファイルに保存
z-ai vision -p "詳細な要約を提供してください" -i "./meeting.mp4" -o summary.json
高度な動画解析
# 思考を有効にした複雑なシーン理解
z-ai vision \
-p "この動画を分析し、以下を特定してください: 1) 主要なイベント, 2) 人物とその行動, 3) 重要な瞬間のタイムライン" \
-i "./event.mp4" \
--thinking \
-o analysis.json
# アクション検出
z-ai vision \
-p "この動画内で人々が行ったすべてのアクションを特定してください" \
-i "./sports.mp4" \
--thinking
ストリーミング出力
# 動画解析をストリーム
z-ai vision -p "この動画コンテンツを説明してください" -i "./video.mp4" --stream
CLI パラメータ
--prompt, -p <text>: 必須 - 動画に関する質問または指示--image, -i <URL または パス>: オプション - 動画URLまたはローカルファイルパス(名前は異なりますが、動画でも機能します)--thinking, -t: オプション - 複雑な分析のための思考連鎖推論を有効にする(デフォルト: 無効)--output, -o <path>: オプション - 出力ファイルパス(JSON形式)--stream: オプション - レスポンスをリアルタイムでストリーム
対応動画形式
- MP4 (.mp4) - 最も広くサポートされている形式
- AVI (.avi) - Audio Video Interleave
- MOV (.mov) - QuickTime 形式
- WebM (.webm) - Web最適化形式
- MKV (.mkv) - Matroska 形式
- FLV (.flv) - Flash Video 形式
CLI と SDK の使い分け
CLI を使用する場合:
- 簡単な動画要約
- 単発の動画解析
- 動画理解機能のテスト
- 簡単な自動化スクリプト
- 動画説明の生成
SDK を使用する場合:
- 動画に関するマルチターン会話
- 複雑な動画処理パイプライン
- エラーハンドリングを含む本番アプリケーション
- 動画処理ロジックとのカスタム統合
- カスタムワークフローによるバッチ動画処理
推奨アプローチ
ローカル動画のパフォーマンスと信頼性を向上させるには、以下を考慮してください。
- 動画をCDNにアップロードし、URLを使用する
- 短い動画の場合は、キーフレームを画像に変換して解析を高速化する
- 長い動画の場合は、チャンク分割または一定間隔でのサンプリングを検討する
基本的な動画理解の実装
単一動画解析
import ZAI from 'z-ai-web-dev-sdk';
async function analyzeVideo(videoUrl, prompt) {
const zai = await ZAI.create();
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{
type: 'text',
text: prompt
},
{
type: 'video_url',
video_url: {
url: videoUrl
}
}
]
}
],
thinking: { type: 'disabled' }
});
return response.choices[0]?.message?.content;
}
// 使用例
const summary = await analyzeVideo(
'https://example.com/presentation.mp4',
'この動画で提示された主要なポイントを要約してください'
);
const actionDetection = await analyzeVideo(
'https://example.com/sports.mp4',
'この動画で行われているすべての運動動作を特定して説明してください'
);
動画シーン理解
import ZAI from 'z-ai-web-dev-sdk';
async function understandVideoScenes(videoUrl) {
const zai = await ZAI.create();
const prompt = `この動画を分析し、以下を提供してください:
1. 動画コンテンツの全体的な要約
2. 主要なシーンまたはセグメント(可能であればおおよそのタイムスタンプ)
3. 主要な人物またはキャラクターとその役割
4. 時系列順の重要なアクションまたはイベント
5. 設定と環境の説明
6. 全体的なムードやトーン`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' } // 詳細な分析のために有効化
});
return response.choices[0]?.message?.content;
}
// 使用例
const sceneAnalysis = await understandVideoScenes(
'https://example.com/documentary.mp4'
);
モーションとアクションの検出
import ZAI from 'z-ai-web-dev-sdk';
async function detectActions(videoUrl, specificAction = null) {
const zai = await ZAI.create();
const prompt = specificAction
? `この動画内の「${specificAction}」のすべてのインスタンスを特定してください。各インスタンスについて、いつ発生するか、どのように実行されるかの詳細を説明してください。`
: 'この動画内のすべての重要なアクションと動きを特定して説明してください。誰がいつ実行しているかを含めてください。';
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
// 使用例
const runningActions = await detectActions(
'https://example.com/sports.mp4',
'走る'
);
const allActions = await detectActions(
'https://example.com/activity.mp4'
);
イベントタイムライン抽出
import ZAI from 'z-ai-web-dev-sdk';
async function extractTimeline(videoUrl) {
const zai = await ZAI.create();
const prompt = `この動画の詳細なイベントタイムラインを作成してください:
- 重要な瞬間と遷移を特定
- おおよその時間(開始、中間、終了、または表示されている特定のタイムスタンプ)をメモ
- 各キーポイントで何が起こるかを説明
- イベント間の因果関係を特定
時系列リストとしてフォーマットしてください。`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
動画コンテンツ分類
import ZAI from 'z-ai-web-dev-sdk';
async function classifyVideo(videoUrl) {
const zai = await ZAI.create();
const prompt = `この動画コンテンツを分類してください:
1. プライマリカテゴリ(例: 教育、エンターテイメント、スポーツ、ニュース、チュートリアル)
2. サブカテゴリまたはジャンル
3. ターゲットオーディエンス
4. コンテンツスタイル(プロフェッショナル、カジュアル、ドキュメンタリーなど)
5. 主要なテーマやトピック
6. 推奨タグ(10〜15キーワード)
レスポンスは構造化されたJSONとしてフォーマットしてください。`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'disabled' }
});
const content = response.choices[0]?.message?.content;
try {
return JSON.parse(content);
} catch (e) {
return { rawResponse: content };
}
}
高度なユースケース
マルチターン動画会話
import ZAI from 'z-ai-web-dev-sdk';
class VideoConversation {
constructor() {
this.messages = [];
}
async initialize() {
this.zai = await ZAI.create();
}
async loadVideo(videoUrl, initialQuestion) {
this.messages.push({
role: 'user',
content: [
{ type: 'text', text: initialQuestion },
{ type: 'video_url', video_url: { url: videoUrl } }
]
});
return this.getResponse();
}
async askFollowUp(question) {
this.messages.push({
role: 'user',
content: [
{ type: 'text', text: question }
]
});
return this.getResponse();
}
async getResponse() {
const response = await this.zai.chat.completions.createVision({
messages: this.messages,
thinking: { type: 'disabled' }
});
const assistantMessage = response.choices[0]?.message?.content;
this.messages.push({
role: 'assistant',
content: assistantMessage
});
return assistantMessage;
}
}
// 使用例
const conversation = new VideoConversation();
await conversation.initialize();
const initial = await conversation.loadVideo(
'https://example.com/lecture.mp4',
'この講義の主なトピックは何ですか?'
);
const followup1 = await conversation.askFollowUp(
'言及された主要な概念を説明してもらえますか?'
);
const followup2 = await conversation.askFollowUp(
'これらの概念を説明するためにどのような例が使われましたか?'
);
動画品質評価
import ZAI from 'z-ai-web-dev-sdk';
async function assessVideoQuality(videoUrl) {
const zai = await ZAI.create();
const prompt = `この動画の品質を評価してください:
1. 視覚品質(解像度、明瞭さ、照明) - 1〜10で評価
2. 音声品質(音声が存在する場合) - 1〜10で評価
3. カメラワーク(安定性、フレーミング、構図) - 1〜10で評価
4. プロダクション価値(編集、トランジション、エフェクト) - 1〜10で評価
5. コンテンツの明確さ(メッセージは明確か?) - 1〜10で評価
6. ペーシング(速すぎる、遅すぎる、適切)
7. 技術的な問題(アーティファクト、ぼやけ、音声同期など)
8. 全体的な評価 - 1〜10
9. 改善のための具体的な推奨事項
各基準について詳細なフィードバックを提供してください。`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
動画コンテンツモデレーション
import ZAI from 'z-ai-web-dev-sdk';
async function moderateVideo(videoUrl) {
const zai = await ZAI.create();
const prompt = `この動画をコンテンツモデレーションのためにレビューしてください:
1. 不適切またはセンシティブなコンテンツがないか確認
2. 潜在的な安全上の懸念を特定
3. 一般的なコミュニティガイドラインに違反する可能性のあるコンテンツを指摘
4. 年齢適切性を評価
5. 見える範囲にある著作権で保護された素材(ロゴ、ブランド、音楽)を特定
6. 全体的な安全性評価: 安全 / 注意 / レビュー必須
特定された懸念事項について具体的な例を提供してください。`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}
動画トランスクリプト生成(視覚説明)
import ZAI from 'z-ai-web-dev-sdk';
async function generateVisualTranscript(videoUrl) {
const zai = await ZAI.create();
const prompt = `この動画の詳細な視覚トランスクリプトを生成してください:
- 各シーンで何が起こっているかを説明
- 画面上に表示されるテキストをメモ
- 重要な視覚要素を説明
- シーンチェンジやトランジションについて言及
- 人々の行動や表情の説明を含める
時間ベースのナレーションとしてフォーマットしてください(例: "最初に...", "次に...", "最後に...")。`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'disabled' }
});
return response.choices[0]?.message?.content;
}
スポーツ動画解析
import ZAI from 'z-ai-web-dev-sdk';
async function analyzeSportsVideo(videoUrl, sport = null) {
const zai = await ZAI.create();
const prompt = sport
? `この${sport}動画を詳細に分析してください:
1. 選手とそのポジションを特定
2. 主要なプレーと戦略を説明
3. 得点イベントや重要な瞬間をメモ
4. 選手のパフォーマンスを評価
5. ルール違反やファウルを特定
6. 試合のペースと流れを説明`
: `このスポーツ動画を分析してください:
1. 行われているスポーツを特定
2. 主要なアクションとプレーを説明
3. 得点や重要なイベントをメモ
4. 選手の動きと戦略を説明
5. 試合またはマッチの全体的な評価`;
const response = await zai.chat.completions.createVision({
messages: [
{
role: 'user',
content: [
{ type: 'text', text: prompt },
{ type: 'video_url', video_url: { url: videoUrl } }
]
}
],
thinking: { type: 'enabled' }
});
return response.choices[0]?.message?.content;
}