openrouter-transcribe

核心用法

openrouter-transcribe 是一款命令行音频转录工具，通过调用 OpenRouter 的聊天补全 API 实现语音转文字。用户只需执行 {baseDir}/scripts/transcribe.sh /path/to/audio.m4a 即可快速获取转录结果。工具支持多种自定义选项，包括指定模型（默认 google/gemini-2.5-flash）、添加转录提示词（如说话人标签）、输出到文件以及设置调用者标识便于在 OpenRouter 后台追踪用量。

显著优点

技术实现简洁可靠：工具采用 ffmpeg 将音频转换为标准 WAV 格式（单声道、16kHz），经 base64 编码后通过 HTTPS 发送至 OpenRouter API，流程透明可控。脚本使用 set -euo pipefail 严格模式，配合完善的错误处理机制，确保执行稳定性。

兼容性与灵活性兼备：支持任意音频能力的 OpenRouter 模型，用户可根据需求切换 Gemini、GPT-4o-audio-preview 等不同厂商的模型。同时妥善处理大文件场景，通过临时文件而非命令行参数传递数据，避免 "argument list too long" 错误。

安全设计到位：临时目录使用 mktemp -d 创建并配合 trap 机制确保清理，无敏感信息硬编码，API Key 需用户主动配置，符合最小权限原则。

潜在缺点与局限性

网络依赖性强：完全依赖 OpenRouter 云端服务，离线环境无法使用，且受 API 可用性和响应速度制约。大文件或网络不稳定时可能出现超时或失败。

隐私与成本考量：音频文件需上传至第三方服务器处理，不适合处理机密或敏感内容。同时产生 OpenRouter API 调用费用，高频或大批量使用需关注成本。

功能边界有限：专注于转录单一任务，不支持实时流式转录、多语言自动检测、说话人分离等高级功能，复杂场景需配合其他工具。

适合的目标群体

• 开发者与技术人员：需要集成音频转录到自动化工作流或脚本管道
• 内容创作者与播客制作者：快速生成采访、会议、播客的文本稿
• 研究人员与学生：处理访谈录音、课堂录音等学术资料
• 小型团队：低成本、轻量化的语音内容处理方案

使用风险

• 数据外泄风险：音频内容上传至 OpenRouter 服务器，需确保内容脱敏或已获得授权
• API 依赖风险：服务可用性、定价策略变更可能影响长期使用
• 成本不可控：按量计费模式下，大文件或高频调用可能产生意外费用
• 格式兼容性：虽支持常见格式，但极端编码或损坏文件可能导致转录失败

核心用法

openrouter-transcribe 是一款基于 Bash 的音频转录 Skill，通过调用 OpenRouter API 的聊天补全端点，利用 Gemini 2.5 Flash、GPT-4o-audio 等支持音频输入的模型完成语音转文字。核心工作流为：使用 ffmpeg 将输入音频转换为单声道 16kHz WAV 格式 → Base64 编码 → 通过 curl 发送至 https://openrouter.ai/api/v1/chat/completions → 解析返回的 JSON 提取转录文本。

典型调用

{baseDir}/scripts/transcribe.sh /path/to/audio.m4a

关键功能

• --model 切换底层模型（默认 google/gemini-2.5-flash，可选 openai/gpt-4o-audio-preview 等）
• --prompt 注入自定义指令，如“添加说话人标签”
• --out 指定输出文件，默认 stdout
• --title 自定义 X-Title Header，便于 OpenRouter 后台追踪调用来源

配置方式

• 环境变量：OPENROUTER_API_KEY
• 配置文件：~/.clawdbot/clawdbot.json 的 skills.openrouter-transcribe.apiKey 字段

显著优点

1. 模型选择灵活：不绑定单一厂商，可在 Gemini、GPT-4o-audio 等模型间自由切换，按需平衡成本与质量。
2. 零依赖部署：仅依赖系统标准工具（curl、ffmpeg、base64、jq），无 Python/Node 运行时负担，适合 CI/CD 或容器化场景。
3. 安全编码实践：启用 set -euo pipefail 严格模式；API Key 强制从环境变量或配置文件读取，无硬编码；临时目录通过 mktemp -d 创建并配合 trap 自动清理，避免敏感音频残留。
4. 工程细节周全：针对 macOS mktemp 后缀问题规避了格式识别错误；通过 --rawfile 和 @file 方式绕过 shell 参数长度限制，支持大文件处理。
5. 透明可追溯：内置 X-Title 与 HTTP-Referer Header，用户可在 OpenRouter Dashboard 清晰识别调用来源。

潜在缺点与局限性

• 隐私敏感场景受限：音频数据需经 Base64 编码后上传至 OpenRouter 服务器，无法离线纯本地处理，不适合涉密或强隐私合规场景。
• 成本与速率限制：依赖 OpenRouter 计费策略，长音频或大流量场景可能产生显著费用；受限于第三方 API 速率限制与可用性。
• 格式与大小约束：虽内部转换为 WAV，但极罕见格式可能仍失败；超大文件虽通过文件方式规避参数限制，但未内置大小校验，极端情况下可能导致 API 拒绝或长时间等待。
• 无说话人分离内置：需通过 --prompt 手动引导模型输出说话人标签，非原生 diarization，效果依赖模型指令遵循能力。

适合人群

• 开发者与自动化工程师：需要快速集成音频转录到 Shell 工作流或 CI 流水线
• 播客与内容创作者：批量处理录制文件，生成可搜索文字稿
• 研究人员：需要灵活切换模型以对比转录质量与成本
• 隐私敏感度中等、可接受云端处理的个人或团队用户

常规风险

• 数据外泄风险：音频内容上传至 OpenRouter，需确认其隐私政策与数据处理条款符合自身合规要求。
• API 密钥泄露：若环境变量或配置文件权限配置不当（如 0644），多用户系统存在密钥泄露风险；建议设置为 0600。
• 命令注入残余：文件名虽经引号保护，但未显式过滤控制字符，极端构造的恶意文件名仍存在理论注入可能（风险等级：低）。
• 网络超时挂起：当前 curl 调用未设置 --max-time，在网络异常时可能长时间无响应。