volcengine-video-understanding

火山视频理解是一个使用字节跳动火山方舟视频理解 API 对视频进行深度理解和分析的技能。它支持通过 Files API 上传视频（推荐方式），最大支持 512MB 的视频文件，并自动进行视频预处理（FPS 采样），上传的文件可重复使用，默认存储 7 天。

用途该技能用于分析视频、理解视频内容、提取视频信息。当用户需要分析视频、理解视频内容或提取视频信息时激活此技能。

主要能力

视频上传：通过 Files API 上传本地视频（推荐，最大 512MB）。
内容理解：分析视频场景、人物、动作、情感。
视频问答：基于视频内容回答用户问题。
视频描述：自动生成视频描述和摘要。

前置要求需要设置 ARK_API_KEY 环境变量。

配置方式（推荐）复制配置模板： cp .canghe-skills/.env.example .canghe-skills/.env 编辑 .canghe-skills/.env 文件，填写你的 API Key： ARK_API_KEY=your-actual-api-key-here 或使用环境变量： export ARK_API_KEY="your-api-key"

加载优先级

系统环境变量 (process.env)
当前目录 .canghe-skills/.env
用户主目录 ~/.canghe-skills/.env

使用方式

基础视频分析（Files API 方式 - 推荐）： cd ~/.openclaw/workspace/skills/volcengine-video-understanding python3 scripts/video_understand.py /path/to/video.mp4 "描述这个视频的内容"
视频问答： python3 scripts/video_understand.py /path/to/video.mp4 "视频中出现了哪些人物？"
情感分析： python3 scripts/video_understand.py /path/to/video.mp4 "分析视频中人物的情感变化"
指定模型和帧率： python3 scripts/video_understand.py /path/to/video.mp4 "总结视频要点"
--model doubao-seed-2-0-pro-260215
--fps 2
保存结果到文件： python3 scripts/video_understand.py /path/to/video.mp4 "描述视频" --output result.json

参数说明

video_path：必填，视频文件路径。
instruction：必填，分析指令/问题。
--model：默认 doubao-seed-2-0-pro-260215，模型 ID。
--fps：默认 1，视频采样帧率（预处理）。
--output：默认 -，结果输出文件路径。

支持的模型

doubao-seed-2-0-pro-260215 (默认)
doubao-seed-2-0-lite-250728
doubao-seed-1-6-251015
其他 Seed 系列视频理解模型

分析示例示例 1：视频内容描述 python3 scripts/video_understand.py ~/Desktop/video.mp4 "详细描述这个视频的内容，包括场景、人物和动作"

示例 2：视频摘要 python3 scripts/video_understand.py ~/Desktop/video.mp4 "用3句话总结这个视频的要点"

示例 3：动作识别 python3 scripts/video_understand.py ~/Desktop/video.mp4 "视频中的人物在做什么动作？按时间顺序描述"

示例 4：场景分析 python3 scripts/video_understand.py ~/Desktop/video.mp4 "分析视频中的场景变化和环境特征"

技术细节调用流程：

上传视频：通过 Files API 上传本地视频文件，指定 FPS 预处理配置。
等待处理：等待视频预处理完成（状态变为 processed）。
创建任务：调用 Responses API 进行视频理解。
获取结果：返回分析结果。

API 格式 Files API 上传： curl https://ark.cn-beijing.volces.com/api/v3/files
-H "Authorization: Bearer $ARK_API_KEY"
-F 'purpose=user_data'
-F 'file=@video.mp4'
-F 'preprocess_configs[video][fps]=1'

Responses API 分析： { "model": "doubao-seed-2-0-pro-260215", "input": [ { "role": "user", "content": [ { "type": "input_video", "file_id": "file-xxxx" }, { "type": "input_text", "text": "用户指令" } ] } ] }

FPS 设置建议

0.3-0.5：慢节奏视频、静态场景、节省 token。
1：一般视频分析（默认）。
2-3：快速动作、细节分析。

限制

视频格式：MP4（推荐）、MOV、AVI。
文件大小：最大 512MB（Files API 方式）。
存储时间：上传的文件默认存储 7 天。
处理时间：根据视频长度和复杂度，通常 10-60 秒。

Python API 使用 from scripts.video_understand import analyze_video

result = analyze_video( file_path="/path/to/video.mp4", instruction="描述视频内容", model="doubao-seed-2-0-pro-260215", fps=1 )

提取回答

text = "" for item in result.get("output", []): if item.get("type") == "message": for content in item.get("content", []): if content.get("type") == "output_text": text = content.get("text", "") break

print(text)

错误处理常见错误及解决方案：

API Key 错误：未设置或错误，检查 ARK_API_KEY 环境变量。
文件不存在：路径错误，检查文件路径。
上传失败：文件过大或格式不支持，检查文件大小（<512MB）和格式。
处理超时：视频过长或复杂，缩短视频或降低 FPS。

适用场景适用于需要分析视频内容、理解视频、提取视频信息的场景，例如视频内容描述、视频摘要、动作识别、场景分析、情感分析、视频问答等。

限制视频格式支持 MP4（推荐）、MOV、AVI；文件大小最大 512MB（Files API 方式）；上传文件默认存储 7 天；处理时间通常 10-60 秒，视视频长度和复杂度而定。

技能介绍

提取回答