影片理解技能
此技能使用 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 <text>:必要 - 關於影片的問題或指示--image, -i <URL 或路徑>:選用 - 影片 URL 或本機檔案路徑(儘管名稱如此,但同樣適用於影片)--thinking, -t:選用 - 啟用思考鏈推理以進行複雜分析(預設:停用)--output, -o <path>:選用 - 輸出檔案路徑(JSON 格式)--stream:選用 - 即時串流回應
支援的影片格式
- MP4 (.mp4) - 最廣泛支援的格式
- AVI (.avi) - 音訊影片交錯格式
- MOV (.mov) - QuickTime 格式
- WebM (.webm) - 網路最佳化格式
- MKV (.mkv) - Matroska 格式
- FLV (.flv) - Flash 影片格式
何時使用 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;
}
// 使用方式
const footballAnalysis = await analyzeSportsVideo(
'https://example.com/football.mp4',
'足球'
);
const anySportAnalysis = await analyzeSportsVideo(
'https://example.com/game.mp4'
);
最佳實踐
- 影片長度:對於超過 10 分鐘的影片,考慮分段或要求摘要。較短的影片會產生更準確的分析。
- 影片品質:更高解析度的影片通常會產生更好的分析結果,但可能需要更長的處理時間。
- 提示工程:提示越具體,分析結果越好。包括您希望回答的具體問題。
- 限制:此技能提供影片的基於 AI 的分析,可能會錯過非常短的動作或非常小的細節。對於關鍵分析,請交叉參考其他來源。
- 錯誤處理:在生產程式碼中始終實作適當的錯誤處理和重試邏輯。
- 快取:對於經常分析的影片,考慮快取結果以減少 API 使用量。