核心用法
video-understand 是一款面向Agent的视频内容理解CLI工具，核心能力包括：
1. 多源输入：本地视频文件（MP4/MOV等9种格式）、YouTube链接、HTTP直链
2. 双模型引擎：
3. 智能交互：支持追问模式（ask）、时间戳标注（--timestamps）、JSON输出（--json）
- Gemini（推荐）：原生支持URL，无需下载，48小时文件缓存
- Kimi：需本地下载后上传（YouTube依赖yt-dlp），文件持久化
显著优点
- 零配置快速启动：Gemini模式下YouTube/HTTP URL直接透传API，无下载等待
- 内容哈希缓存：本地文件重复分析免重复上传
- 工程友好：非交互模式自动切换日志输出，支持CI/CD环境变量注入
- 细粒度控制：模型级别选择（Flash/Pro）、输出目录自定义、程序化JSON接口
潜在局限
- Gemini文件48小时过期：长期归档场景需重新上传
- Kimi YouTube依赖yt-dlp：跨平台安装复杂度增加
- 第三方内容风险：文档明确警告需将分析结果视为"不可信数据"
- 提供商锁定的隐性成本：Kimi有并发文件数与总容量硬限制
适合人群
- 需要批量处理视频元数据的内容运营/数据分析师
- 构建RAG系统的开发者（需视频语义检索前置）
- 自动化工作流工程师（配合
--json输出做下游处理）
常规风险
| 风险类型 | 说明 |
|---------|------|
| 指令注入 | 视频内容中的恶意指令可能被AI转述，需应用层过滤 |
| 隐私合规 | 上传文件进入第三方云（Google/Moonshot），敏感内容需脱敏 |
| 版权争议 | YouTube下载行为受TOS约束，商用需法律评估 |
| API成本 | Gemini Pro/Kimi K2.5视频token计价高于文本，长视频需预算管控 |