视频理解技能
此技能使用 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 或本地文件路径(尽管名称中有 image,但也适用于视频)--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;
}
会议视频分析
import ZAI from 'z-ai-web-dev-sdk';
async function analyzeMeetingVideo(videoUrl) {
const zai = await ZAI.create();
const prompt = `分析此会议录制内容:
1. 会议议程和讨论主题
2. 与会者(发言者人数及其角色)
3. 关键决策和行动项
4. 任何视觉辅助工具(幻灯片、白板、图表)
5. 会议节奏(是否高效,是否偏离主题)
6. 主要结论
7. 跟进的项目和截止日期`;
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 analyzeSurveillanceVideo(videoUrl) {
const zai = await ZAI.create();
const prompt = `分析此监控录像:
1. 检测任何运动或活动
2. 识别视频中的人员
3. 标注可疑行为或异常事件
4. 记录事件时间线
5. 识别安全风险
6. 描述环境条件(光照、天气、时间)
7. 补充观察或建议`;
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;
}