火山视频理解使用字节跳动火山方舟视频理解 API（doubao-seed-2-0-pro-260215 等模型）对视频进行深度理解和分析。推荐方式：Files API 上传 + Responses 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 使用方法 1. 基础视频分析（Files API 方式 - 推荐） cd ~/.openclaw/workspace/skills/volcengine-video-understanding python3 scripts/video_understand.py /path/to/video.mp4 "描述这个视频的内容" 2. 视频问答 python3 scripts/video_understand.py /path/to/video.mp4 "视频中出现了哪些人物？" 3. 情感分析 python3 scripts/video_understand.py /path/to/video.mp4 "分析视频中人物的情感变化" 4. 指定模型和帧率 python3 scripts/video_understand.py /path/to/video.mp4 "总结视频要点" \ --model doubao-seed-2-0-pro-260215 \ --fps 2 5. 保存结果到文件 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 设置建议 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 参考文档火山方舟视频理解文档 Files API 文档 Responses API 文档

安装

提取回答

text