gemini-stt

核心用法

Gemini STT 是一个轻量级命令行工具，专门用于将音频文件转录为文本。它通过调用 Google Gemini API 或 Vertex AI 实现语音识别，默认采用 gemini-2.0-flash-lite 模型以确保最快的转录速度。用户只需提供音频文件路径，工具会自动检测认证方式（优先尝试 Application Default Credentials，其次检查 GEMINI_API_KEY 环境变量），无需复杂的配置即可工作。

该技能支持多种音频格式，包括 Telegram 语音消息常用的 .ogg、.opus，以及通用的 .mp3、.wav 和 .m4a。通过命令行参数，用户可以灵活选择不同的 Gemini 模型（从轻量级的 Flash Lite 到高质量的 Pro 版本），或强制使用 Vertex AI 并指定特定的 GCP 项目和区域。

显著优点

零依赖架构是该技能最突出的特点。它仅使用 Python 3.10+ 标准库（urllib、json、base64、os、subprocess 等），无需安装任何第三方包，避免了依赖冲突和供应链攻击风险。

双重认证支持提供了极大的灵活性：对于 Google Cloud 用户，可以通过 gcloud auth application-default login 使用 ADC 认证，无需管理 API 密钥；对于普通用户，则可以直接设置 GEMINI_API_KEY 快速开始使用。

智能自动检测机制简化了使用流程，工具会自动识别认证方式并选择相应的 API 端点。此外，完善的 MIME 类型白名单验证和错误处理机制确保了输入安全，避免因文件格式错误或网络问题导致的崩溃。

潜在缺点与局限性

作为 T3 来源的个人开发者项目，虽然代码经过安全审计，但长期维护性和社区支持可能不如企业级项目。此外，隐私合规性是需要重点考虑的因素：所有音频内容必须发送至 Google 的云端 API 进行处理，不适合处理高度敏感或机密音频。

功能层面，该工具仅提供基础的转录功能，缺乏说话人分离、时间戳标记、实时流式转录等高级特性。对于离线环境或无法访问 Google API 的网络环境，该工具完全无法使用。

适合的目标群体

该技能特别适合以下用户：需要处理 Telegram 语音消息或播客内容的开发者；使用 Clawdbot 构建自动化工作流的技术用户；寻求轻量级、无依赖音频转录方案的 Python 开发者；以及已经使用 Google Cloud 或 Gemini API 的现有用户。

对于需要批量处理音频文件、构建语音转文字自动化流程，或希望在本地环境中快速部署 STT 功能而不想处理复杂依赖关系的用户，这是一个理想的选择。

使用风险

数据隐私风险是最主要的考虑：音频文件内容会被 base64 编码并发送至 Google 服务器，用户需确保拥有处理这些音频的合法权利，并了解 Google 的数据处理条款。

认证配置风险方面，虽然工具本身不存储 API 密钥，但用户需要妥善保管 GEMINI_API_KEY 或 gcloud 凭证，避免通过不安全的命令历史或日志泄露敏感信息。

网络依赖性意味着转录质量和速度受网络连接影响，大文件上传可能耗时较长，且存在 API 限流或服务的可用性风险。建议在生产环境中添加重试机制和超时配置。