name: gemini-video-understanding description: 使用Google的Gemini API分析视频 - 描述内容、回答问题、转录音频并添加视觉描述、引用时间戳、剪辑视频和处理YouTube URL。支持9种视频格式、多种模型（Gemini 2.5/2.0）和高达2M令牌的上下文窗口（6小时视频）。 license: MIT allowed-tools:

Bash
Read
Write metadata: version: “1.0.0” author: ClaudeKit api-provider: Google Gemini requires-api-key: GEMINI_API_KEY

Gemini视频理解技能

此技能使用Google的Gemini API实现全面的视频分析，包括视频总结、问答、转录、时间戳引用等。

能力

视频总结：创建视频内容的简洁摘要
问答：回答关于视频内容的具体问题
转录：转录音频并添加视觉描述和时间戳
时间戳引用：查询视频中的特定时刻（MM:SS格式）
视频剪辑：使用起始/结束偏移处理特定片段
多视频分析：比较和分析最多10个视频（Gemini 2.5+）
YouTube支持：直接分析YouTube视频（预览功能）
自定义帧率：调整FPS采样以适应不同类型的视频

支持的格式

MP4, MPEG, MOV, AVI, FLV, MPG, WebM, WMV, 3GPP

可用模型

Gemini 2.5系列：

gemini-2.5-pro - 最佳质量，1M上下文
gemini-2.5-flash - 平衡质量/速度，1M上下文
gemini-2.5-flash-preview-09-2025 - 预览功能，1M上下文

Gemini 2.0系列：

gemini-2.0-flash - 快速处理
gemini-2.0-flash-lite - 轻量级选项

上下文窗口：

2M令牌模型：约2小时（默认）或约6小时（低分辨率）
1M令牌模型：约1小时（默认）或约3小时（低分辨率）

API密钥配置

技能按以下顺序检查GEMINI_API_KEY：

进程环境：process.env.GEMINI_API_KEY或$GEMINI_API_KEY
技能目录：.claude/skills/gemini-video-understanding/.env
项目根目录：项目根目录中的.env文件

设置方法：

# 选项1：环境变量（推荐）
export GEMINI_API_KEY="您的API密钥"

# 选项2：技能目录.env文件
echo "GEMINI_API_KEY=您的API密钥" > .claude/skills/gemini-video-understanding/.env

# 选项3：项目根目录.env文件
echo "GEMINI_API_KEY=您的API密钥" > .env

获取API密钥：https://aistudio.google.com/apikey

使用说明

何时使用此技能

当用户要求时使用此技能：

分析、总结或描述视频内容
回答关于视频的问题
转录视频音频并添加视觉上下文
从特定时间戳提取信息
比较多个视频
处理YouTube视频内容
从视频创建测验或教育内容

基本视频分析

对于视频文件：

python .claude/skills/gemini-video-understanding/scripts/analyze_video.py \
  --video-path "/path/to/video.mp4" \
  --prompt "用3个关键点总结此视频"

对于YouTube URL：

python .claude/skills/gemini-video-understanding/scripts/analyze_video.py \
  --youtube-url "https://www.youtube.com/watch?v=VIDEO_ID" \
  --prompt "讨论的主要主题是什么？"

高级功能

视频剪辑（特定时间范围）：

python .claude/skills/gemini-video-understanding/scripts/analyze_video.py \
  --video-path "/path/to/video.mp4" \
  --prompt "总结此片段" \
  --start-offset "40s" \
  --end-offset "80s"

自定义帧率：

python .claude/skills/gemini-video-understanding/scripts/analyze_video.py \
  --video-path "/path/to/video.mp4" \
  --prompt "分析快速动作" \
  --fps 5

转录带时间戳：

python .claude/skills/gemini-video-understanding/scripts/analyze_video.py \
  --video-path "/path/to/video.mp4" \
  --prompt "转录音频并添加时间戳和视觉描述"

多视频（仅Gemini 2.5+）：

python .claude/skills/gemini-video-understanding/scripts/analyze_video.py \
  --video-paths "/path/video1.mp4" "/path/video2.mp4" \
  --prompt "比较这两个视频并突出差异"

模型选择：

python .claude/skills/gemini-video-understanding/scripts/analyze_video.py \
  --video-path "/path/to/video.mp4" \
  --prompt "详细分析" \
  --model "gemini-2.5-pro"

脚本参数

必需（之一）：
  --video-path PATH           本地视频文件路径
  --youtube-url URL           YouTube视频URL
  --video-paths PATH [PATH..] 多个视频路径（Gemini 2.5+）

必需：
  --prompt TEXT              分析提示/问题

可选：
  --model NAME               使用的模型（默认：gemini-2.5-flash）
  --start-offset TIME        视频剪辑起始时间（例如："40s"、"1m30s"）
  --end-offset TIME          视频剪辑结束时间（例如："80s"、"2m"）
  --fps NUMBER               帧采样率（默认：1）
  --output-file PATH         将响应保存到文件
  --verbose                  显示详细处理信息

常见用例

1. 视频总结

提示："用时间戳总结此视频的3个关键点"

2. 教育内容

提示："基于此视频创建5个问题及答案的测验"

3. 时间戳特定问题

提示："在01:15发生了什么，与02:30的主题有何关系？"

4. 转录

提示："转录此视频的音频，为突出事件添加时间戳和视觉描述"

5. 内容比较

提示："比较这两个产品演示视频。哪个更清晰地解释功能？"

6. 动作检测

提示："列出此教程视频中执行的所有动作及其时间戳"

速率限制与配额

免费层（每模型）：

10-15 RPM（每分钟请求数）
1M-4M TPM（每分钟令牌数）
1,500 RPD（每天请求数）

YouTube限制：

免费层：每天8小时YouTube视频
付费层：无基于长度的限制
仅公共视频（无私人/未列出视频）

存储（文件API）：

每个项目20GB
每个文件2GB
48小时保留期

令牌计算

视频令牌取决于分辨率：

默认分辨率：每秒视频约300令牌
低分辨率：每秒视频约100令牌

示例： 10分钟视频 = 600秒 × 300令牌 = 约180,000令牌

错误处理

常见错误及解决方案：

错误	原因	解决方案
400 Bad Request	无效视频格式或损坏文件	检查文件格式和完整性
403 Forbidden	无效/缺失API密钥	验证GEMINI_API_KEY配置
404 Not Found	文件URI未找到	确保文件已上传且激活
429 Too Many Requests	速率限制超出	实现退避，升级到付费层
500 Internal Error	服务器端问题	使用指数退避重试

最佳实践

使用文件API处理大于20MB的视频 - 比内联数据更可靠
等待文件处理 - 轮询直到状态为ACTIVE再进行分析
优化FPS - 对于静态内容使用较低FPS以节省令牌
剪辑长视频 - 处理特定片段而非整个视频
缓存上下文 - 重用上传的文件进行多个查询
批处理 - 在一个请求中处理多个短视频（2.5+）
具体提示 - 精确指定要提取的内容

实现说明

对于Claude代码：

当用户请求视频分析时：

首先检查API密钥可用性使用辅助脚本
确定视频源：本地文件、YouTube URL或多个视频
选择合适模型基于需求（默认：gemini-2.5-flash）
运行分析脚本使用适当参数
解析并清晰呈现结果给用户
优雅处理错误并提供有用建议

文件API工作流：

对于大于20MB或可重用内容：

使用文件API上传视频（脚本自动处理）
等待ACTIVE状态（脚本包含轮询）
使用文件URI进行分析
文件在48小时后自动删除

内联数据工作流：

对于小于20MB的视频：

将视频文件读取为字节
Base64编码以用于API
在generateContent请求中发送
单次使用，无需上传

示例工作流

工作流1：YouTube视频总结

# 用户："分析此YouTube教程视频"
python .claude/skills/gemini-video-understanding/scripts/analyze_video.py \
  --youtube-url "https://www.youtube.com/watch?v=abc123" \
  --prompt "创建结构化总结：1) 主要主题，2) 关键要点，3) 推荐受众"

工作流2：采访转录

# 用户："用时间戳转录此采访"
python .claude/skills/gemini-video-understanding/scripts/analyze_video.py \
  --video-path "interview.mp4" \
  --prompt "转录此采访，添加说话者标签、时间戳以及手势或展示幻灯片的视觉描述"

工作流3：产品比较

# 用户："比较这两个产品演示视频"
python .claude/skills/gemini-video-understanding/scripts/analyze_video.py \
  --video-paths "demo1.mp4" "demo2.mp4" \
  --model "gemini-2.5-pro" \
  --prompt "比较这些产品演示：展示的功能、演示质量、解释清晰度和整体效果"

故障排除

API密钥未找到：

# 检查API密钥检测
python .claude/skills/gemini-video-understanding/scripts/check_api_key.py

视频太大：

错误：请求大小超过20MB
解决方案：脚本自动使用文件API处理大视频

处理超时：

错误：文件未达到ACTIVE状态
解决方案：检查视频完整性，尝试较小文件或不同格式

速率限制错误：

错误：429 Too Many Requests
解决方案：重试前等待，或升级到付费层

附加资源

API文档：https://ai.google.dev/gemini-api/docs/video-understanding
文件API指南：https://ai.google.dev/gemini-api/docs/vision#uploading-files
速率限制：https://ai.google.dev/gemini-api/docs/rate-limits
定价：https://ai.google.dev/pricing
获取API密钥：https://aistudio.google.com/apikey

版本历史

1.0.0 (2025-10-26)：初始版本，具备完整的视频理解能力