Whisper API Key 获取与调用教程：语音转文字（2026）

Whisper 是 OpenAI 开源的语音识别模型，OpenAI 还提供了托管版音频转写接口。对开发者来说，最省事的做法不是自己部署模型，而是拿一个 Key，调用 /v1/audio/transcriptions，把音频文件传上去，直接拿文本。

本文讲清楚 Key 怎么获取、接口怎么调、文件有什么限制、时间戳怎么拿，以及常见的报错和隐私问题。不同网关对音频接口的支持范围不同，以站内文档为准。

说明：OpenAI、Whisper 是其权利人的商标，本文仅作技术接入说明。模型名、文件限制和计费口径可能调整，以官方文档和站内文档为准，价格以站内价格页为准。

一、Whisper API 能做什么

会议、访谈、课程录音转文字；
播客、短视频字幕初稿；
客服通话质检与关键词抽取；
语音笔记整理；
多语言音频转写与翻译（翻译接口另说）。

它不适合：强噪声环境下的高精度识别、需要说话人分离的会议、司法级录音鉴定。这些场景要在转写后加人工校对，或者选用专门的说话人分离方案。

二、获取 Whisper API Key

Whisper 没有单独的「Whisper Key」，它复用 OpenAI 平台或网关的 API Key。下文的 Whisper API Key，指的就是这把能调用音频转写接口的 Key。

方式一：OpenAI 官方

注册 OpenAI 平台账号，完成付款方式配置。
在 API Keys 页面创建 Key，按项目命名。
确认账户有可用额度。
把 Key 写入服务端环境变量。

方式二：中商起航 AI 网关

打开中商起航 AI 网关注册并登录。
进入 API 密钥页面，新建 Key。
在模型价格或站内文档确认音频转写模型是否可用。
小额充值，先用短音频跑通。

无论走哪条路径，Key 都只放服务端。浏览器或 App 前端直接持有 Key，等于把账户交给别人。

三、Base URL 与鉴权

项目	官方 OpenAI	中商起航网关
Base URL	`https://api.openai.com/v1`	`https://ai.zhongshangqihang.com/v1`
鉴权	`Authorization: Bearer <key>`	同上
接口	`/audio/transcriptions`	以站内文档为准
模型	`whisper-1` 等	以站内文档或价格页为准

网关是否完整转发音频接口、支持哪些 response_format，需要以站内文档为准。不要假设文本接口能用，音频接口就一定能用。

四、curl 调用

export WHISPER_API_KEY="sk-你的密钥"

curl "https://ai.zhongshangqihang.com/v1/audio/transcriptions" \
  -H "Authorization: Bearer $WHISPER_API_KEY" \
  -F "file=@meeting.mp3" \
  -F "model=whisper-1" \
  -F "language=zh" \
  -F "response_format=json"

注意这是 multipart/form-data，不是 JSON。用 -F 而不是 -d，否则服务端收不到文件。

五、Python 调用

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["WHISPER_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

with open("meeting.mp3", "rb") as f:
    result = client.audio.transcriptions.create(
        model="whisper-1",  # 以站内文档为准
        file=f,
        language="zh",
        response_format="verbose_json",
        timestamp_granularities=["segment"],
    )

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

language 用 ISO-639-1 代码，例如 zh、en、ja。不传时模型会自动识别，但短音频或中英混杂时容易误判，明确指定更稳。

六、文件格式与大小限制

项目	常见限制	建议
支持格式	flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav、webm	统一转 mp3 或 wav
单文件大小	25 MB（以官方文档为准）	超过就切分
采样率	无强制要求	16 kHz 单声道足够
时长	受文件大小间接限制	长音频按 10 分钟切段
多声道	支持但识别效果一般	先混音或选主声道

格式不对会直接报 400；文件过大常见 413。转码是最稳的预处理方式。

七、时间戳与输出格式

`response_format`	返回内容	适用场景
`json`	纯文本	只要文字
`text`	纯文本，响应体更简单	脚本管道
`srt`	字幕文件	视频剪辑
`vtt`	Web 字幕	网页播放器
`verbose_json`	文本、分段、语言、时长	需要时间戳

分段级时间戳用 timestamp_granularities=["segment"]；词级时间戳通常只对 whisper-1 开放，且需要 verbose_json。具体支持情况以官方或站内文档为准。

八、长音频怎么处理

超过大小限制的音频，用 ffmpeg 切分后再逐段转写：

ffmpeg -i input.mp3 -f segment -segment_time 600 \
  -ac 1 -ar 16000 -b:a 64k part_%03d.mp3

切分时注意：

尽量在静音处切，避免把词切成两半。
记录每段的起始偏移，合并时把时间戳加回去。
段与段之间留 0.5–1 秒重叠，减少边界丢字。
合并后做一次去重和标点整理。

九、常见报错

报错	原因	处理
`401`	Key 错误或未带 Bearer	检查 Key 和请求头
`404`	Base URL 或路径错	确认 `/v1/audio/transcriptions`
`400 unsupported file`	格式不支持	转 mp3 或 wav
`413`	文件过大	压缩或切分
`429`	频率或额度超限	降并发，退避重试
返回空文本	静音、音量过低、语言误判	检查音频，指定 language
超时	文件大或网络慢	切分、提高超时

十、成本控制

转写前先做静音检测，去掉空白段。
统一转成 16 kHz 单声道，减少文件体积。
长音频切段并行，但控制并发，避免 429。
先跑短样本确认语言和效果，再批量提交。
记录每次调用的音频时长，按项目对账。
失败重试要有上限，避免重复计费。

音频转写通常按分钟计费，单价以站内模型价格为准。便宜不等于省钱：格式转换、人工校对和重试都会进入总成本。

十一、准确率怎么提升

音频预处理：转 16 kHz 单声道，做轻度降噪，去掉爆音和长静音。
明确语言：中文场景传 language=zh，中英混杂时评估是否分段处理。
提供提示词：用 prompt 参数传入专有名词、人名、产品名，帮助模型对齐用词。
合理切段：按静音切，每段 5–10 分钟，避免跨段丢词。
后处理校对：数字、日期、金额、专有名词做规则校验，关键场景人工复核。
建立词表：把高频错词整理成替换表，随版本迭代。

转写准确率没有统一数字，和录音质量、口音、领域词汇关系很大。上线前用自己业务的真实音频做一组抽样测试，比看宣传参数更有意义。

十二、隐私与合规

音频可能包含姓名、电话、地址、病情等个人信息，上传前明确告知并取得授权。
敏感内容先脱敏，或改用可私有化部署的方案。
确认服务商的留存政策、日志策略和删除方式。
不要把含客户数据的音频放到公开可访问的 URL。
跨境传输要评估当地法规和企业合规要求。

常见问题

Whisper API 支持中文吗？

支持。中文转写建议显式传 language=zh，并在提示词或后处理中补充专有名词。

一个 Key 能同时调用文本模型吗？

在网关里通常可以，但音频接口是否开放要看站内文档；官方 Key 的权限也按账号和项目配置。

可以返回词级时间戳吗？

部分模型和格式支持，通常需要 verbose_json 加 timestamp_granularities。以文档为准。

音频超过 25 MB 怎么办？

用 ffmpeg 压缩或按 10 分钟切段，逐段转写后合并。切分点尽量选静音处。

转写结果可以直接商用吗？

取决于音频内容的权利、平台条款和当地法律。涉及他人录音、音乐、课程内容时，先确认授权。

下一步

先注册中商起航 AI 网关，创建测试 Key，用一段 1 分钟音频跑通 /v1/audio/transcriptions，再接入批量流程。模型与价格以模型价格为准。