Whisper API 语音转文字教程：音频转文字完整流程

语音转文字是 AI API 里最容易被低估的能力：会议录音整理、播客出文稿、客服通话质检、视频自动出字幕，全都要先过这一步。自己部署 Whisper 模型对显卡有要求，调参也繁琐，其实直接调 API 几行代码就能跑通。

这篇讲清 Whisper API 的完整用法：支持什么格式、大小限制、时间戳怎么取、长音频怎么处理，最后给一段拿来就能跑的代码。

先说结论#

• 音频在 25MB 以内：直接调 API，一个接口搞定转写和翻译
• 音频超过 25MB：先本地切片（每段 10 分钟左右）再分批调用
• 需要按句加时间戳出字幕：用 verbose_json 响应格式，返回里自带分段
• 在国内环境调用，把 base_url 指向聚合网关即可，代码不用改结构

支持的格式与限制#

Whisper API 接受这些格式：mp3、mp4、mpeg、mpga、m4a、wav、webm，单文件上限 25MB。

几个实用判断：

• 手机录音（m4a）和微信语音（amr 需先转码为 mp3/wav）都能转
• 一小时的高压缩 mp3 大约 50–60MB，超限；低码率压到 96kbps 以下可以压进 25MB
• 与其硬压码率损音质，不如切片。音质差是识别错误的最大来源

最小可用代码#

用 OpenAI SDK 调用，音频以文件对象传入：

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的密钥",
    base_url="https://api.zaimod.com/v1",
)

with open("meeting.mp3", "rb") as f:
    result = client.audio.transcriptions.create(
        model="whisper-1",
        file=f,
    )

print(result.text)

result.text 就是完整转写文本。中文识别效果很好，专有名词偶尔出错，可以在请求里加 prompt 参数给上下文提示：

result = client.audio.transcriptions.create(
    model="whisper-1",
    file=f,
    prompt="本次会议讨论：RAG 检索增强、向量数据库选型。人名：张伟、李娜。",
)

prompt 里的词会被模型优先采用，专有名词、产品名、人名靠这个纠偏，比转完再手动改省时间。

要时间戳：verbose_json#

做字幕或按段落定位时，把响应格式设为 verbose_json，返回里会带分段和时间戳：

result = client.audio.transcriptions.create(
    model="whisper-1",
    file=f,
    response_format="verbose_json",
    timestamp_granularities=["segment"],
)

for seg in result.segments:
    print(f"[{seg['start']:.1f} - {seg['end']:.1f}] {seg['text']}")

输出类似：

[0.0 - 4.2] 大家好，今天我们讨论一下向量数据库的选型。
[4.2 - 9.8] 先看召回率，再看写入性能……

拿到 start/end 秒数，转成 SRT 的 时:分:秒,毫秒 格式就是标准字幕文件，写个十行的转换函数即可。

长音频：切片处理#

超过 25MB 的录音，推荐用 ffmpeg 按 10 分钟切片，逐段转写后拼接：

# 按 600 秒切片，输出 meeting_part_001.mp3 ...
ffmpeg -i meeting_full.mp3 -f segment -segment_time 600 -c copy meeting_part_%03d.mp3

from pathlib import Path

full_text = []
for part in sorted(Path(".").glob("meeting_part_*.mp3")):
    with open(part, "rb") as f:
        r = client.audio.transcriptions.create(model="whisper-1", file=f)
    full_text.append(r.text)

print("\n".join(full_text))

附赠能力：语音翻译#

同一个接口换一个参数，能把非英语音频直接翻成英文文本（不是转写原文，是翻译）：

result = client.audio.translations.create(model="whisper-1", file=f)

做双语内容整理时很省事，但中文场景一般还是先转写原文，再交给 chat 模型做摘要或翻译，可控性更好。

计费与成本#

Whisper API 按音频时长计费，价格在各平台价格页都能查到，以 价格页 实时挂单价为准。给个体感量级：一小时会议录音的成本通常低于一次 GPT-4 级别的长文摘要，瓶颈不在钱，在于音频预处理和后处理的人工校对。

如果转写后要做摘要、要点提取，用便宜的模型接在后面就够，例如 gpt-4o-mini（$0.156 / $0.624 每百万 tokens，输入 / 输出），一小时的会议纪要后处理成本可以忽略。

常见问题#

Q：转出来的文字太啰嗦，全是口语填充词怎么办？

转写和润色分开做。先用 Whisper 拿到忠实原文，再让 chat 模型做口语转书面语的改写，不要指望语音接口直接出干净文稿。

Q：报 400 错误说文件无效？

九成是格式问题：先确认扩展名在上表支持列表里；amr、opus 等格式先用 ffmpeg 转成 mp3；文件损坏或截断也会报这个错。

Q：支持说话人分离（谁在说）吗？

Whisper API 本身不区分说话人。需要的话先本地跑 pyannote 等分离工具切出单人音轨，再分轨调用 API，最后按轨合并。

Q：并发批量处理几百条录音可以吗？

可以，注意控制并发数，遇到 429 按退避重试即可，处理思路参考 大模型 API 429 报错：原因、重试与并发调优。

延伸阅读#

• OpenAI API Key 怎么购买：国内开发者完整指南
• 大模型 API 报错速查：401、403、500、超时排查方法
• OpenAI 兼容协议是什么：一个 base_url 通吃 175 个模型
• 注册 zaimod，5 分钟跑通第一次转写请求