Gemini STT

核心用法

gemini-stt 是一个轻量级命令行音频转录工具，通过调用 Google Gemini API 将语音文件转换为文本。默认采用 gemini-2.0-flash-lite 模型，在速度与成本间取得最佳平衡。

基本命令：

python ~/.claude/skills/gemini-stt/transcribe.py /path/to/audio.ogg

支持通过 --model 参数切换至更高质量的 Pro 系列模型。兼容 Telegram 语音消息（.ogg/.opus）、.mp3、.wav、.m4a 等主流格式，自动识别 MIME 类型。

显著优点

• 零依赖设计：仅使用 Python 标准库（base64、urllib、json），无需安装额外包
• 极速响应：Flash Lite 模型针对低延迟优化，适合实时场景
• 模型灵活：7 档模型可选，从极速到高精度全覆盖
• 格式友好：原生支持 Telegram 生态的 .ogg 语音消息
• Clawdbot 集成：专为机器人工作流设计，支持 ~/.clawdbot/media/inbound/ 路径

潜在局限

• API 依赖：需稳定网络连接至 Google 服务器，离线不可用
• 成本累积：高频调用产生 Gemini API 费用，无本地兜底方案
• 隐私考量：音频数据上传至 Google 云端处理，敏感内容需谨慎
• 错误处理：仅返回 stderr 退出码 1，无结构化错误码或重试机制
• 长音频限制：受 Gemini API 上下文窗口与速率限制约束

适合人群

• Telegram 机器人开发者（Clawdbot 用户）
• 需要快速原型语音功能的 Python 开发者
• 追求极简部署、不愿维护复杂依赖的技术用户
• 已持有 Google AI Studio / Vertex AI 凭据的 Gemini 生态用户

常规风险

• 密钥泄露：GEMINI_API_KEY 以环境变量存储，需确保 ~/.env 文件权限正确（建议 600）
• 模型漂移：Google 频繁更新模型版本，默认模型未来可能被弃用
• 输出不可控：大语言模型可能产生幻觉或格式不一致的转录结果
• 计费突增：预览版模型（gemini-3-*-preview）定价可能变动，生产环境建议锁定稳定版本

核心用法

Gemini-STT 是一个轻量级 Python 脚本，专用于调用 Google Gemini 模型进行音频转文字。用户通过命令行指定音频文件路径即可启动转录，默认使用 gemini-2.0-flash-lite 模型以保证极速响应。支持 .ogg/.opus（Telegram 语音消息）、.mp3、.wav、.m4a 等常见格式，通过 MIME 类型自动识别。高级用户可通过 --model 参数切换至 gemini-2.5-pro 等更强模型，以换取更高准确率在复杂场景下的表现。

显著优点

1. 零外部依赖：仅使用 Python 3 标准库（urllib、argparse、base64 等），彻底杜绝供应链攻击风险，部署即拷即用。
2. 模型选择灵活：覆盖 Gemini 2.0/2.5/3.0 系列从 Lite 到 Pro 的全梯队，用户可按需权衡速度与质量。
3. 安全传输：API 通信强制 HTTPS（TLS 1.2+），密钥通过环境变量注入，无硬编码凭证。
4. 轻量集成：输出纯文本，便于 Shell 管道与自动化工作流（如 Clawdbot 语音消息处理）。

潜在缺点与局限性

• 数据出境：音频内容需 Base64 编码后上传至 Google 服务器，对隐私敏感场景不适用。
• 无离线能力：完全依赖云端 API，网络波动或配额耗尽将导致服务中断。
• 缺乏高级功能：无说话人分离、时间戳标记、实时流式转录等企业级特性。
• T3 来源可信度：个人开发者维护，无组织背书，长期维护与合规审计存在不确定性。

适合人群

• 需要快速转录 Telegram/即时通讯语音消息的个人用户
• 轻量级会议记录、播客字幕生成的内容创作者
• 已持有 Gemini API Key、寻求零依赖工具的开发者与运维人员

常规风险

| 风险类别 | 说明 |

|---------|------|

| 隐私合规 | 音频数据上传至 Google，需遵守其隐私政策；建议避免处理含 PII 或商业机密的敏感录音 |

| API 成本 | Gemini API 按 token 计费，长音频或大模型可能产生较高费用 |

| 单点故障 | 无本地降级方案，API 限流或故障时服务完全不可用 |