视频理解技能
此技能使用 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 <text>:必需 - 关于视频的问题或指令--image, -i <URL 或路径>:可选 - 视频 URL 或本地文件路径(尽管命名如此,它也适用于视频)--thinking, -t:可选 - 为复杂分析启用链式推理(默认:禁用)--output, -o <path>:可选 - 输出文件路径(JSON 格式)--stream:可选 - 实时流式传输响应
支持的视频格式
- MP4 (.mp4) - 最广泛支持的格式
- AVI (.avi) - 音频视频交错格式
- MOV (.mov) - QuickTime 格式
- WebM (.webm) - 针对 Web 优化的格式
- 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;
}