Communitygithub.com

動画理解スキル

z-ai-web-dev-sdkを使用した動画コンテンツ分析、動作認識、シーン説明を実現する専門スキルです。

動画理解スキル とは?

このスキルは、z-ai-web-dev-sdkパッケージを利用して、AIモデルが動画コンテンツを分析、説明、情報抽出するための専門的な機能を提供します。対応プラットフォームはClaude Code、Cursor、Codexなど、z-ai-web-dev-sdkをサポートするあらゆる環境です。具体的には、シーン理解、アクション・モーション検出、時間的シーケンス分析、イベント検出、動画要約、シーンチェンジ検出、フレーム間の人物・物体追跡などを行えます。CLIとSDKの両方で利用可能で、CLIは簡単な動画分析に、SDKは複雑なパイプラインやプロダクション用途に適しています。MP4、AVI、MOVなどを含む一般的な動画フォーマットをサポートし、マルチターン会話や品質評価、コンテンツモデレーションなどの高度なユースケースにも対応します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cetc2211/AcTR-app/tree/HEAD/skills/video-understand

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

動画理解スキル は何をしますか?

このスキルは、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またはローカルファイルパス(名前はimageですが、動画にも機能します)
  • --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を使用するケース:

  • 動画に関するマルチターン会話
  • 複雑な動画処理パイプライン
  • エラーハンドリングを含むプロダクションアプリケーション
  • 動画処理ロジックとのカスタム統合
  • カスタムワークフローによるバッチ動画処理

推奨アプローチ

ローカル動画でより良いパフォーマンスと信頼性を得るには、以下を検討してください:

  1. 動画をCDNにアップロードし、URLを使用する
  2. 短い動画では、キーフレームを画像に変換して分析を高速化する
  3. 長い動画では、間隔をあけてチャンク分割またはサンプリングを検討する

基本的な動画理解の実装

単一動画分析

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;
}

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

Cetc2211/AcTR-app

Generate a single-file Chinese atelier-style portfolio website (horizontal-row list + hover-reveal thumb interaction, art lishu typography "Alimama DaoLiTi" via CDN, light/dark theme, hash-routed detail pages). Takes a natural-language description of the studio (name, director, discipline, works) and outputs ONE working .html file. Runs in BOTH Claude Code (writes to ~/Desktop) and GLM / online chat (outputs HTML inline). Trigger phrases include "做个中式工作室作品集", "做个隶书作品集", "lishu-portfolio-gen ...", "做个白屋风格的作品集", or when user drags this skill folder into chat asking for an atelier-style site.

Cetc2211/AcTR-app

Premium calm-tech SaaS landing template — bilingual (CN/EN) literary voice over a dark forest-night palette with warm gold accent, Cormorant + Noto Serif SC, Three.js procedural forest hero, station-based scrolling narrative, custom cursor. Built for ambient-AI / creative-tool / philosophical SaaS, not loud commercial launch.

Cetc2211/AcTR-app

Pro-camera HUD mockup template — full-viewport black canvas wrapping a real video with monospace overlays (corner brackets, top status bar, side AF/exposure columns, bottom timecode + aperture/shutter/ISO row, vertical 8-filter wheel, animated reticle). For cinematographer portfolios, camera-app demos, LUT pack previews, filter-look auditions. NOT a TikTok/Reels mockup, NOT a storyboard, NOT a shot list, NOT a script document. The chrome wraps real footage — never a div placeholder.

Cetc2211/AcTR-app

Premium pre-launch waitlist page template — dark charcoal canvas with subtle vignette, drifting portrait video-thumbnail cards, fade-up cascades, glass nav, live-updating join counter, single email form with success/error states. Built for creative-tool / AI / niche-SaaS invite-only launches with hushed exclusive tone, not loud growth-marketing.

Cetc2211/AcTR-app

Route design-related HTML artifact tasks to the right artifact skill, reference, design system generation, or export skill.

Cetc2211/AcTR-app

Implement text-to-speech (TTS) capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to convert text into natural-sounding speech, create audio content, build voice-enabled applications, or generate spoken audio files. Supports multiple voices, adjustable speed, and various audio formats.

Cetc2211/AcTR-app

Implement AI-powered video generation capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to generate videos from text prompts or images, create video content programmatically, or build applications that produce video outputs. Supports asynchronous task management with status polling and result retrieval.

関連スキル