1实现原理 · 为什么它能做到
它把本地视频送到字节跳动火山方舟的视频理解 API，用 Seed 系列模型做深度理解与分析。
skills/canghe-volcengine-video-understanding/SKILL.md
使用字节跳动火山方舟视频理解 API（doubao-seed-2-0-pro-260215 等模型）对视频进行深度理解和分析。
注：这里在做什么：声明核心是『视频→外部多模态模型』的调用，本地只做编排与结果解析。
推荐流程为两步：Files API 上传 + Responses API 分析。
skills/canghe-volcengine-video-understanding/SKILL.md
**推荐方式**：Files API 上传 + Responses API 分析
注：这里在做什么：先把视频当文件上传（支持大文件、可复用），再以 file_id 发起理解任务。
上传是 multipart，并携带预处理 FPS 配置。
skills/canghe-volcengine-video-understanding/scripts/video_understand.py
"preprocess_configs[video][fps]": str(fps)
注：这里在做什么：让服务端按采样帧率预处理视频，平衡 token 成本与细节保留。
上传后轮询文件状态，直到 active/processed 才继续。
skills/canghe-volcengine-video-understanding/scripts/video_understand.py
if status in ["active", "processed"]:
注：这里在做什么：等待视频预处理完成，避免在未就绪时发起分析。
理解任务用 Responses API，把 input_video(file_id) 与 input_text(指令) 一起提交。
skills/canghe-volcengine-video-understanding/scripts/video_understand.py
"type": "input_video",
注：这里在做什么：把视频引用与用户问题组装成一次多模态请求。
鉴权靠环境变量 ARK_API_KEY（系统环境→当前目录 .env→用户主目录 .env）。
skills/canghe-volcengine-video-understanding/scripts/video_understand.py
return require_env_key("ARK_API_KEY")
注：这里在做什么：从宿主 common/env_utils 读取密钥，再以 Bearer 头调用火山方舟端点。
结果可解析为文本并可 --output 落盘成 JSON。
skills/canghe-volcengine-video-understanding/scripts/video_understand.py
with open(args.output, 'w', encoding='utf-8') as f:
注：这里在做什么：把 API 原始响应保存或提取 output_text，便于后处理。
默认模型与采样帧率可调（默认 doubao-seed-2-0-pro-260215 / fps=1）。
skills/canghe-volcengine-video-understanding/SKILL.md
| `--fps` | 1 | 视频采样帧率（预处理） |
注：这里在做什么：慢节奏视频可降 FPS 省 token，快动作可升 FPS 保留细节。
2核心能力
01视频内容理解（场景/人物/动作/情感）
02基于视频内容的问答
03自动生成视频描述与摘要
04Files API 上传大文件（最大 512MB）
05可指定模型与采样帧率
06等待预处理完成的轮询
07结果落盘为 JSON / 提供 Python API（analyze_video）
3外部依赖
| 类型 | 依赖 |
|---|---|
| api | 火山方舟视频理解 API（Files / Responses），模型 doubao-seed-2-0-pro-260215 等 |
| package | requests（HTTP 客户端） |
| cli | python3（运行 video_understand.py） |
4风险提醒 风险提醒：橙色 · 评估后使用
风险提醒：橙色 · 评估后使用
- 密钥与素材双重出网：需配置 ARK_API_KEY，且视频与分析指令会上传到火山方舟，涉及数据隐私与账号额度。
- 强绑定外部服务：没有离线/替代路径，火山方舟 API 变更或不可用即失效。
- 跨目录依赖：脚本相对引用 skills/common/env_utils，目录结构变化会导致 ImportError。
- 文件默认仅存 7 天，重跑需重新上传；分析结果按模型输出，可能不准确。
风险提醒：橙色，评估后使用。两条独立理由：①【读环境变量凭证】脚本 get_api_key() → require_env_key("ARK_API_KEY") 读取 ARK_API_KEY，并以 Bearer 头发送给火山方舟端点；②【用户素材送外部服务后端】视频经 Files API 上传、再以 Responses API 分析，即把本地视频与分析指令送到第三方多模态模型并消耗账号额度。按判级范式『读凭据/环境变量，或把用户素材送外部生成/服务后端』＝橙。不升红：无逆向、无冒充、无绕过防护、无安全降级（未见关闭 TLS 校验/沙箱）、无任意代码执行面；脚本结构清晰、无混淆、无硬编码密钥。
5第二遍独立确认
- [ok] 读取 ARK_API_KEY 并外发 — 脚本 get_api_key() 用 require_env_key("ARK_API_KEY")；三处请求均带 "Authorization": f"Bearer {api_key}"。
- [ok] 端点定位 — BASE_URL = "https://ark.cn-beijing.volces.com/api/v3"；风险扫描『URL/端點』与『網路請求』命中 files/responses 与脚本 requests.post/get。
- [ok] 素材上传到外部服务 — upload_video_file() 以 requests.post 到 {BASE_URL}/files 上传视频；analyze_video() 以 file_id 调 /responses。
- [ok] 无本地危险执行面 — 风险扫描『危險旗標/防護繞過』『沙箱/未受控執行』均无命中；脚本无 eval/exec、无 shell。
- [ok] 唯一写盘为 --output — 风险扫描『寫盤/產生檔案』仅命中 open(args.output, 'w', encoding='utf-8')。
- [ok] env_utils 为跨目录依赖 — 脚本 sys.path 插入 COMMON_DIR = Path(__file__).parent.parent.parent / "common"，导入 load_env/require_env_key；该模块位于 skill 目录之外，本报告仅作推测定位。
- [ok] 档位复核 — 读 env 密钥 + 用户视频出网至生成型服务 → orange；无 red 触发项。
- [ok] 元数据与 commit — commit=dd0bf355955b4c82b764740b4183c86a72ba0e0c，license=MIT（仓库根），installs=null。
6结论
适合：适合已有火山方舟 Ark 账号、需要把本地视频做内容理解/问答/摘要的开发者与内容团队，尤其是要处理较大视频文件（≤512MB）的场景。
不适合：不适合禁止视频/素材出网或对数据合规要求严格的环境；不适合无 ARK_API_KEY 或无额度者；也不适合期望离线本地推理的用户。
安装 agent 直装可复制
① 本站镜像 更新 2026-10-10
方式 A · 人下载镜像包下载 volcengine-video-understanding.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent5f1ee27839a37239…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库freestylefly / freestylefly/canghe-skills
原始 GitHubfreestylefly/canghe-skills ↗
本 skill commit
dd0bf35595许可MIT（仓库根 LICENSE）
本站信息
收录日期2026-09-06
分类内容创作
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。