Gemini Speech-to-Text Skill 是一个音频转写工具,使用 Google 的 Gemini API 或 Vertex AI 将音频文件转录为文本。默认模型为 gemini-2.0-flash-lite,以获得最快的转写速度。
用途 该技能用于将音频文件转写为文本,适用于处理语音消息、录音等音频内容的转录需求。
主要能力
- 支持多种音频格式:.ogg / .opus(Telegram 语音消息)、.mp3、.wav、.m4a
- 支持多种 Gemini 模型,包括 gemini-2.0-flash-lite(默认,最快)、gemini-2.0-flash、gemini-2.5-flash-lite、gemini-2.5-flash、gemini-2.5-pro、gemini-3-flash-preview、gemini-3-pro-preview 等
- 自动检测认证方式:优先使用 Vertex AI 的应用默认凭据(ADC),否则使用 GEMINI_API_KEY
- 自动从文件扩展名检测 MIME 类型
- 无外部 Python 依赖(仅使用标准库)
使用方式 认证(二选一): 选项 1:Vertex AI 配合应用默认凭据(推荐) gcloud auth application-default login gcloud config set project YOUR_PROJECT_ID 脚本会在可用时自动检测并使用 ADC。 选项 2:直接使用 Gemini API Key 在环境变量中设置 GEMINI_API_KEY(例如 ~/.env 或 ~/.clawdbot/.env)。
要求:
- Python 3.10+
- 配置 GEMINI_API_KEY 或已配置 ADC 的 gcloud CLI
命令行用法示例:
自动检测认证(先尝试 ADC,再尝试 GEMINI_API_KEY)
python ~/.claude/skills/gemini-stt/transcribe.py /path/to/audio.ogg
强制使用 Vertex AI
python ~/.claude/skills/gemini-stt/transcribe.py /path/to/audio.ogg --vertex
指定模型
python ~/.claude/skills/gemini-stt/transcribe.py /path/to/audio.ogg --model gemini-2.5-pro
Vertex AI 指定项目和区域
python ~/.claude/skills/gemini-stt/transcribe.py /path/to/audio.ogg --vertex --project my-project --region us-central1
处理 Clawdbot 媒体文件
python ~/.claude/skills/gemini-stt/transcribe.py ~/.clawdbot/media/inbound/voice-message.ogg
选项:
- <audio_file>:音频文件路径(必填)
- --model, -m:使用的 Gemini 模型(默认:gemini-2.0-flash-lite)
- --vertex, -v:强制使用 Vertex AI 配合 ADC
- --project, -p:GCP 项目 ID(用于 Vertex,默认取 gcloud 配置)
- --region, -r:GCP 区域(用于 Vertex,默认:us-central1)
工作原理:
- 读取音频文件并进行 base64 编码
- 自动检测认证:若 ADC 可用(gcloud),使用 Vertex AI 端点;否则使用 GEMINI_API_KEY 直连 Gemini API
- 将音频发送给所选 Gemini 模型并附带转写提示
- 返回转写文本
集成示例(Clawdbot 语音消息处理): TRANSCRIPT=$(python ~/.claude/skills/gemini-stt/transcribe.py "$AUDIO_PATH") echo "User said: $TRANSCRIPT"
错误处理: 脚本在以下情况会以退出码 1 退出并向 stderr 输出信息:
- 无可用认证(ADC 和 GEMINI_API_KEY 均无)
- 文件未找到
- API 错误
- 使用 Vertex 时缺少 GCP 项目
适用场景
- 将 Telegram 语音消息转写为文本
- 批量转写录音文件
- 集成到自动化流程中处理音频输入
限制
- 需要 Python 3.10+ 环境
- 需要配置认证(ADC 或 GEMINI_API_KEY)
- 使用 Vertex AI 时需要 GCP 项目
- 具体收费、价格、平台支持等信息暂未提供