動画理解スキル
このスキルは、z-ai-web-dev-sdk パッケージを使用した専用の動画理解機能を提供し、AIモデルが動画コンテンツの分析、説明、情報抽出(モーション、時間的シーケンス、シーンチェンジを含む)を可能にします。
スキルパス
スキル場所: {project_path}/skills/video-understand
このスキルは、プロジェクト内の上記パスに配置されています。
参照スクリプト: テストと参照用のサンプルテストスクリプトは {Skill Location}/scripts/ ディレクトリにあります。実際の使用例については、{Skill Location}/scripts/video-understand.ts を参照してください。
概要
動画理解は動画コンテンツ分析に特化し、以下の機能を提供します:
- 動画シーンの理解と説明
- アクションとモーションの検出
- 時間的シーケンス分析
- 動画内のイベント検出
- 動画コンテンツの要約
- シーンチェンジ検出
- フレーム間の人物・物体追跡
- オーディオビジュアルコンテンツ分析(該当する場合)
重要: 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 <テキスト>: 必須 - 動画に関する質問または指示--image, -i <URLまたはパス>: オプション - 動画URLまたはローカルファイルパス(名前は異なりますが、動画でも機能します)--thinking, -t: オプション - 複雑な分析のための思考連鎖推論を有効にする(デフォルト: 無効)--output, -o <パス>: オプション - 出力ファイルパス(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;
}