BroadRouter

用 API 把 WhatsApp 语音消息转成文字

更新于

WhatsApp 语音消息是 .ogg 文件中的 Opus 音频,转写端点不能直接接收。先用 ffmpeg 把每个文件转成 16 kHz 单声道 WAV,再发送给 BroadNet Transcribe Arabic 或 BroadNet Transcribe,并设置正确的 language 字段。一个简短的脚本就能对整个文件夹完成这两步。

从聊天中导出语音消息(或者通过你的 WhatsApp Business 集成接收),得到的是 .ogg 文件。Meta 的 Cloud API 文档说,WhatsApp 语音消息是用 Opus 编码的 .ogg 文件。手机录音则常常是 .m4a。BroadNet 的转写端点接收 WAV 和 MP3,所以要先转换。

1. 转换单个文件

ffmpeg -i voice-note.ogg -ar 16000 -ac 1 voice-note.wav

-ar 16000 -ac 1 生成 16 kHz 单声道音频,BroadNet 的文档对语音消息和电话录音用的就是这种转换。同一条命令也适用于 .m4a。16 kHz 单声道 16 位 WAV 每秒 32,000 字节,因此 26,214,400 字节的文件上限大约能容纳 13 分钟。更长的录音可以用音频切分工具:它会算出需要切成几段,并写好 ffmpeg 命令。

2. 转写整个文件夹

import os, pathlib, subprocess
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

for src in sorted(pathlib.Path("voice-notes").glob("*.ogg")):
    wav = src.with_suffix(".wav")
    subprocess.run(["ffmpeg", "-y", "-loglevel", "error", "-i", str(src), "-ar", "16000", "-ac", "1", str(wav)], check=True)
    with open(wav, "rb") as audio:
        text = client.audio.transcriptions.create(
            model="broadnet/cohere-transcribe-arabic",
            file=audio,
            language="ar",          # use "en", "es", ... with broadnet/cohere-transcribe
        ).text
    src.with_suffix(".txt").write_text(text, encoding="utf-8")
    print(src.name, "->", text[:60])

每个 .txt 都会放在对应语音消息的旁边。想对每条收到的 WhatsApp Business 消息自动执行同样的步骤,请看 n8n WhatsApp 语音消息工作流。

费用

一条一分钟的语音消息,用阿拉伯语模型的费用是 $0.0042,用 14 种语言的模型是 $0.002。请求结束后,音频和转写文本不会被保留;参见零数据保留。

故障排查

  • 输出的是拉丁字母而不是阿拉伯文: 加上 language="ar"。BroadNet 的文档要求始终发送 language。

  • 413 错误: 文件超过了 26,214,400 字节(25 MiB)。把长录音切成 10 分钟一段的 WAV:

    ffmpeg -i long-note.ogg -ar 16000 -ac 1 -f segment -segment_time 600 part-%03d.wav
  • 上传时返回 400 或 422: 确认文件确实是 WAV 或 MP3,而不是被改名为 .wav 的 .ogg。运行上面的 ffmpeg 转换。

  • ffmpeg: command not found: 用你的包管理器安装 ffmpeg(例如 apt install ffmpeg 或 brew install ffmpeg)。

  • 429 错误: 按量付费密钥同时最多处理 4 个请求;请用一个小的并发池处理文件。参见 BroadNet 全部错误码。

关于模型、格式和准确率的更多细节,见阿拉伯语语音转文字指南。想比较其他服务商每分钟音频的收费,请看公开的语音转文字 API 价格索引,每个价格都附有来源和日期。为什么 16 kHz 对语音已经足够,背景知识见采样率。

常见问题

WhatsApp 语音消息是什么音频格式?

Ogg 容器中的 Opus 音频,保存为 .ogg。Meta 的 Cloud API 文档说,语音消息必须是用 Opus 编码的 .ogg 文件,并且只能是单声道。

可以把 .ogg 文件直接发给转写 API 吗?

BroadNet Inference 不行。它的转写端点接收 WAV 和 MP3,所以要先用 ffmpeg 转换语音消息。一条命令就能把它转成 16 kHz 单声道 WAV。

转写之后语音消息会被保存吗?

BroadNet 表示,音频和转写文本只为处理该请求而使用,不会保留。它只保留不含内容的记录,例如耗时、状态和用量,用于计费和安全。

阿拉伯语语音消息该用哪个模型?

用 BroadNet Transcribe Arabic,即 broadnet/cohere-transcribe-arabic,并把 language 设为 ar。它覆盖的另外 13 种语言用 BroadNet Transcribe,即 broadnet/cohere-transcribe。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity