名称： gemini-stt
描述： 使用 Google Gemini API 或 Vertex AI 转录音频文件
元数据： {"clawdbot":{"emoji":"🎤","os":["linux","darwin"]}}

Gemini 语音转文本技能

使用 Google Gemini API 或 Vertex AI 转录音频文件。默认模型为 gemini-2.0-flash-lite，以获得最快的转录速度。

身份验证（任选其一）

选项 1：使用应用默认凭据的 Vertex AI（推荐）

gcloud auth application-default login
gcloud config set project 你的项目ID

脚本会自动检测并使用可用的应用默认凭据。

选项 2：直接使用 Gemini API 密钥

在环境变量中设置 GEMINI_API_KEY（例如，在 ~/.env 或 ~/.clawdbot/.env 文件中）

要求

• Python 3.10+（无需外部依赖）
• 配置好 GEMINI_API_KEY 或带有应用默认凭据的 gcloud CLI

支持的格式

• .ogg / .opus（Telegram 语音消息）
• .mp3
• .wav
• .m4a

使用方法

# 自动检测身份验证（先尝试应用默认凭据，再尝试 GEMINI_API_KEY）
python ~/.claude/skills/gemini-stt/transcribe.py /路径/到/音频.ogg

# 强制使用 Vertex AI
python ~/.claude/skills/gemini-stt/transcribe.py /路径/到/音频.ogg --vertex

# 指定特定模型
python ~/.claude/skills/gemini-stt/transcribe.py /路径/到/音频.ogg --model gemini-2.5-pro

# 使用特定项目和区域的 Vertex AI
python ~/.claude/skills/gemini-stt/transcribe.py /路径/到/音频.ogg --vertex --project 我的项目 --region us-central1

# 配合 Clawdbot 媒体文件使用
python ~/.claude/skills/gemini-stt/transcribe.py ~/.clawdbot/media/inbound/voice-message.ogg

选项

支持的模型

任何支持音频输入的 Gemini 模型均可使用。推荐模型：

查看 Gemini API 模型 获取最新列表。

工作原理

1. 读取音频文件并进行 Base64 编码
2. 自动检测身份验证：
   • 如果应用默认凭据可用（gcloud），则使用 Vertex AI 端点
   • 否则，使用 GEMINI_API_KEY 和直接的 Gemini API
3. 将数据发送到选定的 Gemini 模型进行转录
4. 返回转录后的文本

集成示例

用于 Clawdbot 语音消息处理：

# 转录传入的语音消息
TRANSCRIPT=$(python ~/.claude/skills/gemini-stt/transcribe.py "$AUDIO_PATH")
echo "用户说：$TRANSCRIPT"

错误处理

在以下情况下，脚本将以代码 1 退出并打印错误信息到 stderr：
* 无可用身份验证（既无应用默认凭据也无 GEMINI_API_KEY）
* 文件未找到
* API 错误
* 使用 Vertex 时缺少 GCP 项目

注意事项

• 默认使用 Gemini 2.0 Flash Lite 以获得最快的转录速度
• 无需外部 Python 依赖（仅使用标准库）
• 根据文件扩展名自动检测 MIME 类型
• 优先使用带应用默认凭据的 Vertex AI（无需管理 API 密钥）