介绍
# Gemini Speech-to-Text Skill
使用 Google 的 Gemini API 或 Vertex AI 转录音频文件。默认模型为 `gemini-2.0-flash-lite`，可实现最快的转录速度。
## 身份验证（任选其一）
### 选项 1：使用应用默认凭据 (ADC) 的 Vertex AI（推荐）
```bash gcloud auth application-default login gcloud config set project YOUR_PROJECT_ID ```
当 ADC 可用时，脚本将自动检测并使用它。
### 选项 2：直接使用 Gemini API 密钥
在环境变量中设置 `GEMINI_API_KEY`（例如在 `~/.env` 或 `~/.clawdbot/.env` 中）
## 环境要求
- Python 3.10+（无外部依赖） - 需配置 GEMINI_API_KEY 或配置了 ADC 的 gcloud CLI
## 支持的格式
- `.ogg` / `.opus` （Telegram 语音消息） - `.mp3` - `.wav` - `.m4a`
## 使用方法
```bash # Auto-detect auth (tries ADC first, then GEMINI_API_KEY) python ~/.claude/skills/gemini-stt/transcribe.py /path/to/audio.ogg
# Force Vertex AI python ~/.claude/skills/gemini-stt/transcribe.py /path/to/audio.ogg --vertex
# With a specific model python ~/.claude/skills/gemini-stt/transcribe.py /path/to/audio.ogg --model gemini-2.5-pro
# Vertex AI with specific project and region python ~/.claude/skills/gemini-stt/transcribe.py /path/to/audio.ogg --vertex --project my-project --region us-central1
# With Clawdbot media 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`） |
## 支持的模型
任何支持音频输入的 Gemini 模型均可使用。推荐模型：
| 模型 | 说明 | |-------|-------| | `gemini-2.0-flash-lite` | **默认。** 转录速度最快。 | | `gemini-2.0-flash` | 快速且具有成本效益。 | | `gemini-2.5-flash-lite` | 轻量级 2.5 模型。 | | `gemini-2.5-flash` | 平衡的速度和质量。 | | `gemini-2.5-pro` | 更高质量，速度较慢。 | | `gemini-3-flash-preview` | 最新的 Flash 模型。 | | `gemini-3-pro-preview` | 最新的 Pro 模型，质量最佳。 |
查看 [Gemini API Models](https://ai.google.dev/gemini-api/docs/models) 获取最新列表。
## 工作原理
1. 读取音频文件并进行 base64 编码 2. 自动检测身份验证方式： - 如果 ADC 可用（gcloud），则使用 Vertex AI 端点 - 否则，使用 GEMINI_API_KEY 直连 Gemini API 3. 将音频和转录提示词发送到所选的 Gemini 模型 4. 返回转录文本
## 集成示例
用于 Clawdbot 语音消息处理：
```bash # Transcribe incoming voice message TRANSCRIPT=$(python ~/.claude/skills/gemini-stt/transcribe.py "$AUDIO_PATH") echo "User said: $TRANSCRIPT" ```
## 错误处理
脚本将在以下情况退出并返回状态码 1，并将错误信息打印到 stderr：
- 无可用的身份验证方式（既无 ADC 也无 GEMINI_API_KEY） - 文件未找到 - API 错误 - 缺少 GCP 项目（使用 Vertex 时）
## 注意事项
- 默认使用 Gemini 2.0 Flash Lite 以实现最快转录 - 无外部 Python 依赖（仅使用标准库） - 根据文件扩展名自动检测 MIME 类型 - 如果可用，优先使用 Vertex AI 和 ADC（无需管理 API 密钥）