video-understand

视频理解

支持多提供商的视频理解，具备自动回退和模型选择功能。

快速开始

# Check available providers
python3 scripts/check_providers.py

# Process a video (auto-selects best provider)
python3 scripts/process_video.py "https://youtube.com/watch?v=..."
python3 scripts/process_video.py /path/to/video.mp4

# Custom prompt
python3 scripts/process_video.py video.mp4 -p "List all products shown with timestamps"

# Use specific provider/model
python3 scripts/process_video.py video.mp4 --provider openrouter -m google/gemini-3-pro-preview

# List available models
python3 scripts/process_video.py --list-models

提供商优先级

自动选择当前可用的最佳提供商：

优先级	提供商	能力	环境变量	默认模型
1	Gemini	完整视频分析	GEMINI_API_KEY	gemini-3-flash-preview
2	Vertex AI	完整视频分析	GOOGLE_APPLICATION_CREDENTIALS	gemini-3-flash-preview
3	OpenRouter	完整视频分析	OPENROUTER_API_KEY	google/gemini-3-flash-preview
4	FFMPEG	视频帧 + ASR	无（需要 ffmpeg + whisper）	scene
5	OpenAI	仅 ASR	OPENAI_API_KEY	whisper-1
6	AssemblyAI	ASR + 分析	ASSEMBLYAI_API_KEY	best
7	Deepgram	ASR	DEEPGRAM_API_KEY	nova-2
8	Groq	ASR（快速）	GROQ_API_KEY	whisper-large-v3-turbo
9	本地 Whisper	ASR（离线）	无	base

完整视频分析 = 视觉 + 音频分析。视频帧 + ASR = 提取的视频截图 + 音频转录（免费、离线）。ASR = 仅音频转录。

CLI 选项

python3 scripts/process_video.py [OPTIONS] SOURCE

Arguments:
  SOURCE              YouTube URL, video URL, or local file path

Options:
  -p, --prompt TEXT   Custom prompt for video understanding
  --provider NAME     Force specific provider
  -m, --model NAME    Force specific model
  --asr-only          Force ASR-only mode (skip visual analysis)
  -o, --output FILE   Write JSON to file instead of stdout
  -q, --quiet         Suppress progress messages
  --list-models       Show available models per provider
  --list-providers    Show available providers as JSON

模型选择

每个提供商都支持多个模型。使用 --list-models 查看选项：

python3 scripts/process_video.py --list-models

OpenRouter 模型：

• google/gemini-3-flash-preview（默认）- 快速，免费层级
• google/gemini-3-pro-preview - 更高质量

Gemini 模型：

• gemini-3-flash-preview（默认）- 最新、快速
• gemini-3-pro-preview - 最高质量
• gemini-2.5-flash - 稳定的生产环境回退选项

本地 Whisper 模型：

• tiny、base（默认）、small、medium、large、large-v3

FFMPEG 模式（视频帧提取策略）：

• scene（默认）- 在场景切换时提取视频帧（智能、高效）
• keyframe - 仅提取 I 帧（最快）
• interval - 按固定间隔提取视频帧（可预测）

快速参考

任务	参考文档
设置和 API 密钥	setup-guide.md
使用 Gemini 分析视频	gemini.md
使用 OpenRouter	openrouter.md
FFMPEG 视频帧（免费）	ffmpeg-frames.md
ASR 提供商	asr-providers.md
输出 JSON 架构	output-format.md
视频来源和下载	video-sources.md

验证设置

python3 scripts/setup.py  # Check dependencies and API keys

输出格式

所有提供商都会返回格式一致的 JSON：

{
  "source": {
    "type": "youtube|url|local",
    "path": "...",
    "duration_seconds": 120.5,
    "size_mb": 15.2
  },
  "provider": "openrouter",
  "model": "google/gemini-3-flash-preview",
  "capability": "full_video",
  "response": "...",
  "transcript": [{"start": 0.0, "end": 2.5, "text": "..."}],
  "text": "Full transcript..."
}

功能

• 根据可用的 API 密钥自动选择提供商
• 为每个提供商选择模型，并提供合理的默认值
• 稳健的路径处理，支持 macOS 特殊字符和 Unicode
• 进度输出（使用 -q 启用静默模式）
• 针对 API 限制的文件大小警告
• 按需自动转换视频格式
• 支持 YouTube URL（直接使用或通过下载）

要求

完整视频理解：

pip install google-generativeai  # Gemini
pip install openai               # OpenRouter

ASR 回退：

brew install yt-dlp ffmpeg       # Video tools
pip install openai               # OpenAI Whisper
pip install groq                 # Groq Whisper
pip install assemblyai           # AssemblyAI
pip install deepgram-sdk         # Deepgram
pip install openai-whisper       # Local Whisper