影片理解技能
此技能使用 z-ai-web-dev-sdk 套件提供專業的影片理解功能,使 AI 模型能夠分析、描述與提取影片內容中的資訊,包括動作、時間序列與場景變化。
技能路徑
技能位置:{project_path}/skills/video-understand
此技能位於您專案中的上述路徑。
參考腳本:範例測試腳本位於 {技能位置}/scripts/ 目錄,供快速測試與參考。請參閱 {技能位置}/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) - 音訊視訊交錯格式
- 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;
}