Doubao ASR / 豆包语音转写

核心用法

Doubao ASR 调用字节跳动火山引擎「豆包录音文件识别模型2.0」API，实现高质量音频文件转文字。核心流程为：上传音频至 Volcengine TOS 对象存储 → 提交转写任务 → 轮询获取结果。支持通过命令行工具 transcribe.py 直接调用，可处理本地文件或公网 URL，输出带说话人标签的文本或 JSON 格式结果。

关键功能参数：

• --out：指定输出文件路径
• --json：输出结构化 JSON（含时间戳、置信度）
• --no-speakers：关闭说话人分离
• --format：显式指定音频格式
• 直接传入 URL 可跳过上传步骤

显著优点

1. 中文识别准确率顶尖：基于字节跳动 Seed-ASR 2.0，对普通话、粤语、四川话等方言优化充分
2. 多语言支持：覆盖 13+ 种语言
3. 说话人分离：内置 speaker diarization，自动区分不同说话人
4. 隐私合规：音频通过预签名 URL 上传至用户自有 TOS 桶，数据停留于火山引擎内部
5. 灵活输入：支持本地文件路径或直接 URL，免去重复上传

潜在缺点与局限

1. 非实时处理：仅支持录制文件转写，不支持流式/实时语音识别
2. 配置门槛高：需配置 5 项环境变量，涉及 IAM、TOS、ASR 三个控制台，步骤繁琐
3. 区域限制敏感：海外服务器若误配 cn-beijing 区域，上传速度暴跌至 ~15KB/s
4. 文件大小限制：单文件上限 512MB / 5 小时
5. 无内置音频处理：不支持降噪、音量归一化等预处理

适合人群

• 需要高精度中文语音转写的研究者、记者、律师
• 处理会议录音、访谈、播客的内容创作者
• 已有火山引擎账号、能接受一定配置复杂度的企业用户
• 对数据隐私有要求，希望音频不出境的用户

常规风险

1. 密钥泄露风险：VOLCENGINE_SECRET_ACCESS_KEY 与 API Key 需妥善保管，避免硬编码提交至代码仓库
2. 存储桶权限配置错误：若 TOS 桶策略未设为「文件夹读写」，将导致 403 上传失败
3. 旧版控制台陷阱：误从 /speech/app 获取 API Key 会导致认证失败，必须使用新版 /speech/new/
4. 跨区域流量成本：海外服务器配错区域虽能工作，但可能产生额外跨境流量费用
5. 临时文件残留：脚本上传后是否自动清理 TOS 中的临时音频文件，需用户自行确认实现

核心用法

豆包语音转写（Doubao ASR）是一款基于字节跳动火山引擎Seed-ASR 2.0标准的录音文件识别技能，专为中文语音识别场景优化。用户可通过Discord或WhatsApp向OpenClaw发送音频文件，系统将自动调用豆包API完成转写。技能支持命令行直接调用，基础用法为：

python3 {baseDir}/scripts/transcribe.py /path/to/audio.m4a

默认配置已启用说话人分离（speaker diarization），输出带标签的转写文本。高级功能包括JSON格式输出、自定义保存路径、禁用说话人分离，以及直接传入URL跳过上传步骤。支持的音频格式涵盖WAV、MP3、MP4、M4A、OGG、FLAC，单文件上限512MB/5小时。

技术实现上，由于豆包API仅接受URL形式的音频输入，技能通过预签名URL将音频安全上传至用户专属的火山引擎TOS对象存储，全程不经过第三方服务。上传完成后提交转写任务，通常1-3分钟即可返回10分钟音频的完整结果。

显著优点

中文识别精度业界领先：Seed-ASR 2.0在普通话、粤语、四川话等方言场景下表现优异，识别准确率显著优于国际主流ASR服务。

企业级安全架构：音频数据通过TLS 1.2+加密传输，存储于用户自主管理的TOS桶内，配合最小权限的桶策略授权，避免IAM过度授权风险。凭证全部采用环境变量管理，无硬编码安全隐患。

灵活的部署模式：支持中国内地（cn-beijing）与海外（cn-hongkong等）多区域部署，海外服务器选择香港节点可规避跨境传输导致的性能衰减（约15KB/s→正常带宽）。

开箱即用的说话人分离：默认启用说话人标识功能，无需额外配置即可区分会议、访谈中的不同发言者。

潜在缺点与局限性

配置复杂度较高：需同时配置5项环境变量（API Key、IAM密钥对、TOS桶名及区域），涉及语音控制台、IAM控制台、TOS控制台三个独立入口，对新手存在一定学习成本。

非实时转写：仅支持录制完成的音频文件，不支持实时流式识别或直播字幕场景。

依赖外部脚本执行：Skill本身为文档型设计，核心功能依赖外部transcribe.py脚本，用户需自行确保脚本来源可信且版本匹配。

区域选择敏感：海外服务器若误选cn-beijing区域，上传速度将骤降至约15KB/s，影响大文件处理体验。

适合的目标群体

• 企业会议组织者：需将线下会议、线上访谈录音快速转为可检索文字记录
• 内容创作者与媒体人：播客、视频字幕制作，需高精度中文语音转文字
• 研究人员与学生：学术访谈、田野调查录音的批量转写与归档
• 跨国团队：支持13+语言识别，满足多语言会议记录需求
• 隐私敏感型用户：数据留存于自有云存储，非第三方SaaS模式

使用风险说明

外部脚本依赖风险：实际执行代码不在Skill包内，建议从官方渠道获取transcribe.py，执行前审查代码逻辑与网络行为。

凭证管理风险：VOLCENGINE_API_KEY等5项密钥若泄露，可能导致TOS存储桶被非法访问。建议使用专用IAM子用户、定期轮换密钥、避免在Shell历史或日志中明文暴露。

网络性能风险：跨境区域配置错误将导致上传瓶颈；建议海外用户严格遵循cn-hongkong区域指引。

服务可用性风险：依赖火山引擎API SLA，极端情况下可能出现排队延迟或区域性服务中断。