---
title: "WhatsApp 语音消息（.ogg）转文字 API 教程 | BroadRouter"
description: "用 ffmpeg 把 WhatsApp 的 .ogg 语音消息或手机的 .m4a 录音转成 WAV，再用一次 API 调用转写成阿拉伯语或其他 13 种语言的文字。"
url: https://broadrouter.com/zh/guides/transcribe-whatsapp-voice-notes/
lang: zh-Hans
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。[阅读英文原文](https://broadrouter.com/guides/transcribe-whatsapp-voice-notes/)（2026-11-16 更新）。

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

更新于 2026-11-16

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\. 转换单个文件

```bash
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 分钟。更长的录音可以用[音频切分工具](https://broadrouter.com/tools/audio-splitter-ffmpeg/)：它会算出需要切成几段，并写好 ffmpeg 命令。

## 2\. 转写整个文件夹

```python
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 语音消息工作流](https://broadrouter.com/zh/guides/n8n-whatsapp-voice-note-transcription/)。

## 费用

一条一分钟的语音消息，用阿拉伯语模型的费用是 $0.0042，用 14 种语言的模型是 $0.002。请求结束后，音频和转写文本不会被保留；参见[零数据保留](https://broadrouter.com/zh/privacy/)。

## 故障排查

-   **输出的是拉丁字母而不是阿拉伯文：** 加上 `language="ar"`。BroadNet 的文档要求始终发送 `language`。
    
-   **413 错误：** 文件超过了 26,214,400 字节（25 MiB）。把长录音切成 10 分钟一段的 WAV：
    
    ```bash
    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 全部错误码](https://broadrouter.com/zh/guides/errors-and-retries/)。
    

关于模型、格式和准确率的更多细节，见[阿拉伯语语音转文字指南](https://broadrouter.com/zh/guides/arabic-speech-to-text-api/)。想比较其他服务商每分钟音频的收费，请看公开的[语音转文字 API 价格索引](https://broadrouter.com/data/speech-to-text-api-prices/)，每个价格都附有来源和日期。为什么 16 kHz 对语音已经足够，背景知识见[采样率](https://broadrouter.com/zh/glossary/sample-rate/)。

## 本指南涉及的术语

[WAV](https://broadrouter.com/zh/glossary/wav/)

WAV（Waveform Audio File Format，又称 WAVE）是建立在微软与 IBM 的 RIFF 格式之上的音频容器。它通常存放未压缩的线性 PCM 样本，因此大小可以预测：每秒字节数 = 采样率 × 每样本字节数 × 声道数。

[按量付费（pay-as-you-go）](https://broadrouter.com/zh/glossary/pay-as-you-go/)

按量付费是一种计价模式：你只为实际用量付费，按 token、请求次数或音频分钟等单位计量，没有订阅费，也没有最低消费承诺。大多数大模型 API 都这样计费，从预付余额中扣减或定期开具账单。

[并发（concurrency）](https://broadrouter.com/zh/glossary/concurrency/)

并发（concurrency）是客户端在同一时刻正在进行中的请求数。大模型 API 往往按密钥或套餐单独限制并发，与每分钟请求数分开计算，因为每个未完成的请求在响应结束前都会占用 GPU 资源。

[工具调用（tool calling / function calling）](https://broadrouter.com/zh/glossary/tool-calling/)

工具调用（也叫函数调用，function calling）是大模型 API 的一项功能：模型返回一个结构化请求，要求执行开发者定义的某个函数，并附上 JSON 参数。应用执行该函数并把结果发回；模型自己从不执行代码。

[速率限制（rate limit）](https://broadrouter.com/zh/glossary/rate-limit/)

速率限制是 API 对客户端在一个时间窗口内的使用量设定的上限，例如每分钟请求数或每分钟 token 数。超出限制的请求会被拒绝，通常返回 HTTP 429 Too Many Requests，直到用量回落到限制以下。

[Ogg Opus](https://broadrouter.com/zh/glossary/ogg-opus/)

Ogg Opus 是用 Opus 编解码器（RFC 6716）编码、存放在 Ogg 容器（RFC 7845）中的音频。它专为低码率下的语音和实时交互音频设计，也是 WhatsApp 语音消息使用的格式，文件通常为 .ogg 或 .opus。

## 常见问题

### 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。

## 相关指南

-   [在 n8n 中转写 WhatsApp 语音消息](https://broadrouter.com/zh/guides/n8n-whatsapp-voice-note-transcription/)
-   [阿拉伯语语音转文字 API 分步教程](https://broadrouter.com/zh/guides/arabic-speech-to-text-api/)
-   [BroadNet Inference 错误码，以及什么时候该重试](https://broadrouter.com/zh/guides/errors-and-retries/)

用你的真实业务负载试一试。新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-transcribe-whatsapp-voice-notes&utm_content=page-cta) ·

**来源**

-   [BroadNet Inference API 参考文档：转写与 ffmpeg 转换（英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-transcribe-whatsapp-voice-notes&utm_content=sources#requests)
-   [BroadNet Inference 价格（英文）](https://inference.broadnet.ai/pricing?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-transcribe-whatsapp-voice-notes&utm_content=sources)
-   [Meta WhatsApp Cloud API：音频消息（语音消息为使用 Opus 编码的 OGG；核对于 2026-11-14）](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/audio-messages)
-   [FFmpeg 格式文档：segment 复用器（核对于 2026-11-14）](https://ffmpeg.org/ffmpeg-formats.html#segment)
